boatramp.cfg schema

boatramp.cfg is the server config, read by boatramp serve. It is RON. Every value can also be set as a flag or an environment variable, which take precedence. The whole file is optional — serve runs with defaults without it.

boatramp serve --config boatramp.cfg

Precedence for any value: flag / environment variable > boatramp.cfg > built-in default.

Top-level sections, all optional:

serve

Warning: with no auth_root_* key configured, control-plane auth is disabled. Under the default multi-tenant posture, serve refuses to start that way on a non-loopback addr. Configure a key, bind 127.0.0.1, or select a looser security posture.

serve.signer

Selects an external signer so the root key never sits in process memory. Written as a RON enum. Credentials (tokens, PINs) come from the named environment variables, never this file.

serve: ( signer: Vault(
    address: "https://vault:8200",
    key: "boatramp-root",
    token_env: "VAULT_TOKEN",
    alg: Es256,
) )

See Hold the signing key in a KMS/HSM/Vault.

serve.s3_credential (v0.6.1)

A node-level base S3 credential sourced from the sealed secrets store instead of the ambient AWS_ACCESS_KEY_ID / AWS_SECRET_ACCESS_KEY env chain. One source feeds both consumers — the S3 blob object backend (--blobs s3) and the AWS blob-upload cloud minter (serve.s3_ingress_cloud) — because it is the same bucket key. Absent ⇒ the ambient AWS env chain (unchanged, non-breaking).

serve: ( s3_credential: (
    access_key_id: "tid_public_akid",              // a public identifier — plain config
    secret_access_key: "boatramp:tigris-secret",   // a sealed secret REFERENCE, not the secret
) )

Seal the secret once with boatramp secrets set (default project), then reference it here.

• Fail-closed: a boatramp: / env: ref configured with no [secrets] envelope is a startup error — boatramp does not silently fall back to the ambient env chain (which would mask the misconfig).
• Cluster caveat: blob storage is built before the replicated control plane, so a boatramp: (KV-backed) ref is refused fail-closed on a cluster node (the sealed store is single-node) — use an env:<VAR> ref there. The AWS cloud minter is likewise single-node this release.

See Encrypt secrets at rest.

serve.blob_fallback (v0.6.2)

A read-only secondary blob backend enabling a zero-downtime blob-backend switch (fs→cloud, provider→provider, region→region). While it is attached, serving reads the primary (the [serve] blobs / s3_* / gcs_* / azure_* fields) first and, only on a definitive miss for a boatramp-owned key, falls through to this secondary — so there is no serving gap while the old backend drains into the new one. A transient primary error propagates (never serves stale/secondary bytes on a blip); the fall-through is prefix-allowlisted to content-addressed blobs, hblob/, and mqgp/ (a control-plane-shaped key never resurrects off the secondary); keys are forwarded byte-identical so tenant isolation is preserved. put and delete are primary-only — the secondary is strictly read-only, never written.

This block takes the same backend-descriptor shape as the primary — a blobs selector plus the matching per-backend option fields — plus its own optional s3_credential and a read timeout.

serve: (
    blobs: s3,                                  // the NEW (primary) backend
    s3_bucket: "acme-blobs-new",
    s3_region: "auto",
    blob_fallback: (                            // the OLD backend to read through
        blobs: fs,
        secondary_timeout_secs: 5,
    ),
)

This is a bounded transition aid. Rollout: deploy primary = new, blob_fallback = old, drain the old backend into the new one with boatramp blob migrate (a bare blob migrate with a blob_fallback configured drains the fallback → primary), then remove this block and restart. While a fallback is attached the node logs a prominent transition-mode WARNING at startup and blob GC refuses to prune (a prune returns 409) — a union list over a primary-only delete would otherwise reclaim a secondary-only object that a read could resurrect. See Switch the blob backend with zero downtime.

serve.s3-upload-ingress (v0.5.9)

The external S3 upload ingress — the daemon-config side of letting a client outside the wasm sandbox upload directly into a project’s blob container over the S3 protocol, which the guest then reads unchanged through wasi:blobstore. These are the [serve]-level knobs; the guest capability, operator CLI, and per-recipe UX are covered in Ingest large uploads over S3.

serve: (
    addr: "0.0.0.0:8080",                       // control plane / site edge
    s3_ingress_addr: "0.0.0.0:9000",            // the dedicated S3 face
    s3_ingress_secret_file: "/etc/boatramp/s3-ingress.key",
    s3_ingress_public_url: "https://uploads.example.com",
    s3_ingress_mint_max_ttl_secs: 3600,         // TTL ceiling (default 1h)
    s3_ingress_mint_max_bytes: 104857600,       // per-cred object cap (100 MiB)
)

When the node’s blob backend is a cloud object store, add serve.s3_ingress_cloud so the mint brokers a native, scoped, short-lived cloud credential and the client uploads directly to the real store (bytes never transit the node) instead of the local face.

serve.s3_ingress_cloud (v0.5.9)

Cloud-brokering identity for the upload minter. Only the fields for the active blob backend are consulted; absent ⇒ the local S3 face mints. See Ingest large uploads over S3 — per-cloud setup.

security

The operator security posture: a profile preset plus per-knob overrides. Absent means the strict multi-tenant default. This section is operator-only — it is never part of site config, so a site writer cannot relax it. Inspect the resolved posture with boatramp security explain.

Override knobs (byte caps: 0 = unlimited):

security.projects (per-project posture, v0.4.7)

A [security.projects.<project>] block overrides the four tenancy/capability sub-knobs for one project only, layered over the resolved fleet posture. It lets a single serve process host a strict-isolation project beside a looser one on a shared, multi-project machine.

