Drivers — the substrate contract

Every substrate a region touches — secrets, queue, inference, storage, runtime — is behind a driver interface in @usenaive/region-core. Services never import a provider SDK directly; they call a driver resolved from a NAIVE_*_DRIVER env var. The interfaces are 1:1 with the cloud implementations they abstract, so the cloud code paths port to a Tower without behavior change.

The five selectors

Selector	Values	Cloud default	Tower default
`NAIVE_SECRETS_DRIVER`	`kms` · `vaultd` · `file`	`kms`	`vaultd`
`NAIVE_QUEUE_DRIVER`	`sqs` · `pg`	`sqs`	`pg`
`NAIVE_INFERENCE_DRIVER`	`openrouter` · `vllm` · `auto`	`openrouter`	`auto`
`NAIVE_STORAGE_DRIVER`	`s3` · `fs`	`s3`	`fs`
`NAIVE_RUNTIME_DRIVER`	`ecs` · `local`	`ecs`	`local`

Defaults come from resolveDriverSelection(): with NAIVE_BUILD=tower the base is the Tower set, otherwise the cloud set. Any individual NAIVE_*_DRIVER value overrides its base. (There are also kv and cron drivers — both Postgres on a Tower — used for the relay cursor and scheduled sweeps.)

The runtime pool is a selectable driver, not a fixed dependency. The cloud default is the ECS warm pool; a Tower runs local (docker-compose service instances). Neither is privileged by the code.

`NAIVE_SECRETS_DRIVER` — the Credential Vault

The SecretsDriver is envelope encryption. Regardless of driver the stored value layout is identical — nonce(12) || tag(16) || ciphertext, AES-256-GCM, with an encryption context of exactly { company_id, tenant_user_id } — so vault_entries rows are portable between substrates.

Value	Where	Notes
`kms`	Cloud	AWS KMS envelope driver. Implements the optional `reveal`. Needs `NAIVE_VAULT_KEK_ID`.
`vaultd`	Tower	Thin UNIX-socket client to the closed TPM-rooted daemon. No `reveal`.
`file`	Dev/CI	HKDF tenant-KEK rooted in a local key file. No TPM. Implements `reveal`.

generateDataKey / decryptDataKey / reEncryptDataKey are the required methods; decryptDataKey must reject on a mismatched context. reveal is optional.

Reveal is absent on vaultd (Tower). reveal? is an optional method on SecretsDriver; the vaultd driver does not implement it and vaultd compiles the method out entirely (towerbuild). The vault reveal route therefore returns 501 on a Tower — plaintext never leaves the box. kms and file implement reveal; vaultd does not. See Security model and Vault encryption.

`NAIVE_QUEUE_DRIVER` — durable queues

sqs (cloud) and pg (Tower) implement the same QueueDriver: create/delete, send (with FIFO group id + content dedup + delay), receive with a visibility timeout, delete, purge, and attributes. The pg driver implements pgmq semantics on plain SQL (SKIP LOCKED, read_ct, archive) rather than requiring the pgmq extension — a documented deviation, since FIFO group-key withholding needs custom SQL either way. It runs on stock postgres:16, does FIFO group-withholding + content dedup, and moves a message to the DLQ at maxReceive = 5.

`NAIVE_INFERENCE_DRIVER` — chat completions

