Serving Branchyard harnesses
Branchyard runs coding
harnesses on branches and gives each one a skill and an SDK per granted
connector instead of upstream credentials. Anvil is the other half: its fleet
gateway (anvil serve mcp <workspace> --fleet --http <port>) holds every
upstream authorization, checks each call against the branch’s grant, and
records it. The packaged CLI and SDKs a harness uses call that gateway and
nothing else.
The contract between the two repositories is Branchyard’s
docs/connectors.md. ADR-0029
records Anvil’s side of it and lists where it differs. Branchyard’s effect
ledger (its docs/effects.md) adds a second contract: what undoing each
operation means, reported on every call.
ADR-0030 records Anvil’s side of that one;
Effects and undo below is the reference.
Prerequisites
Section titled “Prerequisites”- Node.js 22.17 or later, pnpm 10, and a built checkout:
pnpm install --frozen-lockfile && pnpm build. - Python 3.9 or later for the Python SDK.
- Compiled bundles with approved operations (
anvil compile,anvil approve).
anvil below is node packages/cli/dist/bin-anvil.js (or pnpm anvil).
Run the fixture
Section titled “Run the fixture”examples/github-mini/ is a small GitHub-shaped API (issues list, get,
create, and update; issue comments list, create, and delete; releases create,
update, delete, and get by tag; pulls list) with a manifest that approves
every operation, marks issues.create as a mutation that needs
confirmation, and declares each write’s effect class: creating a comment is
reversible, creating an issue is compensable, and creating a release is
irreversible with a draft form. One script drives the whole flow against a
mock upstream:
node examples/github-mini/e2e.mjs # add --keep to keep the work directoryIt prints one JSON line and exits 0 when every check holds:
{"ok":true,"work":"/tmp/anvil-branchyard-e2e-…","checks":[{"name":"index lists github","ok":true},{"name":"python lists issues through the gateway","ok":true,…},{"name":"issues.create is refused policy_denied","ok":true,…},…]}After the read-only turn it mints a second turn’s token granting
github:write and exercises the effect contract over MCP and REST (see
Effects and undo). The same script runs in Anvil’s suite
(packages/cli/src/branchyard-e2e.test.ts).
Drive it step by step
Section titled “Drive it step by step”These are the commands e2e.mjs runs, in order, for a test harness that wants
to own each process (Branchyard’s Rust tests, for example). $WORK is a
scratch directory and $ANVIL is node packages/cli/dist/bin-anvil.js, run
from the Anvil checkout.
-
Start the mock upstream. It prints
{"url":"http://127.0.0.1:<port>"}, accepts onlyAuthorization: Bearer <token>, and lists every request it served atGET /__requests.Terminal window node examples/github-mini/mock-upstream.mjs --port 0 --token e2e-upstream-pat -
Compile the spec with its server pointed at the mock. The bundle’s directory name is its connector id.
Terminal window mkdir -p "$WORK/src"sed "s#https://api.github.example#$MOCK_URL#" examples/github-mini/openapi.yaml > "$WORK/src/openapi.yaml"$ANVIL compile "$WORK/src/openapi.yaml" --manifest examples/github-mini/anvil.yaml --out "$WORK/workspace/github" -
Package the connector and write the index for a
github:readgrant.Terminal window $ANVIL package harness "$WORK/workspace/github" --out "$WORK/home/connectors/github"echo '[{"connector":"github","operations":["*"],"mode":"read"}]' > "$WORK/grants.json"$ANVIL connectors index --grants "$WORK/grants.json" --out "$WORK/home/connectors/INDEX.md" "$WORK/workspace/github" -
Make the yard’s signing key and JWKS (Branchyard’s broker does this for a real yard), and the vault key.
Terminal window node examples/github-mini/yard-keys.mjs keygen "$WORK/yard" # writes signing.jwk.json (0600) and jwks.jsonnode -e 'process.stdout.write(require("crypto").randomBytes(32).toString("hex"))' > "$WORK/vault.key"chmod 600 "$WORK/vault.key" -
Serve the workspace in branchyard mode. The audience is the gateway’s own
/mcpURL, so pick the port first.Terminal window ANVIL_INBOUND_AUTH_MODE=branchyard \ANVIL_INBOUND_ISSUER=branchyard:local:e2e \ANVIL_INBOUND_AUDIENCE=http://127.0.0.1:$PORT/mcp \ANVIL_INBOUND_JWKS_URI=file://$WORK/yard/jwks.json \ANVIL_VAULT_KEY_FILE=$WORK/vault.key \ANVIL_VAULT_DIR=$WORK/vault \ANVIL_AUDIT_FILE=$WORK/audit.jsonl \ANVIL_ALLOWED_HOSTS=127.0.0.1 \$ANVIL serve mcp "$WORK/workspace" --fleet --http $PORTIt is ready when
GET http://127.0.0.1:$PORT/healthzanswers 200. -
Mint a turn’s token (Branchyard’s job; the fixture’s stand-in is below) and write it to a 0600 file.
Terminal window node examples/github-mini/yard-keys.mjs mint "$WORK/yard" \--iss branchyard:local:e2e --aud http://127.0.0.1:$PORT/mcp --sub local:e2e-person \--tenant e2e --branch main --turn 1 \--grants '[{"connector":"github","operations":["*"],"mode":"read"}]' > "$WORK/turn.token"chmod 600 "$WORK/turn.token" -
Connect the person’s account. GitHub-mini authenticates with a bearer the person already holds, so it is a key connection read from stdin. The connect routes take only the person’s connect token (
by connectmints it), never the turn’s token a harness holds.Terminal window node examples/github-mini/yard-keys.mjs mint "$WORK/yard" \--iss branchyard:local:e2e --aud http://127.0.0.1:$PORT/mcp --sub local:e2e-person \--tenant e2e --purpose connect --grants '[]' > "$WORK/connect.token"chmod 600 "$WORK/connect.token"printf '%s\n' e2e-upstream-pat | $ANVIL connect "$WORK/workspace" github \--gateway http://127.0.0.1:$PORT/mcp --token-file "$WORK/connect.token" --api-key-stdin -
Act as the harness: the packaged Python SDK and CLI with only the two variables Branchyard sets.
Terminal window export ANVIL_GATEWAY_URL=http://127.0.0.1:$PORT/mcp ANVIL_GATEWAY_TOKEN_FILE=$WORK/turn.tokenPYTHONPATH="$WORK/home/connectors/github/python" python3 -c 'from anvil_github import GithubClient, AnvilErrorc = GithubClient()print(c.list_issue(owner="octo", repo="hello"))try:c.create_issue(owner="octo", repo="hello", title="x", confirm=True)except AnvilError as e:print(e.code, e.details["code"])'"$WORK/home/connectors/github/bin/github" pulls list --owner octo --repo helloThe first call prints the two mock issues. The second prints
policy_denied policy/grant_denied, and the mock’s/__requestsshows noPOST. -
Read the audit log. Each call is one line (shortened here; every line also carries
effect_class,ledger_id, andstaged_for):{"time":"…","sub":"local:e2e-person","by_tenant":"e2e","by_branch":"main","by_turn":"1","connector":"github","account":"default","operation":"github.issues.list","decision":"allowed","grant":{"index":0,"connector":"github","operations":["*"],"mode":"read"},"upstream_status":200,"latency_ms":17,"input_sha256":"sha256:…","error_code":null,"rule":null,"dry_run":false,"trace_id":"trace_…"}{"time":"…","sub":"local:e2e-person",…,"operation":"github.issues.create","decision":"denied","grant":{"index":0,…,"mode":"read"},"upstream_status":null,…,"error_code":"policy_denied","rule":"policy/grant_denied",…}
Reference
Section titled “Reference”Gateway environment
Section titled “Gateway environment”| Variable | Meaning |
|---|---|
ANVIL_INBOUND_AUTH_MODE=branchyard |
Verify per-turn EdDSA tokens and enforce their grant. Only anvil serve mcp --fleet --http accepts this mode; the generated servers refuse to boot with it. |
ANVIL_INBOUND_ISSUER |
The yard’s issuer: its server URL, or branchyard:local:<yard id>. |
ANVIL_INBOUND_AUDIENCE |
The gateway’s canonical /mcp URL: HTTPS, or HTTP on a loopback host. |
ANVIL_INBOUND_JWKS_URI |
The yard’s JWKS: https://…/.well-known/jwks.json, or file://…/.branchyard/gateway/jwks.json (read on every verification). |
ANVIL_VAULT_BACKEND |
file (the default) or firestore. See Vault backends. |
ANVIL_VAULT_KEY_FILE |
file backend. Required. A file only its owner can read holding a 32-byte key (raw, 64 hex characters, or base64). Refused with firestore. |
ANVIL_VAULT_DIR |
file backend. Where encrypted connections live. Default ~/.anvil/gateway/vault. Refused with firestore. |
ANVIL_VAULT_KMS_KEY |
firestore backend. Required. The Cloud KMS crypto key, projects/P/locations/L/keyRings/R/cryptoKeys/K (not a key version). |
ANVIL_VAULT_FIRESTORE_COLLECTION, ANVIL_VAULT_FIRESTORE_DATABASE, ANVIL_VAULT_FIRESTORE_PROJECT |
firestore backend, optional. Defaults: anvil_vault, (default), and the KMS key’s project. |
ANVIL_AUDIT_FILE |
Append one JSON line per call here (created 0600). Unset: no audit log. |
ANVIL_GATEWAY_PUBLIC_URL |
The base for /connect/callback when it differs from the audience’s origin. |
ANVIL_LEDGER |
The idempotency ledger. The fleet listener boots it through the same composition root as every other surface, so firestore://PROJECT/DATABASE/NAMESPACE selects the Firestore ledger and an unknown scheme or a malformed URI stops the start. Unset, the ledger is in memory, which is for dev. |
ANVIL_SHUTDOWN_GRACE_SECONDS |
On SIGTERM the listener stops accepting connections, answers new work 503 (and /readyz not ready), lets calls already running finish for this many seconds, then closes and exits 0. Default 8, under Cloud Run’s 10-second window. An integer from 0 to 3600; anything else stops the start. |
ANVIL_CONNECT_<CONNECTOR>_CLIENT_ID, _CLIENT_SECRET |
The gateway’s OAuth client for one connector. _AUTHORIZATION_ENDPOINT, _TOKEN_ENDPOINT, _ISSUER, _SCOPES override what AIR declares. Both endpoints, from either source, must be HTTPS (plain HTTP only to 127.0.0.1): otherwise /connect/start answers 503 connector_not_configured, a stored connection’s refresh fails as connector/refresh_failed, and nothing is sent to the token endpoint. Neither request follows a redirect. |
ANVIL_CONNECT_<CONNECTOR>_MCP_URL, _MCP_AUTH |
Reviewed upstream Streamable HTTP MCP endpoint and explicit auth mode: oauth, workload, static, or none. OAuth requires _ISSUER and _CLIENT_ID, with optional _CLIENT_SECRET and _SCOPES. |
ANVIL_ALLOWED_HOSTS |
The upstream egress allowlist, as for every serving surface. |
A compact JWT, alg: EdDSA, with kid in the header. The gateway checks the
signature, iss, aud, exp (and refuses one more than an hour away), nbf,
iat (not in the future), and requires nonempty sub and by_tenant plus a
well-formed by_grants. by_branch, by_turn and by_manifest are optional
strings of at most 256 characters, recorded in the audit log (by_manifest is
the digest of the turn’s manifest, <algorithm>:<hex>, and the gateway treats
it as opaque text; a longer value is a 401). It is recorded, never enforced:
it changes neither the credential owner, nor the grant, nor the decision. Any failure is a 401 with WWW-Authenticate. A session belongs to
one token: a different token presenting its session id gets 403.
There are two kinds of token, told apart by by_purpose:
- A turn token has no
by_purpose. Branchyard mints one per turn and the harness holds it. It is the only token/mcptakes, and the connect routes refuse it with403 connect_token_required, before the vault is read or written, so a harness (or a prompt injected into one) can never start a connection or overwrite the person’s stored credential. - A connect token has
by_purpose: "connect", an emptyby_grants, and emptyby_branchandby_turn.by connectmints one for the person alone and hands it toanvil connect, never to a harness. It lives at most ten minutes (exp - iat; a longer one is a401). It is the only token the connect routes take, and/mcprefuses it with403 turn_token_required, so it can neither list nor call tools.
Any other by_purpose is a 401.
Grants
Section titled “Grants”by_grants is a list of entries; an operation is allowed when some entry
allows it, and the first such entry picks the account.
{"connector": "github", "operations": ["issues.*", "pulls.list"], "mode": "read", "account": "work"}connector: the bundle’s id in the served workspace (its directory, folded to[A-Za-z0-9_-]). Every tool is served as<connector>__<tool>.operations: globs over AIR operation ids.*matches any run of characters,?one. A glob may omit the service prefix:issues.*andgithub.issues.*both matchgithub.issues.list.mode:readallows only operations AIR classifies as reads;writeallows reads and mutations.confirm: "allow": needed for a mutation AIR marks as needing confirmation. The caller still passes its ownconfirm.
tools/list shows only what the grant allows. A call outside it never reaches
the upstream:
| Refusal | details.code |
When |
|---|---|---|
policy_denied |
policy/grant_denied |
No entry for the connector, no glob names the operation, or only read entries for a mutation. details.rule is the stopping entry with its index, or null. |
confirmation_required |
policy/grant_confirmation_required |
The entry allows the mutation but lacks confirm: "allow". |
auth_required |
connector/not_connected |
The person has no connection for this connector and account. |
auth_required |
connector/needs_reconnect |
The provider refused a refresh (invalid_grant). |
The auth_required messages name the connector and account and never carry a
link; the link goes to the person through /connect/start.
Credential ownership and migration
Section titled “Credential ownership and migration”Connect and turn tokens select the same credential owner:
by:v1: followed by lowercase SHA-256 of UTF-8 JSON [iss, by_tenant, sub].
These are verified claims, never request-body fields. Vault coordinates,
encryption AAD, refresh locks and pending OAuth state use that owner. Inbound
session fingerprints also include the tenant. Audit sub retains the actual
signed subject; the execution principal ID uses the isolated owner.
Older subject-only records are never adopted implicitly. Reconnect accounts
under the new namespace after upgrading. Two tenants with the same sub, or
two configured issuers using the same vault, cannot read each other’s accounts.
There is no lookup fallback to an old record.
Workload ADC and adopted MCP execution
Section titled “Workload ADC and adopted MCP execution”The Branchyard gateway resolves an approved operation’s
auth.type: workload_identity and secretSource: workload_identity through
Google’s official google-auth-library. Normal ADC discovery supports external
account WIF files, attached metadata credentials and supported impersonation
configurations. Set GOOGLE_APPLICATION_CREDENTIALS to the deployment’s ADC
configuration when needed. Scopes come from reviewed AIR; auth.audience or
auth.provider.resource requests an audience-bound ID token on credential types
that the Google library supports for ID tokens. Unsupported types fail closed.
The provider caches within connector, profile, scopes and audience. A missing
human account never falls back to the gateway’s workload identity.
For an adopted MCP connector, deploy an explicit endpoint and auth mode:
export ANVIL_CONNECT_DOCS_MCP_URL=https://mcp.example.com/mcpexport ANVIL_CONNECT_DOCS_MCP_AUTH=oauthexport ANVIL_CONNECT_DOCS_ISSUER=https://login.example.comexport ANVIL_CONNECT_DOCS_CLIENT_ID=registered-client-idexport ANVIL_CONNECT_DOCS_SCOPES=documents.readUse the actual fleet connector prefix in place of DOCS. Register the gateway’s
/connect/callback with that issuer, then use the existing human connect flow.
The official MCP SDK discovers protected-resource and authorization-server
metadata and performs PKCE, code exchange and refresh. The discovered resource
and issuer must match configuration exactly. Authorization and token endpoints
must stay on the configured issuer origin unless the deployer lists additional
exact origins in ANVIL_CONNECT_<CONNECTOR>_OAUTH_ALLOWED_ORIGINS, separated by
commas or spaces. Use this for an IdP whose token endpoint has a different origin.
Discovery may contact only those reviewed origins and the resource origin. No redirect carries credentials to another host.
This release requires a pre-registered OAuth client; it does not dynamically
register clients. Missing registration or consent remains a deployment dependency.
The encrypted account stores MCP tokens with their resource and issuer. An expiring token refreshes through the SDK under the existing account lock, retaining rotated refresh tokens. Only connect-purpose requests initiate consent. A turn cannot start a new flow or expand scopes. A 401 or 403 during an upstream call returns a refusal without automatic replay; reconnect or inspect the upstream outcome before retrying an effectful operation.
After the normal approval, principal, grant, confirmation, policy and effect
gates, the runtime calls the exact tool name captured in sourceRef.operationId.
It uses an official SDK session owned by that one call and closes it afterward.
An MCP result with isError is a failure. Public tool renaming does not change
the captured upstream binding. The incoming Branchyard bearer is never an
upstream credential. Native OAuth scopes, IAM and document permissions remain
upstream checks; a Branchyard grant cannot confer them.
workload requires the approved AIR workload contract; static resolves the
selected account in the vault; none requires auth.type: none. Unsupported
or unconfigured MCP operations still fail the wire gate. This path implements
Streamable HTTP; upstream stdio execution is outside this gateway capability.
MCP execution supports none and natural idempotency contracts. AIR HTTP
idempotency carriers are rejected before credential acquisition: the MCP
tools/call adapter cannot truthfully claim it sent those HTTP carrier keys.
Hermetic coverage uses actual SDK MCP servers and local OAuth/STS fixtures, including refresh rotation, resource/issuer mismatch, tenant collisions, subject-only migration refusal and zero upstream calls on policy denial. Live qualification, 29 October 2026: the compiled gateway obtained GKE workload credentials and called a TLS-protected SDK MCP fixture backed by real Google Storage IAM. The allowed identity listed the test object; the denied identity received a native 403. Native Branchyard Google ID-token admission also passed its audience, subject, and scope checks. See the dated record. A separate extension exercised real Google admission through an engine-issued connector token, the generated SDK, the default effect proxy, and the supervised gateway to native Storage IAM. The actual grant refusal proved the issuer–tenant–subject namespace and sent zero upstream requests. That extension used the repository’s model-free fake ACP agent; no fixture signed the inbound gateway token. Not done: live human OAuth consent or refresh, a production MCP provider, or a model-driven turn in this qualification.
Connect routes
Section titled “Connect routes”All but the callback take the person’s connect token (by_purpose: "connect") as a bearer; a turn token gets 403 connect_token_required and
nothing is read or stored. The callback takes no bearer: it is bound to the
person by the state a connect token’s /connect/start made.
| Route | Body | Answer |
|---|---|---|
POST /connect/start |
{"connector": "github", "account": "work"} |
{"kind": "oauth", "url", "expires_at"} or {"kind": "static", "submit": "/connect/api-key"} |
GET /connect/callback?state&code[&iss] |
— | Plain text for the browser. state is single use and expires after ten minutes. |
POST /connect/api-key |
{"connector", "account", "api_key"} |
{"connected": true, "connector", "account"} |
GET /connect/status |
— | {"sub", "connections": [{connector, account, kind, status, …}]}, no secrets |
POST /connect/disconnect |
{"connector": "github", "account": "work"} |
{"connector", "account", "disconnected": true}; "disconnected": false when nothing was stored |
/connect/disconnect removes the stored connection of the person the connect
token names, for the connector and account in the body (account defaults to
default). The owner comes from the verified token, never from the body, so a
person cannot remove another person’s record. Repeating it is safe and answers
200 with disconnected: false. It writes one audit line with operation
connect.disconnect, decision allowed and disconnected, and no secret. A
later call to that connector fails with connector/not_connected. A turn token
gets 403 connect_token_required; no token gets 401. The contract also asks
for a best-effort upstream revocation when AIR declares a revocation endpoint;
AIR declares none in this tree, so only the local record is removed.
anvil capabilities --json prints {"features": [...]} for this build; it
lists vault.firestore and connect.disconnect.
anvil connect <workspace> <connector> [--account <name>] [--gateway <url>] [--token-file <path>] [--open] [--api-key-stdin] calls these for a person:
it prints the authorization URL (and opens it with --open), or submits a key
read from stdin. OAuth connectors use the authorization-code grant with PKCE
(S256); the redirect URI is <gateway origin>/connect/callback.
Vault backends
Section titled “Vault backends”The gateway keeps each person’s upstream authorizations in a vault chosen by
ANVIL_VAULT_BACKEND. The owner key is the same in both: the vault sub is
by:v1:sha256([iss, by_tenant, sub]), and a record’s id is the hex SHA-256 of
the coordinates JSON [sub, connector, account].
-
file(default, unchanged). One AES-256-GCM file per connection underANVIL_VAULT_DIR, sealed with the key inANVIL_VAULT_KEY_FILE. -
firestore. One Firestore document per connection, so several gateway instances that share no disk share one vault. Each write seals the record with AES-256-GCM under a fresh 32-byte data key; Cloud KMS wraps that key (ANVIL_VAULT_KMS_KEY). The document holdsv(2),sub,connector,account,kind,status,created_at,updated_at,wrapped_dek,kms_key_version,iv,ciphertextandtag; every token or key is insideciphertext. The coordinates JSON is the additional authenticated data for both the record and the KMS wrap, so a document copied to other coordinates does not decrypt. A document wrapped by a different KMS key is refused. Reads call KMSDecryptonce per document and keep the unwrapped key in process for at most 60 seconds. Writes run in a Firestore transaction. With this backend the gateway starts withoutANVIL_VAULT_KEY_FILE, and refuses to start ifANVIL_VAULT_KEY_FILEorANVIL_VAULT_DIRis set.Refreshes and
POST /connect/disconnectare serialized across instances by a Firestore lease, so a rotating refresh token is spent once and a disconnect cannot be undone by a refresh that already read the record. The lease is a document in<collection>_leases(defaultanvil_vault_leases, id = the record id) holding a random holder id and an expiry, no secret. It is taken in a transaction before the read and released after the write; it lasts 60 seconds, so a crashed holder is taken over once it expires. A caller waits up to 30 seconds for another instance’s lease, then fails asvault_unavailable(retryable). Tested with the in-memory Firestore fake and a scripted REST client only; not run against real Firestore.
A Firestore or KMS failure fails the call: a turn gets upstream_unavailable
(retryable) with details.code: "connector/vault_unavailable", and a connect
route answers 503 vault_unavailable. No stale secret is returned. A document
that will not decrypt is connector/vault_unreadable, as for a file record.
The Firestore and KMS clients call the REST APIs with fetch and an access
token from the metadata server (Cloud Run, GCE). Other Application Default
Credentials sources, such as a key file or gcloud user credentials, are not
read. No Google client library is used.
Qualification, 5 November 2026: hermetic. The tests use in-memory fakes of
Firestore and KMS (packages/runtime/src/vault-fakes.ts) and a scripted
fetch for the REST clients. They cover a round trip across two instances,
ciphertext only in the fake Firestore, a wrong KMS key, tampered fields, a
document moved to other coordinates, KMS and Firestore outages and the 60
second key cache, and the connect routes over a real socket with the Firestore
backend. Not done: a run against real Firestore or Cloud KMS, the Firestore
emulator, key rotation, the anvil vault migrate command, and a transaction
conflict between two real instances (the fake serializes writes).
Harness environment
Section titled “Harness environment”| Variable | Meaning |
|---|---|
ANVIL_GATEWAY_URL |
The gateway’s /mcp URL. When set, the generated CLI and the Python and TypeScript SDKs send every call there and read no upstream credential variable. |
ANVIL_GATEWAY_TOKEN_FILE |
This turn’s token. Read on every call, so a replaced file takes effect at once. |
ANVIL_GATEWAY_AUTH |
token_file (the default) reads the token file as above. proxy sends no Authorization header and reads no token file: a proxy at ANVIL_GATEWAY_URL adds the token, so the process holds none. proxy is refused, before any request, unless ANVIL_GATEWAY_URL names a loopback host (localhost, 127.x.x.x, ::1). Any other value is refused. The generated CLI, the packaged bin/<connector> script and the Python and TypeScript SDKs all follow it. |
ANVIL_GATEWAY_CONNECTOR |
Optional. Overrides the connector id a client was built with. |
Local confirmation and idempotency checks still run before a call leaves the
client. --dry-run / dry_run=True / { dryRun: true } returns the gateway’s
plan. Go and Java clients do not have a gateway mode yet.
Cloud Run
Section titled “Cloud Run”anvil deploy gateway --out <dir> --image <ref> --project <id> --public-url <url> --branchyard-url <url>
writes deploy/gateway/Dockerfile and deploy/gateway/service.yaml. It writes
files and calls nothing. The Dockerfile’s command is
anvil serve mcp /srv/bundles --fleet --http "$PORT" --host 0.0.0.0 run with
exec, so Node receives Cloud Run’s SIGTERM. The service definition carries:
- a startup probe on
/readyzand a liveness probe on/healthz; ANVIL_INBOUND_AUTH_MODE=branchyard,ANVIL_INBOUND_ISSUER(the Branchyard URL),ANVIL_INBOUND_AUDIENCE(<public url>/mcp) andANVIL_INBOUND_JWKS_URI(<Branchyard URL>/.well-known/jwks.json, or--jwks-uri). The JWKS cache lasts five minutes, so after a key rotation keep the old key published for that long;ANVIL_GATEWAY_PUBLIC_URL,ANVIL_LEDGER=firestore://<project>/<database>/<namespace>andANVIL_SHUTDOWN_GRACE_SECONDS=8;ANVIL_VAULT_KEY_FILE, read from a mounted Secret Manager secret.
The image expects a prebuilt Anvil tree in anvil/ and the reviewed bundles in
bundles/ of the build context; it resolves nothing from a registry. The
per-bundle deploy/ output of anvil compile is unchanged, and its server still
refuses branchyard mode.
anvil capabilities --json prints {"features": [...]} for this build:
token.proxy and manifest.claim. A caller reads it to tell what the Anvil in
use supports.
What ran: the listener’s drain (a running call finishes, a new connection is
refused, a call past the grace period is cut, SIGTERM through anvil serve mcp --fleet --http exits 0), the ANVIL_LEDGER selection (the Firestore class is
chosen from the URI; a bad URI stops the start), the generated files’ contents,
and by_manifest in the audit line, all hermetic on loopback sockets. Not
done: a deployment on Cloud Run, a call against a real Firestore, building the
image, and a run of two gateway instances sharing one ledger (the ledger’s
cross-instance rules are covered with a fake Firestore in
packages/runtime/src/firestore-ledger.test.ts).
Harness package
Section titled “Harness package”anvil package harness <bundle> --out <dir> [--workspace <dir>] [--connector <id>] [--skill-mode full|lean] writes:
<dir>/ SKILL.md routing, safety, and refusals; under 80 lines reference/ operations.md, errors.md (gateway mode), idempotency.md, workflows.md, capabilities.md search.json the operation search index (below) schemas/ one input schema per operation, plus <connector>.<operation>.input.json for each one in search.json and anvil-search-v1.json, the schema of search.json examples/ one example input per operation python/ the Python SDK (standard library only; Python 3.9+) typescript/ the TypeScript SDK source (build with tsc, or a runtime that strips types) bin/<connector> the CLI: one dependency-free script, Node.js 18+ harness.json connector, service, bundle hash, icon, entry points, operationsThe connector id is the one the gateway serves the bundle under: its path in
--workspace (the directory given to anvil serve mcp --fleet), folded as the
fleet folds it, so <workspace>/team/github is team_github. Without
--workspace the bundle is taken as served alone and named by its directory.
--connector overrides both. Only operations the gateway serves are packaged:
approved, and never a webhook_receiver (the same rule as the MCP server and
the SDKs).
Search index and lean skill
Section titled “Search index and lean skill”search.json lists every operation the gateway serves, and only those, so a
ranker need not read reference/operations.md. It is sorted by operation id
and holds no time or path from the machine that wrote it, so one bundle gives
the same bytes every time.
{ "schema": "anvil.search/v1", "connector": "github", "bundle_hash": "sha256:…", "icon": null, "operations": [ { "id": "github.issues.list", "title": "List issues", "summary": "List issues in a repository, filtered by state.", "effect": "read", "risk": null, "confirm": false, "idempotency": "safe", "resource": "github.issue", "tags": [], "terms": ["issues", "list", "owner", "repo"], "schema": "schemas/github.issues.list.input.json", "cli": "bin/github issues list" } ]}idis the connector id and the operation’s dotted name.effectis the effect class (ADR-0030).riskis the operation’s risk, ornullfor none.confirmis whether the call needs--confirm.idempotencyissafewhen repeating is harmless,keyedwhen the operation takes an idempotency key, elsenone.summaryis the first sentence of the description, on one line, at most 160 characters.resourceis the id of the capability that owns the operation.termsare the lower-case tokens of the id, title, tags and parameter names.bundle_hashissha256:and the hex digest thatharness.jsonkeeps asbundleHash.
--skill-mode lean writes a SKILL.md of at most 4 KB: the safety rules, one
line per capability with its operation count, and pointers to search.json and
reference/. When a bundle has too many capabilities for 4 KB, the last line
says how many were left out. The default, full, is unchanged.
Connector icon
Section titled “Connector icon”service.icon in the manifest is a Simple Icons slug (github): lower-case
letters and digits, words joined by single hyphens, at most 64 characters. A
slug that breaks this is refused at compile time, and the error names
service.icon. Anvil ships no image and fetches none. The slug is copied to
harness.json, search.json ("icon": null when the bundle has none) and to
the - **Icon:** line of each INDEX.md entry (none when absent).
Host toolchain and OCI packages
Section titled “Host toolchain and OCI packages”anvil install --prefix <dir> [--from <dir>] [--prune] installs the toolchain
once per host:
<prefix>/ current -> versions/<digest> switched last, by renaming a new link over it versions/<digest>/ manifest.json, bin/anvil, python/, typescript/, compose/, env.sh--from names a directory with a manifest.json ({"files": {path: sha256}})
and the files it lists. Every file is hashed before anything is written, so a
tampered file stops the install with digest mismatch for <path> and leaves
the prefix as it was. The version directory is named by the SHA-256 of the file
map (as json.dumps(files, sort_keys=True) writes it), so the same toolchain is
the same directory: a second run changes nothing, and --prune removes the
versions current does not name. Without --from the toolchain is the one
this Anvil carries: bin/anvil is a launcher that runs this installation’s CLI
(--version prints anvil <digest>), python/anvil_sdk and typescript/ hold
the gateway settings the clients share, and compose/ holds the composite
runtime. source env.sh puts bin on PATH and the Python directories on
PYTHONPATH. A registry reference for --from is not supported; pull the
image and pass the directory.
anvil package oci <package-dir> --out <dir> [--push <ref>] writes a harness
package as an OCI image layout: oci-layout, index.json and
blobs/sha256/<digest>, with one blob per file (its path in
org.opencontainers.image.title), a config blob and an image manifest. The
index and the manifest carry dev.anvil.bundle-hash, dev.anvil.connector and
dev.anvil.version. One package gives one layout, byte for byte. --push <host>[:port]/<repository>[:<tag>] checks the manifest by tag, uploads the
blobs the registry lacks, and puts the manifest; when the registry already
holds the same digest it sends nothing more. A bearer token is read from the
file named by ANVIL_OCI_TOKEN_FILE. Loopback hosts use http, all others
https.
anvil capabilities --json prints {"features": [...]}: the optional features
of this build (package.search, skill.lean, install.prefix, package.oci,
bundle.icon).
Tested here with fakes only: the search index against the field rules Branchyard
pins and, when a Branchyard checkout is present, against its tools.py; the
install against directories on disk; the OCI layout against a check that
re-hashes every blob and a registry that is an in-process loopback server. Not
tested: a pull or push against a real registry such as Artifact Registry, and a
registry that demands a token exchange rather than a bearer token.
Branchyard can cache a package by harness.json’s bundleHash. anvil connectors index --grants <file> --out INDEX.md [--workspace <dir>] <bundle...> writes one entry per bundle a grant names, matching grants by the
same connector id: what it is for, when to use it, what is granted, and where
its SKILL.md is.
Spanning connectors: the composite
Section titled “Spanning connectors: the composite”When a branch is granted more than one connector, Branchyard also runs:
$ANVIL connectors compose --workspace "$WORK/workspace" --out "$WORK/home/connectors/_compose" \ "$WORK/workspace/github" "$WORK/workspace/jira"It writes a composite beside the connector packages
(ADR-0031): one client for every
composed connector, and flows, which are DAGs of their calls. Run it
before connectors index. The index then adds a “Spanning connectors” entry
that points at _compose/SKILL.md.
from anvil_compose import Composite, item # PYTHONPATH=<home>/connectors/_compose/python
c = Composite() # gateway mode, from ANVIL_GATEWAY_*flow = c.flow("triage")issues = flow.step("issues", "github.issues.list", owner="octo", repo="hello")flow.map("comment", "github.comments.create", over=issues, args={"owner": "octo", "repo": "hello", "issue_number": item("number"), "body": "triaged"})print(flow.plan()) # nodes, edges, waves; nothing sentprint(flow.validate()) # an error here stops run() before any callrun = flow.run() # dependency order; stops at the first failureif not run.ok: print(run.compensation) # each completed write's undo, newest first flow.compensate(run, confirm=True) # only when the task wants it undoneEach step is an ordinary call to that connector’s SDK, under this branch’s
grant, so a refused step fails the run exactly as a direct call would. The
same flow as JSON (anvil.compose-flow/v1) runs with
python -m anvil_compose run FLOW.json [--dry-run]. typescript/src/ exports
the same API. Step 10 of examples/github-mini/e2e.mjs runs a flow through the
gateway, fails it on purpose, and compensates.
| Meta method | What it does | Sends? |
|---|---|---|
step / map / when= |
Build the DAG; ref(step, path) and item(path) read earlier results. |
no |
plan() / validate() / mermaid() / to_json() |
Read the DAG. | no |
dry_run() |
Every step through its SDK’s gates with dry_run. |
no |
run() |
Call the steps. | yes |
compensate(run, confirm=) |
Run the undo calls a failed run lists. | yes |
Effects and undo
Section titled “Effects and undo”Every operation call through the gateway reports what it did to the world and how to undo it. Anvil never undoes anything itself: an undo is an ordinary call the caller makes, under the same grant.
Effect classes
Section titled “Effect classes”Each operation has one class, declared in its manifest entry and checked by the compiler:
| Class | Meaning | Undo |
|---|---|---|
read |
Changes nothing. | None needed. |
reversible |
A true inverse leaves the world as it was. | inverse |
compensable |
A cancelling call exists, but leaves a trace. | compensate |
irreversible |
No undo exists. | None. |
An operation that declares nothing is read if it is a read and
irreversible otherwise, with no undo.
Declaring it
Section titled “Declaring it”operations: createIssueComment: idempotency: { strategy: key_supported, key_location: header, header: Idempotency-Key } effect: class: reversible inverse: operation: deleteIssueComment # operationId, canonical name, or AIR id arguments: { owner: request.owner, repo: request.repo, comment_id: response.id } deadline: { within_ms: 86400000 } # optional; or at: response.<path> createIssue: effect: class: compensable compensate: operation: updateIssue arguments: { owner: request.owner, repo: request.repo, issue_number: response.number, state: { const: closed } } createRelease: effect: class: irreversible lookup: { operation: getReleaseByTag, by: id, arguments: { owner: request.owner, repo: request.repo, tag: request.tag_name } } draft: operation: createRelease # may be the operation itself with a draft flag arguments: { owner: request.owner, repo: request.repo, tag_name: request.tag_name, name: request.name?, draft: { const: true } } handle: response.id promote: { operation: updateRelease, arguments: { owner: request.owner, repo: request.repo, release_id: response.id, draft: { const: false } } } discard: { operation: deleteRelease, arguments: { owner: request.owner, repo: request.repo, release_id: response.id } }A mapping names each argument of the follow-up call and where its value comes from:
request.<path>: the original call’s arguments, by the names the tool takes.response.<path>: the upstream’s answer.idempotency_key: the key the call carried upstream (lookups only).{ const: <value> }: a literal.
A path is dotted names and [n] indices (response.items[0].id). A trailing
? leaves the argument out when the path names nothing; otherwise a path that
names nothing makes the follow-up unavailable for that call. anvil compile
refuses (effect/* errors) a reference to a missing operation, a mapping that
misses a required argument, names an argument the target does not take, or
sets its confirm or idempotency key, a value whose type the target input
cannot take, a path the schema does not declare, a
reversible class with no inverse, a compensable class with no compensation,
and a lookup by key on an operation that sends no key. An operation whose
declaration has an error is served as irreversible with no undo until it is
fixed, and requires confirmation. An operation whose draft form requires
confirmation requires it too, so a staged call can pass confirm: true on to
the draft.
What a call returns
Section titled “What a call returns”Over MCP, the tools/call result’s _meta.effect; over REST, the
X-Anvil-Effect header (JSON, non-ASCII escaped):
| Field | Meaning |
|---|---|
class |
The operation’s class. |
operation |
The AIR operation id. |
idempotency_key |
The key that went upstream, or null when none did. |
undo |
{kind: "inverse" | "compensate", operation, tool, arguments}, or null. tool is the name to call on this gateway. |
deadline_ms |
Epoch milliseconds after which undo may stop working, or null. |
compensate |
On a reversible effect that also declares a compensation: the same shape, for after the deadline. |
lookup |
{by, operation, tool, arguments} for reconciliation, or null. |
undo_unavailable |
Why undo is null although the class has one (a mapped value was missing, or the follow-up is not served). |
staged |
On a staged call: {draft_operation, handle, promote, discard}. |
A failed call still reports its class, key, and lookup; a dry run reports
nothing. tools/list publishes the declaration (_meta["anvil/effect_class"]
and _meta["anvil/effect_contract"]) for operations that declare one, so a
reconciler can resolve a lookup from the request and key alone.
Idempotency keys
Section titled “Idempotency keys”Send the ledger id as _meta.idempotency_key (MCP) or Idempotency-Key
(REST). When the operation declares an idempotency carrier the gateway sends
the key upstream through it; otherwise it is not sent, and the report’s
idempotency_key is null. Either way the audit line records it as
ledger_id. A different key in the call’s own arguments is a
validation_error (effect/idempotency_key_conflict).
Undo, staging, and promotion
Section titled “Undo, staging, and promotion”- Undo: call
undo.toolwithundo.arguments, addingconfirm: truewhere the follow-up needs confirmation, under the same token. The grant must allow it, as for any call. - Stage:
_meta.stage: true(MCP) or"stage": truein the REST body on an operation with a draft form performs the draft instead. The answer is the draft, and_meta.effect.stagedholds itshandleand thepromoteanddiscardcalls. The mapped draft input is checked against the draft tool’s schema first (validation_error,effect/draft_input_invalid). An operation without a draft form is refused (unsupported_operation,effect/no_draft_form) and nothing is called. - Promote: call
staged.promote.toolwith its arguments. That call is the real effect, with its own report.
REST route
Section titled “REST route”POST /call/<tool> on the gateway’s listener, with the turn’s token as the
bearer, takes {"arguments": {...}, "stage": true?} (at most 64 KiB) and an
optional Idempotency-Key header. It runs the same grant, gates, executor,
and audit as /mcp. It answers 200 with the response data, or an
{"error": {...}} envelope with a status for its code: 400
validation_error, 401 auth_required, 403 policy_denied or
permission_denied, 404 not_found (also an unknown tool), 409
conflict, 422 unsupported_operation, 428 confirmation_required or
idempotency_required, 429 rate_limited, 502 or 504 from the
upstream.
curl -s -D - -X POST "http://127.0.0.1:$PORT/call/github__github_create_comment" \ -H "authorization: Bearer $(cat "$WORK/turn.token")" -H 'content-type: application/json' \ -H 'idempotency-key: 01JBRANCHYARDLEDGER00000001' \ -d '{"arguments": {"owner": "octo", "repo": "hello", "issue_number": 2, "body": "Looks good."}}'HTTP/1.1 200 OKx-anvil-effect: {"class":"reversible","operation":"github.comments.create","idempotency_key":"01JBRANCHYARDLEDGER00000001","undo":{"kind":"inverse","operation":"github.comments.delete","tool":"github__github_delete_comment","arguments":{"owner":"octo","repo":"hello","comment_id":100}},"deadline_ms":null,"lookup":null}
{"id":100,"body":"Looks good."}