Skip to content

Configuration: Environment Variable Reference ​

Audience: anyone who runs a registry and changes its settings Checked against the source: 2026-10-16 (the registry's config.py and its os.getenv reads, the TEG's settings, the event store; the frame kit 1.0.0-beta.20: both generate-operator-env.sh, the operator and standalone composes and the frame template templates/frame-test/frame-test.env.tmpl); the two generators, the values the kit writes and the template at the end again 2026-10-22 (the frame kit 1.0.0-beta.22)

Each table gives the code default (what the software does when the variable is unset) and, where the kit writes a different value, that value too. Values marked secret are credentials: keep them out of version control, chat and screenshots.

Where the values live. A standalone registry reads scripts/distribution/.env.operator. A cloud operator's .env.operator is written by its frame when the frame provisions it, on the frame's host: the frame-scope switches follow the frame, and the operator-scope switches are the ones chosen in the application. A frame reads <stack>/.env.frame-test, written by frame-up.py: a line named FT_REG_<NAME> is a value the frame's compose maps into the registry's environment, and any other line reaches the registry through the env file. In every compose a value written in environment: beats the env file, and a changed value takes effect when the container is recreated:

bash
docker compose -f <compose file> --env-file <env file> up -d --no-deps --force-recreate <service>

Reading a registry's switches without a shell: GET /api/v1/public/env-catalog lists every switch of the configuration catalog with its options, its scope (operator or frame) and this registry's current option, and says whether that option was set or is the code default. GET /api/v1/public/registry-config gives the switches the console reads (staking_enabled, fiat_onramp_enabled, genesis_grant_amount and others).


Generating Your Environment File ​

On a standalone registry, operator-setup.sh writes the file for you:

bash
./operator-setup.sh <registry-name> standalone

It asks before it overwrites an existing .env.operator, then runs generate-operator-env.sh <registry-name>, which writes .env.operator in the current directory at mode 600 and keeps standard output empty (its progress goes to standard error). You can run the generator yourself: ./generate-operator-env.sh <registry-name>; the older form with > .env.operator leaves the same file. The file carries secrets: never commit it.

The generator writes:

  • REGISTRY_NAME, and an OPERATOR_DID of the form did:theprotocol:operator-<16 hex characters>
  • three database passwords (48 hex characters each)
  • the registry's signing secret and the TEG's keys (64 hex characters each), the event store's internal key, and the ledger broker's password and record key
  • ALLOWED_ORIGINS=["http://localhost:8000"] and a random FEDERATION_HEALTH_CHECK_SECRET, the two values the registry's production checks ask of a standalone registry once BASE_URL is public (put your address in the list)
  • the switches listed in the template at the end of this page

An operator bundle carries a different generator, the one the frame's provisioner runs: it writes .env.operator, pgbouncer.ini and userlist.txt itself, in the current directory, with matching database passwords. Under an operator name that does not start with cloud-op-, it also writes the operator's Redis passwords and proxy trust secrets, redis-users.acl and the markers in the two terminator configurations; a cloud operator's frame writes those itself. Like the standalone generator, it keeps standard output empty.


Environment Variables by Category ​

Identity ​

VariableCode defaultKitDescription
REGISTRY_NAMEAgentVault Registrythe name you give the generatorThe prefix of every container name (<name>-registry), the slug of the first admin's address (admin@<name>.dev) and the registry's own name.
OPERATOR_DIDunsetdid:theprotocol:operator-<hex>A non-empty value marks the registry as a cloud operator for its licence handling: it asks its frame for its licence and shows it on its card. The standalone generator writes one as well, though a standalone registry has no frame to ask.
TRUST_DOMAINunset<name>.localStandalone compose only: passed to the registry as SPIRE_TRUST_DOMAIN and DID_ISSUER_NAMESPACE (operator.local when unset). The registry signs its card under it and issues its agents' DIDs under it. Set your DNS name; .local suits a local trial only.
DID_ISSUER_NAMESPACEunseta frame: its trust domainThe namespace in new agent DIDs (did:theprotocol:<namespace>:<uuid>; unset, did:theprotocol:<uuid>). A registry whose namespace is not its SPIRE_TRUST_DOMAIN refuses to start.
FIRST_ADMIN_EMAIL, FIRST_ADMIN_PASSWORD, FIRST_ADMIN_NAMEunsetnot writtenThe first admin the registry creates on its first start. Unset: admin@<name>.dev with a random password printed once to the log. The password is a secret.