An OpenAI-compatible InferenceDriver (non-streaming, streaming, and listModels). Both the llm primitive and the agent proxy (/v1/proxy/*) go through the same router (packages/api/src/services/llm.ts → drivers.ts), so a box has one inference source, not two.

Value	Behavior
`openrouter`	Forward to OpenRouter. Needs `OPENROUTER_API_KEY`.
`vllm`	Forward to a local vLLM (`NAIVE_VLLM_URL`, default `http://vllm:8000/v1`).
`auto`	Route a model to vLLM when the box serves it, else fall through to OpenRouter (via the gateway on a Tower).

The three box inference modes

On a Tower the mode (persisted per box in boxes.inference_mode, chosen in the dashboard Settings → Inference or the onboarding wizard) decides where model calls actually go. The effective mode resolves as env override (NAIVE_INFERENCE_MODE / NAIVE_LLM_FORWARD / NAIVE_INFERENCE_DRIVER) → the persisted choice → cloud.

Mode	Provider key on the box?	Billing	How it routes
`cloud` (default)	No	Owner’s cloud credits	`/v1/llm/` + `/v1/proxy/` are forwarded through the egress-gateway to Naïve Cloud, which injects the owner’s sealed cloud key (vaultd — never on the box) and meters. Requires the box claimed + a gateway forward named by `NAIVE_LLM_FORWARD` (e.g. a `cloud` forward with `vaultKey: cloud_api_key`). The box does zero local billing on this path.
`local`	No	None (on-box)	The `vllm` driver serves the model on the box; Hermes points at it via `HERMES_LOCAL_MODEL`. Fully offline.
`byo`	Yes (your key)	Your provider account	The box calls the provider directly with `OPENROUTER_API_KEY` / `ANTHROPIC_API_KEY` (today’s simplest path).

If a box is set to cloud but no forward is wired, it degrades to the local provider driver (BYO key) rather than failing — so cloud is safe as a default.

Honest hardware feasibility for local models. Running a model on the box needs real VRAM. A 4 GB Jetson Nano cannot serve a useful LLM — use cloud (credits) or byo. A Jetson Orin (16–64 GB unified memory) can serve a small quantized model (≈3–8B, AWQ/GGUF) at modest speed (expect seconds-per-response, not instant) — fine for light tasks, not for large-context or high-throughput work. Bigger models want a discrete NVIDIA GPU on an x86 box. Enable local inference with the opt-in vllm compose profile (docker compose … --profile vllm up -d) after setting NAIVE_INFERENCE_DRIVER=vllm

VLLM_MODEL (and a JetPack/ARM64 VLLM_IMAGE on Jetson).

`NAIVE_STORAGE_DRIVER` — object storage

StorageDriver = put / get / presigned URL / delete.

s3 (cloud) — AWS S3, real presigned URLs.
fs (Tower) — files under NAIVE_STORAGE_FS_ROOT (e.g. /data/storage). Fetch URLs are HMAC-signed and served by /storage/local/*key; it guards against path traversal.

`NAIVE_RUNTIME_DRIVER` — the runtime pool

RuntimePoolDriver is the spec’s “supervisor”: claim/release/get/list of runtime instances for tenants.

ecs (cloud) — the ECS warm pool (hot-claim an idle task).
local (Tower) — the box’s compose agent-runtime service (the real Hermes agent-container). It boots in POOL_MODE=idle; a claim HOT-CLAIMS it in place by POSTing /provision (identical contract to the ECS path — no restart), then records the binding so sidecarFetch/getContainerForSubject resolve it. Point the driver at it with NAIVE_LOCAL_RUNTIME_URL (default http://agent-runtime:3100) + CONTAINER_AUTH_TOKEN.

On a Tower each runtime is started with a per-operator NAIVE_RUNTIME_TOKEN and addresses the egress gateway as its only route off-box. The agent-container image is built for arm64 and amd64 (scripts/build-agent-container.sh).

Local inference. Set HERMES_LOCAL_MODEL (+ NAIVE_VLLM_URL) to point the box’s Hermes runtime at a local vLLM OpenAI-compatible endpoint — the CEO’s own reasoning then stays on-box, complementing the auto inference driver that keeps the llm primitive local too.

The GovernorClient contract

Drivers move bytes; they never make the trust decision. That decision is a wire call to the closed governor, and the only way to make it is GovernorClient / the governorCall() wrapper in @usenaive/region-core (pinned in PROTOCOLS.md §1).

interface GovernorClient {
  evaluate(req: EvaluateRequest): Promise<Verdict>;         // allow | deny | freeze
  replayAuthorize(req: ReplayAuthorizeRequest): Promise<ReplayAuthorization>;
  budgetReserve(req: BudgetReserveRequest): Promise<BudgetReservation>;
  budgetRelease(referenceId: string): Promise<void>;
}

Transport — localhost HTTP/1.1 + JSON to GOVERNOR_URL (default http://governor:8700), authenticated with a shared GOVERNOR_TOKEN bearer, ajv-validated on both ends.
Fail-closed is baked in. governorCall() bounds every call (500 ms connect / 2 s total). Governor unreachable or timeout throws GovernorUnavailableError; there is no verdict caching and no call site can default to library behavior. The API maps it to 403 enforcement_unavailable; the gateway maps it to deny-all.
A Verdict carries decision, a target of live | sandbox (whether an allowed action routes to real rails or the sandbox adapter), and — on freeze — an approval_id for a persisted pending row.

Writing a driver

Implement the interface from @usenaive/region-core (e.g. SecretsDriver, QueueDriver). Match the exact method shapes; for secrets, preserve the nonce(12) || tag(16) || ciphertext layout and reject on context mismatch so vault_entries rows stay portable.
Register it behind the selector. The api resolves drivers in packages/api/src/drivers.ts via lazy getters keyed on resolveDriverSelection(process.env); add your branch there (and export a create…Driver(opts) factory from your package, as the bundled drivers do).
Never talk to the governor yourself except through GovernorClient — enforcement stays in the closed engine, and the fail-closed guarantee depends on the single wrapper.
Add a conformance capability. Tag any leg that needs a real third-party key with hasCapability() so a missing key is reported BLOCKED, never mocked (see Conformance).
Ship a README with the five-section template (Purpose / Consumers / Configuration / Run standalone / Place in the topology) — the docs gate checks it.

The set of selectors is the source of truth in packages/core/src/drivers.ts (DRIVER_ENV_VARS). A CI gate greps this page for every one: NAIVE_SECRETS_DRIVER, NAIVE_QUEUE_DRIVER, NAIVE_INFERENCE_DRIVER, NAIVE_STORAGE_DRIVER, NAIVE_RUNTIME_DRIVER.

Getting Started

Self-hosting (Tower)

Agent Profiles

Architecture

Templates

Migration Guides

Integrations

Primitives

Drivers — the substrate contract

The five selectors

`NAIVE_SECRETS_DRIVER` — the Credential Vault

`NAIVE_QUEUE_DRIVER` — durable queues

`NAIVE_INFERENCE_DRIVER` — chat completions

The three box inference modes

`NAIVE_STORAGE_DRIVER` — object storage

`NAIVE_RUNTIME_DRIVER` — the runtime pool

The GovernorClient contract

Writing a driver

​The five selectors

​NAIVE_SECRETS_DRIVER — the Credential Vault

​NAIVE_QUEUE_DRIVER — durable queues

​NAIVE_INFERENCE_DRIVER — chat completions

​The three box inference modes

​NAIVE_STORAGE_DRIVER — object storage

​NAIVE_RUNTIME_DRIVER — the runtime pool

​The GovernorClient contract

​Writing a driver

The five selectors

`NAIVE_SECRETS_DRIVER` — the Credential Vault

`NAIVE_QUEUE_DRIVER` — durable queues

`NAIVE_INFERENCE_DRIVER` — chat completions

The three box inference modes

`NAIVE_STORAGE_DRIVER` — object storage

`NAIVE_RUNTIME_DRIVER` — the runtime pool

The GovernorClient contract

Writing a driver