security: (
    profile: "multi-tenant",                 // the fleet default
    projects: {
        "acme-preview": (                     // looser, just this project
            allow_cross_tenant_db: true,
            allow_guest_mint_capability: true,
        ),
    },
)

Only these four in-project knobs are per-project-overridable; every other knob (egress, upload caps, domain verification, guest-admin surfaces, …) stays fleet-wide. Each Some field of the override wins; the rest fall through to the fleet posture, so the override composes with the global one. Cross-project isolation is structural (project = database) — never a knob, so a per-project override can only tune that project’s own in-project strictness and its guests’ capability-mint ceiling, never its reach into another project. These four knobs are also BOATRAMP_SECURITY_* env-settable at the fleet level (see env.md); per-project overrides are config-file only.

See Choose & inspect a security posture and The security posture model.

secrets

Envelope-encrypt cluster-managed certificate private keys so they are never cleartext in the replicated control plane. Absent means keys are stored cleartext.

See Encrypt secrets at rest.

handlers

Wasm handler runtime. Parsed always, consumed only with the handlers feature.

bindings.sql fields: dir, url, admin_url, replica_url, token_env, admin_token_env, preview_mode (empty | branch | shared), preview_init, databases. See Use handler bindings.

Memory ceilings per lane

Every lane defaults to a 64 MiB per-component linear-memory ceiling. The *_max_memory_mb knobs raise that ceiling for a lane; the ceiling is the maximum any component on the lane may use, not a per-component allocation. A component right-sizes itself down from the ceiling with its own limits.memory_mb (per-function) or the site’s max_memory_mb; a component with neither inherits the lane ceiling. So the model is: set the lane ceiling high enough for the heaviest component, and let each component cap itself lower where it should. A per-component value above the lane ceiling is clamped to it — a component can never raise its own memory above the operator-set lane ceiling (fail-closed, operator-gated). Leaving every knob unset keeps the historical 64 MiB everywhere.

Cost: without pooling there is no up-front reservation — each invocation sizes its store to its effective ceiling on demand. With pooling = true the allocator reserves roughly max-lane-memory × total-slots of virtual address space up front (slots = the sum of the three lanes’ concurrency), so a raised ceiling enlarges that reservation; the node logs the estimate at startup and fails loudly if the reservation can’t be made, rather than OOM-ing on the first invocation. Prefer raising only async_max_memory_mb (the durable lane) for heavy jobs, so the tighter sync/streaming lanes don’t inflate the reservation.

A component that exceeds its effective ceiling at runtime no longer dead-letters as an opaque trap: the terminal outcome and the /metrics boatramp_handler_invocations_total{outcome="out-of-memory"} counter read out-of-memory, so memory exhaustion is distinguishable from a logic crash.

External SQL databases

bindings.sql.databases is a map of name → external database, each a Postgres/MySQL a guest opens by that name (sql.open("<name>")) instead of a per-site libsql one. Needs the sql-postgres / sql-mysql build feature. Isolation is the operator’s — such a database is shared across every guest granted the sql binding — so it bypasses the per-site libsql boundary; libsql stays the managed default. A name here shadows the same name on the libsql default.

Each database has one of two sources, mutually exclusive:

• Bring-your-own (url_env) — you run the database anywhere; boatramp reads its connection URL from an env var.
• Compute-backed (compute) — the database is a compute workload boatramp runs (see compute). boatramp resolves the workload’s live endpoint on demand and builds the connection, so there is no URL to hand-map and it follows the workload across restarts. With password_env set you bring the credential; omit it and boatramp fully manages the credential — it generates a strong password once, seals it with the secrets envelope, injects it into the DB workload’s server-init env at launch, and connects the handler with it, so you set no DB secret at all. A managed database therefore requires a [secrets] envelope (it refuses to store a credential it cannot seal) and a persistent volume on the DB workload (so the password the server was initialized with survives a restart).

cluster

Self-hosted Raft cluster. Parsed always, consumed only with the cluster feature. The peer mesh runs over RFC 7250 raw-public-key mutual TLS. A cluster is defined by its root of trust — there is no peer map; nodes self-identify and join by redeeming a ticket.

The node id is derived from the node’s mesh key — there is no node_id field. Founding and joining are driven from the command line: serve --cluster-init founds a new cluster, serve --cluster-join <ticket> joins one (from cluster add). The old static-genesis fields (node_id, peers, voters, bootstrap) have been removed.

Warning: a non-loopback listen refuses to start with an empty trust set (found with --cluster-init or join with --cluster-join <ticket>). Never point two nodes at one store_dir.

See Deploy a self-hosted cluster and Mesh identity & the single root anchor.

compute

Container / microVM execution backends. Present ⇒ this node advertises compute capacity to the scheduler; backends are capability-detected: the native container backend on Linux; the KVM microVM (vmm-embedded) where /dev/kvm exists; the macOS-native microVM (vmm-vz) on Apple silicon + macOS 15+, which boots each replica as a Linux VM via Virtualization.framework (strong per-VM isolation, the same user surface as the KVM backend — no config change); and remote docker wherever a Docker daemon is reachable. macOS 26 is recommended for the vmm-vz backend: macOS 15’s vmnet cannot do container-to-container networking, so multi-replica cross-VM comms needs 26 (single-node serve works on 15). Nothing in the spec, CLI, or the fields below differs by backend — the environment difference lives behind the backend.

The kernel-signing keys and hash allow-list are static (host-access-gated) trust anchors — the fleet default kernel itself is a dynamic setting (compute.default_kernel), changeable without a restart but verified against these anchors at boot. See Run a container or microVM.

Note: vcpus, mem_mib, and the default kernel are also settable at runtime via boatramp config — the boatramp.cfg values are the baseline a dynamic override layers over.