Images and Host Port ​

VariableDefaultDescription
IMAGE_REGISTRYtheprotocolThe prefix of the application images in the standalone compose, and the prefix build.sh tags with. theprotocol is a local name, so the default runs what you built.
IMAGES_PREFIXimages.theprotocol.cloudThe same prefix in the operator compose. The frame's provisioner writes the frame's own image host, or the local prefix of a frame whose images are local tags.
VERSIONstableThe image tag, in both composes. build.sh tags every build with the kit's version, latest and stable; the provisioner writes the version its frame runs.
REGISTRY_HTTP_PORT8000Standalone compose: the host port of the registry's plain HTTP. The container still listens on 8000.

The generator writes none of these; add them to .env.operator only to change a default.

Database Passwords ​

VariableGeneratedDescription
PG_PASS_REGISTRY48 hex charactersSecret. The registry database's password.
PG_PASS_TEG48 hex charactersSecret. The TEG database's password.
PG_PASS_EVENT_STORE48 hex charactersSecret. The event store database's password (standalone only).

PostgreSQL takes a password when it first creates its data directory. Changing one later means changing it inside the database as well (and, on an operator, in pgbouncer.ini and userlist.txt), or recreating the volume.

Security Keys ​

Services authenticate to each other by certificate wherever the stack has an identity fabric: an operator's and a frame's containers hold SPIFFE SVIDs that SPIRE renews, and their gateways verify them. The generated keys that still matter:

VariableGeneratedDescription
API_KEY_SECRET64 hex charactersSecret. Signs every JWT the registry issues: developer and agent access tokens, refresh tokens and the partial token of a two-factor login. API keys do not depend on it: they are random and stored hashed. In production the registry refuses a value containing test, example, demo or sample.
TEG_REGISTRY_JWT_SECRETthe same value as API_KEY_SECRETSecret. The composes pass it to the TEG (as REGISTRY_SERVICE_TOKEN). Keep it equal to API_KEY_SECRET and rotate the two together.
TEG_TOKEN_SIGNING_KEY64 hex charactersSecret. Signs the TEG's own access tokens. Required: the TEG refuses to start without a value of at least 32 characters.
TEG_AVTP_SYSTEM_API_KEY64 hex charactersSecret. The TEG's system key (AVTP_SYSTEM_API_KEY inside the TEG). Required, at least 32 characters.
TEG_ADMIN_API_KEY64 hex charactersSecret. On a standalone registry, how the registry authenticates its admin calls to the TEG (treasury, enforcement), which travel over the stack's private network. On an operator or a frame the TEG takes internal callers by SVID only (TEG_MTLS_REQUIRED=true) and does not consult the key.
EVENT_STORE_INTERNAL_API_KEY64 hex charactersSecret. Standalone only: the registry, the TEG and the auditor present it to their own event store. The operator compose carries no store key: an operator writes to its frame's ledger with its SVID.

SECRET_KEY and JWT_SECRET_KEY are still generated and passed to the registry, which reads neither.

Federation ​

VariableCode defaultKitDescription
EVENT_STORE_URLhttp://localhost:8200operator: the frame's ledger gateway; standalone: http://event-store:8200Where the registry writes its events. The provisioner writes the frame's own gateway into an operator's compose.
FEDERATION_LICENSE_KEYunsetwritten by the provisioner, or by frame-federate.py on a frameSecret. The licence this registry holds from its frame or network. It rides the calls a licence authorizes: an operator's self-service calls to its frame (logs, restart, agent mTLS enrollment), federation sync and cross-registry transfers.
FEDERATION_SYNC_INTERVAL_SECONDS60030Seconds between federation sync cycles. Lower means fresher peer data and more traffic.
FEDERATION_REQUIRE_PEER_SPIFFE_BINDfalsetrue (operator compose and frame template)A federation caller's SPIFFE ID must be bound to an active peer row.
BILATERAL_PEER_URLunsetwritten by the provisionerThe federation address the signed card publishes for peers to dial, such as https://<host>:8443.
FEDERATION_BASE_URLunsethttps://nginx-federation:8443The stack's own federation terminator, an internal address. Leave it unless you change the terminator.
CROSS_TEG_ENABLED (TEG)falsetrue on operators and framesThe TEG's cross-registry transfers.
ALLOWED_ORIGINS["*"]a frame: its console; standalone: ["http://localhost:8000"]Browser origins added to the CORS allowlist. The allowlist is otherwise derived every 60 seconds from this registry's own addresses and every active peer's console. With a public BASE_URL, the registry refuses to start while this is the wildcard.
CORS_ALLOW_ALL_ORIGINSfalsenot writtentrue answers every origin (without credentials). Peers' consoles need no wildcard: they are on the derived allowlist.
EVENTSTORE_MTLS_REQUIRED (event store)truea frame: trueThe event store's own switch: writes need mutual TLS through the frame's terminator, and a federation licence header is refused. On an operator's registry it changes nothing; the frame's store enforces it.
EVENTSTORE_INTERNAL_KEY_WRITES (event store)unsetthe standalone compose: allowallow lets the internal key write to the store while mutual TLS is required. A standalone stack needs it (chapter 00): its store has no TLS terminator in front of it.

The registry reads neither KAFKA_ENABLED nor KAFKA_BOOTSTRAP_SERVERS: it writes its events to the event store over HTTPS, and only the event store talks to the ledger's broker. The generators still write both; they are harmless. The same holds for EVENT_STORE_ENABLED, which the provisioner and the frame template write and nothing reads.

Units and Fees ​

VariableCode defaultKitDescription
FRAME_CURRENCYunset: the code's historical default, FRAME_CURRENCY=AVTa frame: its --ticker; an operator: its frame'sThe unit's ticker on the card, the console, mails and messages. A standalone registry should set its own.
MINTING_AUTHORITYTEG: teg-layer-aoperator: disabled; standalone and frame: teg-layerThe TEG issues only when this equals its TEG_ID. The registry also reads disabled as "this registry is a cloud operator".
TEG_ID (TEG)teg-layer-astandalone and frame: teg-layerThis TEG's identifier.
GENESIS_GRANT_ENABLEDtruetrueA developer's first agent receives a starting grant on creation, paid from the registry's own accounts. Later agents report not_first_agent.
GENESIS_GRANT_AMOUNT1000.05000.0 (both generators and the operator compose); a frame: 1000.0; a provisioned operator: its frame's amountThe grant, in the registry's unit. Read only while GENESIS_GRANT_ENABLED is true: with the grant off, a changed amount has no effect and nothing reports it.
NETWORK_PROFILEunseta frame: lowsupply-2026A file of money amounts (the reputation bond, the treasury floor below which genesis grants wait, the issuance and transfer caps, an operator's starting treasury). A value set in the environment wins over the profile.
DEFAULT_FEE_RATE, MAX_FEE_RATEunsetnot written (kits up to 1.0.0-beta.20 wrote 0.5, 5.0)No service reads them; an older .env.operator may still carry them. Fees come from the frame policy document (transaction_fees.*), and the signed registry card (/.well-known/registry-card.json) states the rates in force.
VELOCITY_SNAPSHOT_INTERVAL_SECONDS3600unsetHow often the registry computes each sender's velocity index for the last completed hour (the Dynamic Fee in chapter 04).
VELOCITY_MIN_ACTIVE_SENDERS10unsetBelow this many senders in an hour every velocity index is 0, so every transfer pays the base rate.
VELOCITY_BASELINE_MIN_VOLUME100unsetThe least baseline, in the registry's unit: the median of an hour's volumes counts as at least this much.
VELOCITY_SATURATION_RATIO100unsetHow many times the baseline a sender must move in an hour to reach index 1, the maximum rate.

Email (SMTP) ​

VariableCode defaultKitDescription
MAIL_SERVERunsetsmtp.example.comThe SMTP host. The kit's value is a placeholder: pick a mail posture (below) before real users register.
MAIL_PORT587587587 for STARTTLS, 465 for TLS.
MAIL_USERNAMEunsetnoreply@example.comThe SMTP login.
MAIL_PASSWORDunsetCHANGE_MESecret. The SMTP password.
MAIL_FROMunsetnoreply@example.comThe sender address.
MAIL_FROM_NAMETheProtocolthe registry nameThe sender's display name.
MAIL_STARTTLS / MAIL_SSL_TLSTrue / FalsesameFor port 465 set MAIL_SSL_TLS=True and MAIL_STARTTLS=False.
MAIL_DISABLEDfalsenot writtenDeclares that this registry sends no mail: every send is logged and skipped. In production it cannot stand beside a configured SMTP account.
MAIL_RELAY_PARENT_URL, MAIL_RELAY_LICENSEunsetnot writtenThe relay posture: the parent sends verification and password-reset mail for this registry (secret licence).
PUBLIC_UI_URLunsetwritten by the provisioner and the frame templateThe console a person uses, such as https://registry.example.org.

Mail carries account verification, password resets and notifications. The addresses involved are easy to confuse:

VariableAnswersUsed for
BASE_URLwhere this registry's API is, as an outside caller types it (code default http://localhost:8000)API links; a value that is not localhost switches on the production checks
PUBLIC_URLthe registry's public web addressthe address on its card
PUBLIC_UI_URLthe console a person usesevery link a person follows: verification, password reset, the console link, invitations
BILATERAL_PEER_URLthe federation lanewhat peers dial

A link a person follows uses PUBLIC_UI_URL, else the origin of BASE_URL or PUBLIC_URL; loopback values never count. With none of them set, a mailed link falls back to the raw BASE_URL, which names localhost: set PUBLIC_UI_URL or BASE_URL before anyone else registers.

Sessions are per host

A link that lands someone on a different host name than the one they registered on signs them in there. Back on the site they typed, they are signed out, which reads as "the link did not work". Point PUBLIC_UI_URL at the console people use.

Pick exactly one of three mail postures. The one broken combination is a registry that demands verification and cannot send it: every self-registered account is then locked out until an admin verifies it by hand.

  1. direct: real SMTP settings above, REQUIRE_EMAIL_VERIFICATION=true. The normal choice.
  2. relay: no SMTP credential of your own; the parent frame sends verification and password-reset mail through MAIL_RELAY_PARENT_URL and MAIL_RELAY_LICENSE (the parent must accept relays). Other mail is skipped in this posture.
  3. none: MAIL_DISABLED=true with MAIL_USERNAME left empty, REQUIRE_EMAIL_VERIFICATION=false and BETA_INVITE_REQUIRED=true. With verification off, invite codes are the remaining gate; never run with neither.

Monitoring ​

VariableDefaultDescription
GRAFANA_ADMIN_PASSWORDgenerated (32 hex characters)Secret. Required by docker-compose.monitoring.yml, which refuses to start Grafana without it.
PROMETHEUS_HTTP_PORT, ALERTMANAGER_HTTP_PORT, GRAFANA_HTTP_PORT9090, 9093, 3000The monitoring compose's host ports, on loopback only.
AUDITOR_HTTP_PORT8045The standalone auditor's host port, on loopback only.
METRICS_ENABLEDtrueWhether the registry serves GET /metrics. false (or 0, no, off) removes the route: it answers 404 to everyone, your own Prometheus included (chapter 06).
PROMETHEUS_URLhttp://agentvault-prometheus:9090Where the registry's status page reads per-day availability. The default is a container name the kit does not use: beside the kit's monitoring compose set http://prometheus:9090. Unreachable means no history bars.

Feature Flags ​

VariableCode defaultKitDescription
BETA_INVITE_REQUIREDfalsefalseRegistration requires an invite code.
ENABLE_PROJECTION_SNAPSHOTSofftrueAllows POST /api/v1/admin/projection-snapshot, which posts the TEG's balances to the ledger as a baseline.
AUDITED_BALANCE_ENABLED (TEG)truetrueBefore a transfer, the TEG refuses an account whose balance differs from its audited copy.
COCKPIT_DESK_ENABLEDfalsea frame: trueThe arrangeable operator desk. Off, the desk's route and its menu entry are gone.
SPAWN_WALLET_ANCHOR_MODEoffa frame: onon: a spawned child agent holds no wallet and spends its parent's.
STATUS_DATA_DIR/app/dataWhere the public status page keeps its incidents and uptime rollup. The operator compose mounts a volume there; the standalone compose does not, so a standalone registry's status history resets when its container is recreated.
RELEASE_CHANNEL_CHECK_ENABLEDfalsea frame: trueReads the signed release channel every 6 hours and tells the admins once when a newer release is out (chapter 16).

Agent Authorization, Liability and Policy ​

These decide what agents may do and who answers for it. Each code default is the setting that changes nothing; a frame the kit stands up starts with most of them on. Turn them on deliberately, and read the chapter before you do.

VariableCode defaultKit frameDescription
AGENT_RBAC_MODEoffenforceoff, shadow or enforce. Per-agent roles and permissions. shadow decides and records without refusing.
AGENT_DELEGATION_MODEoffenforceoff, shadow or enforce. Delegation grants and capability permits.
CAPABILITY_CIRCUIT_BREAKER_ENABLEDfalsetrueRevokes a capability permit and its whole subtree after 5 misuse denials in 5 minutes. Acts only with AGENT_DELEGATION_MODE=enforce; denials for expiry, budget or uses never count.
LIABILITY_MODEoffenforceoff, shadow or enforce. The Cockpit Card gate: it can only refuse, before any escrow, so it never moves value.
LIABILITY_PRESENCE_THRESHOLD_AVT0Amount at or above which an action pauses for a live human presence confirmation. 0 turns the step-up off.
REPUTATION_BOND_MODEoffenforceoff, shadow or enforce. The bond as the gate to providing services. shadow ranks bonded providers first and counts what it would refuse; enforce refuses an unbonded provider at discovery, listing, pricing, Guild bids, contract acceptance, A2A authorization and publishing a migration template, never at settlement. The production frames run enforce.
REPUTATION_BOND_AMOUNT50250 (the network profile)The bond held in escrow per provider, in the frame's unit. Read from the environment, then the network profile, then the frame policy document (enforcement.reputation_bond_min_avt); the network sets its floor at 50. GET /api/v1/reputation-bond/config serves the value in force.
REPUTATION_BOND_TREASURY_BACKSTOPfalsefalseLets an owner ask the treasury to underwrite a bond without moving units. Such a bond holds the treasury's own units: forfeiting it moves nothing, releasing it pays nobody, and it never makes its owner a member.
REPUTATION_BOND_MIN_TRANSACTIONS, _MIN_AGE_DAYS, _MIN_RATED_PEERS, _MIN_TRUST_PERCENTILE10, 30, 3, 50Maturity conditions, all required, each overriding the policy document's enforcement.bond_maturity_* value: satisfactory interactions, days since the lock, distinct rating peers owned by other developers, and a standing at or above that percentile of the frame's ranked agents (waived while fewer than 10 agents are ranked). REPUTATION_BOND_MATURITY_RELEASES_PERCENT (60, held to 0 to 80) is the share a matured bond pays back, after REPUTATION_BOND_RELEASE_COOLDOWN_DAYS (7).
ENFORCEMENT_SLASH_MODEcacheenforcecache, shadow or enforce. Whether a ruling on this registry moves units down the slash_waterfall policy (bond, then lock, then liquid balance, then the owner's other agents where the order lists the cascade). Only enforce moves value; shadow plans and records; cache writes the registry's cached balance only. A peer's slash request the registry takes drains the same order and always moves units.
CROSS_REGISTRY_SETTLEMENT_DELIVERYoffon sends a cross-registry dispute settlement's slash request to the defendant's home, naming the federation address the signed card publishes (BILATERAL_PEER_URL or FEDERATION_BASE_URL, where a peer can dial it). Off, or with no such address, nothing is sent: the settlement ends at once as NOT_DELIVERED and the ruling says so. A money path that is turned on frame by frame.
AGENT_XREG_DELEGATION_ENABLEDfalsetrueCross-registry delegation. Must be true on both the issuing and the receiving registry.
IRONHAND_INLINE_SVID_ENABLEDfalsetrueIssues short-lived X.509 SVIDs inline to agents on infrastructure you do not run.
IRONHAND_INLINE_SVID_TTL_SECONDS1800The lifetime of those SVIDs.
TEG_TESTING_FAUCET_ENABLED (TEG)falsenot writtenThe TEG's test faucet: 1,000 units from the treasury per call, to any agent the caller names, with no authentication. Leave it off outside a throwaway frame.

AGENT_RBAC_MODE and AGENT_DELEGATION_MODE must always move together. With enforce and off, the registry never consults capability-permit checks, so an agent whose authority comes from a capability permit keeps only its role set (often empty) and is refused. Never change one alone.

Before enforcing RBAC on an existing registry, confirm your agents carry roles. An agent with no role resolves to {read.profile, enforcement.self} and can do nothing economic. Run shadow first and read the denial feed (GET /api/v1/agents/{did}/authz/denials): that is what shadow mode is for.

Cross-Currency Transfers ​

A frame holds the FX booth: FX_ENABLED (default false, a frame-scope switch) turns on its swap booth and reserves. A cloud operator holds no booth of its own. When its frame runs one, the provisioner writes FX_ROUTE_ENABLED=true and the gateway settings (FX_ROUTE_GATEWAY_REGISTRY_ID, FX_ROUTE_GATEWAY_ROUTER_DID, FX_ROUTE_GATEWAY_TEG_ID), and the operator hands a cross-currency transfer to its frame's booth. Without a route, a cross-currency transfer answers 409 naming the disabled booth, and nothing moves; same-currency transfers are unaffected. A standalone registry has one unit and no booth. Chapter 11 describes cross-frame FX.

Compliance and Cosmetics ​

VariableCode defaultKitDescription
JURISDICTION_MODEoffa frame: shadowoff, shadow or enforce. Checks actions against the frame's declared jurisdiction profile: shadow logs and counts, enforce refuses with 403. An entry of the regulatory-authorization rail carries its own mode, and an entry-level enforce applies even while this is shadow.
REGAUTH_COUNTERSIGN_WATCH_ENABLEDtrueA watcher that tells you when a countersigned contract behind a regulatory authorization stops being valid.
REGAUTH_COUNTERSIGN_WATCH_INTERVAL120Seconds between its cycles.
FLARE_LOCAL_PURCHASE_ENABLEDfalsea frame: trueSells cosmetic flare tiers for the registry's own units. Off, the catalog says the shop is closed and a purchase answers 503.
FLARE_SHOP_PRICESunsetA JSON object of per-tier prices. An unknown tier or a price of zero or less is ignored; a malformed value leaves the defaults in force.
OPA_ENABLED / OPA_ENFORCEfalse / falsetrue / false (standalone compose and a frame)Open Policy Agent. With OPA_ENABLED alone, every authorization decision is mirrored to OPA and recorded beside the registry's own (shadow). OPA_ENFORCE counts only with OPA_ENABLED; OPA can then turn an allow into a refusal, never a refusal into an allow.

PgBouncer Configuration ​

On an operator, the generator writes pgbouncer.ini and userlist.txt (both mode 600) with the same database passwords as .env.operator:

ini
[databases]
agentvault_registry = host=db port=5432 dbname=agentvault_registry user=registry password=<PG_PASS_REGISTRY>
teg_layer = host=teg-db port=5432 dbname=teg_layer user=teg password=<PG_PASS_TEG> pool_size=200

[pgbouncer]
listen_addr = 0.0.0.0
listen_port = 6432
auth_type = scram-sha-256
auth_file = /etc/pgbouncer/userlist.txt
pool_mode = transaction
max_client_conn = 800
default_pool_size = 150
reserve_pool_size = 10
ignore_startup_parameters = extra_float_digits,options
SettingValueDescription
pool_modetransactionA server connection returns to the pool after each transaction; the workers share them.
auth_typescram-sha-256Every client presents its password; userlist.txt holds the two.
max_client_conn800Client connections the pooler accepts.
default_pool_size150Server connections per database and user; the TEG's database has its own pool_size=200.

If you change a database password, change it in all three places. On a standalone registry the pooler is configured in the compose instead (POOL_MODE=transaction, MAX_CLIENT_CONN=200, DEFAULT_POOL_SIZE=20) and serves the registry's database only; the TEG connects to its database directly.


Redis Configuration ​

redis-server --maxmemory 128mb --maxmemory-policy allkeys-lru
SettingValueDescription
maxmemory128mbMemory before eviction.
maxmemory-policyallkeys-lruEvict the least recently used keys when memory is full.
Database0One database for the registry and the TEG (a frame gives its registry, its event store and its TEG a database each).

On an operator, Redis also loads an access list (redis-users.acl, written by the provisioner, or by the bundle's generator on an operator's own host) with one user each for the registry and the TEG (REDIS_PASSWORD_REGISTRY, REDIS_PASSWORD_TEG, secret); the default user may only answer the health check. A standalone Redis has no access list.

Redis carries the leader election that runs each background task once, the rate limiter's counters, the WebSocket broadcasts across workers and, on an operator, the queue that batches transfers on their way to the TEG.


Registry Service Configuration ​

The compose sets these for the registry; they rarely need changing:

VariableOperator composeStandalone composeDescription
DATABASE_URLpostgresql+asyncpg://registry:<pass>@pgbouncer:6432/agentvault_registrythe sameThe registry's database, through the pooler.
DATABASE_URL_SYNCpostgresql://registry:<pass>@pgbouncer:6432/agentvault_registrythe sameThe same database for the synchronous paths (migrations).
TEG_API_BASE_URLhttps://nginx-teg:8443unset (http://teg-layer:8080)Where the registry calls the TEG: through its mTLS terminator on an operator.
TEG_LAYER_URLhttp://teg-layer:8080the sameThe TEG's own address, read by the stack health probes.
REDIS_URLredis://registry:<REDIS_PASSWORD_REGISTRY>@redis:6379/0redis://redis:6379/0Redis.
SPIFFE_ENDPOINT_SOCKETunix:///opt/spire/sockets/agent.sockunsetThe SPIRE agent's socket.
REGISTRY_PROXY_TRUST_SECRETwritten by the provisioner or the bundle's generatorunsetSecret. The marker nginx-federation adds to every call it forwards. Unset or shorter than 32 characters, the registry ignores forwarded certificates: it refuses rather than trusts.

The number of workers is on each compose's command line (--workers 8 on an operator, 4 standalone). The composes also set UVICORN_WORKERS, which none of the services reads.


TEG Layer Configuration ​

VariableOperator composeStandalone composeDescription
DATABASE_URLpostgresql://teg:<pass>@pgbouncer:6432/teg_layerpostgresql://teg:<pass>@teg-db:5432/teg_layerThe TEG's database.
REGISTRY_URLhttp://registry:8000the sameWhere the TEG reads the event emission policies.
ADMIN_API_KEY<TEG_ADMIN_API_KEY>the sameThe admin key; see TEG_ADMIN_API_KEY above.
MINTING_AUTHORITYdisabledteg-layerIssuance; see Units and Fees.
TEG_MTLS_REQUIREDtrueunset (false)Internal callers authenticate by SVID only; the shared key no longer counts.
TEG_PROXY_TRUST_SECRETwritten by the provisioner or the bundle's generatorunsetSecret. The marker nginx-teg and nginx-federation add to forwarded calls.
TRUSTED_SPIFFE_DOMAINS${TEG_TRUSTED_SPIFFE_DOMAINS}, emptyunsetThe trust domains whose callers the TEG accepts; empty means its own frame's domain only.
REDIS_URLredis://teg:<REDIS_PASSWORD_TEG>@redis:6379/0unsetLeader election for the TEG's own sweepers.

The TEG also runs --workers 8 on an operator and 4 standalone.


Authentication Configuration ​

VariableDefaultDescription
ACCESS_TOKEN_EXPIRE_MINUTES90The lifetime of an access JWT, in minutes.
BOOTSTRAP_TOKEN_LIFETIME300The lifetime of a bootstrap token, in seconds.
EMAIL_VERIFICATION_TOKEN_EXPIRE_HOURS24How long a verification link stays valid.
REQUIRE_EMAIL_VERIFICATIONtrueOff, a new developer is verified on registration; on, a login answers 403 until the mailed link is followed.
REQUIRE_ADMIN_2FAfalseAn account with admin rights that has not set up two-factor authentication cannot sign in with its password, and none of its credentials (API keys, MCP connectors, sessions) reaches an admin route or an admin tool until 2FA is on. Its other use is unchanged.

Rate Limiting ​

VariableDefaultDescription
RATE_LIMIT_DEFAULT1200/minuteThe limit every route has, per client address: the last address your proxy appended, which a caller cannot forge.
SANDBOX_BYPASS_RATE_LIMITunsettrue switches the limiter off. For a test frame that sweeps every endpoint, never for a registry people use.

Many routes carry a tighter limit of their own in the code (a login, for instance), counted per verified account or agent once its credential has been checked. Calls between the stack's own containers are exempt. The limiter keeps its counters in Redis, so a limit holds across workers.

RATE_LIMIT_BYPASS_KEYS (comma-separated API keys) does not lift the limit: a request that presents one of these keys in X-Api-Key counts in a bucket of its own instead of its address's, under the same limit.


Secret Rotation Guidance ​

When to Rotate ​

TriggerAction
Suspected compromiseRotate the API_KEY_SECRET / TEG_REGISTRY_JWT_SECRET pair (every issued JWT stops working: developers and agents sign in again) and revoke the API keys involved (API keys do not depend on the pair). On a standalone registry rotate TEG_ADMIN_API_KEY and EVENT_STORE_INTERNAL_API_KEY too.
Personnel changeThe same pair, and on a standalone registry TEG_ADMIN_API_KEY
RoutineThe pair

Service certificates need no manual rotation: SPIRE renews the SVIDs.

How to Rotate ​

  1. Generate a new value: openssl rand -hex 32.
  2. Write it into .env.operator, on the host that runs the stack.
  3. Recreate the containers that read it:
    bash
    docker compose -f docker-compose.standalone.yml --env-file .env.operator up -d --no-deps --force-recreate registry teg-layer
    On an operator, the compose is docker-compose.operator.yml, and the frame's host runs it.
  4. A database password changes inside the database first (see Database Passwords), or the volume is recreated.

Keys That Must Match ​

Key AKey BReason
API_KEY_SECRETTEG_REGISTRY_JWT_SECRETThe generator writes them equal; rotate them together.
PG_PASS_REGISTRY, PG_PASS_TEGpgbouncer.ini, userlist.txt (operator)The pooler holds the same passwords.

Complete .env.operator Template ​

What operator-setup.sh writes on a standalone registry, values replaced:

bash
# .env.operator: generated by generate-operator-env.sh. Do not commit: it contains secrets.

# -- Identity
REGISTRY_NAME="<your-registry-name>"
OPERATOR_DID=did:theprotocol:operator-<16 hex characters>
TRUST_DOMAIN=<your-registry-name>.local

# -- Database passwords
PG_PASS_REGISTRY=<48 hex characters>
PG_PASS_TEG=<48 hex characters>
PG_PASS_EVENT_STORE=<48 hex characters>

# -- Security keys
SECRET_KEY=<64 hex characters, read by nothing>
JWT_SECRET_KEY=<64 hex characters, read by nothing>
API_KEY_SECRET=<64 hex characters>
TEG_REGISTRY_JWT_SECRET=<the same as API_KEY_SECRET>
TEG_ADMIN_API_KEY=<64 hex characters>
TEG_AVTP_SYSTEM_API_KEY=<64 hex characters>
TEG_TOKEN_SIGNING_KEY=<64 hex characters>
EVENT_STORE_INTERNAL_API_KEY=<64 hex characters>

# -- Production checks: put your public https address in the list when you set BASE_URL
ALLOWED_ORIGINS=["http://localhost:8000"]
FEDERATION_HEALTH_CHECK_SECRET=<64 hex characters>

# -- Units
TEG_ID=teg-layer
MINTING_AUTHORITY=teg-layer

# -- Federation (empty on a standalone registry)
FEDERATION_LICENSE_KEY=
KAFKA_BOOTSTRAP_SERVERS=
KAFKA_ENABLED=false
FEDERATION_SYNC_INTERVAL_SECONDS=30

# -- Email (configure before real users register)
MAIL_SERVER=smtp.example.com
MAIL_PORT=587
MAIL_USERNAME=noreply@example.com
MAIL_PASSWORD=CHANGE_ME
MAIL_FROM=noreply@example.com
MAIL_FROM_NAME="<your-registry-name>"
MAIL_STARTTLS=True
MAIL_SSL_TLS=False

# -- Monitoring
GRAFANA_ADMIN_PASSWORD=<32 hex characters>

# -- Features
ENABLE_PROJECTION_SNAPSHOTS=true
GENESIS_GRANT_ENABLED=true
GENESIS_GRANT_AMOUNT=5000.0
BETA_INVITE_REQUIRED=false
AUDITED_BALANCE_ENABLED=true

# -- The ledger's broker: the event store's password and the key it signs every record with
KAFKA_ES_PASSWORD=<64 hex characters>
ES_KAFKA_RECORD_KEY=<64 hex characters>

The operator generator in a bundle writes the same kind of file with MINTING_AUTHORITY=disabled, CROSS_TEG_ENABLED=true, RELEASE_CHANNEL_CHECK_ENABLED=true and no TRUST_DOMAIN, TEG_ID or event store key, and under a name that does not start with cloud-op- the operator's own Redis passwords and proxy trust secrets; for a cloud operator, the frame's provisioner then appends the values it holds for it (its addresses, its licence, its secrets and the frame's switches).


See also: Quickstart (chapter 00) | Architecture (chapter 01) | Federation Guide (chapter 03)

Server components AGPL-3.0-or-later · SDKs and the auditor Apache-2.0 · this documentation CC BY 4.0. If a doc and the running stack disagree, trust the stack. Legal notice (Impressum) · Privacy · Terms