{
  "schemaVersion": "1.0",
  "title": "getaip-server configuration",
  "description": "This reference lists the complete command-line configuration of the product-neutral getaip-server gateway. Use it to look up process identity, native authentication, durable state, callbacks, connector-fleet routing, NATS, delegation, and M",
  "canonical": "https://getaip.org/docs/reference/configuration",
  "route": "/docs/reference/configuration",
  "source": "docs/reference/configuration.md",
  "protocol": "Agent Interoperability Protocol",
  "protocolVersion": "1.0",
  "section": "Deploy and Operate",
  "documentType": "Reference",
  "language": "en",
  "revision": {
    "lastReviewedRevision": "d7cce13d1d555644d04a4d73c66c95b113737635",
    "documentationSourceRevision": "9192fef3695ad294994f2712f6d156241e5e92fb",
    "basis": "frontmatter"
  },
  "downloads": {
    "md": "/docs/download/reference/configuration.md",
    "txt": "/docs/download/reference/configuration.txt",
    "json": "/docs/download/reference/configuration.json",
    "pdf": "/docs/download/reference/configuration.pdf"
  },
  "content": {
    "format": "text/markdown",
    "markdown": "---\ntitle: GetAIP Server configuration\ndescription: Look up every product-neutral gateway option and its startup constraints\nkind: reference\naudience: operator\nappliesTo: \"1.x\"\nwritingStandard: \"aip-docs/1.0\"\nlastReviewedRevision: \"d7cce13d1d555644d04a4d73c66c95b113737635\"\n---\n\n# `getaip-server` configuration\n\nThis reference lists the complete command-line configuration of the\nproduct-neutral `getaip-server` gateway. Use it to look up process identity, native\nauthentication, durable state, callbacks, connector-fleet routing, NATS,\ndelegation, and MCP settings without mixing product credentials into the\ngateway process.\n\nThe option surface is implemented by `CoreArgs` at source revision\n`d7cce13d1d555644d04a4d73c66c95b113737635`. It does not include Cal.diy,\nHermes Agent, Chatwoot, Dify, CrewAI, or Twenty provider settings. Those belong\nto standalone connector hosts. Existing bundled Cal.diy or Hermes Agent\ndeployments use the separate\n[legacy bundled deployment](../guides/legacy-bundled-deployment.md).\n\nAll defaults below are implementation defaults for the reviewed revision, not\ncapacity recommendations or evidence that a deployment has qualified for its\nintended load.\n\n## Value resolution\n\nMost single-value settings resolve in this order:\n\n1. command-line option;\n2. corresponding environment variable;\n3. implementation default or unset.\n\nBoolean command-line and environment switches are combined: either one can\nenable the behavior. Repeatable command-line lists are extended with values\nfrom their environment list. The complete environment inventory and delimiter\nrules live in [Environment variables](environment-variables.md).\n\nThere are two precedence exceptions. `GETAIP_SERVER_NATIVE_PRINCIPAL` overrides the\nvalue parsed from `--native-principal`, and `GETAIP_SERVER_MCP_PRINCIPAL` overrides the\nvalue parsed from `--mcp-principal`. `GETAIP_SERVER_NATS_REQUEST_TIMEOUT_MS` also\noverrides the CLI timeout value. Configure only one source for these values.\n\nInline and file forms of the same secret are mutually exclusive even when one\nform comes from the environment. Prefer the file form when it exists.\n\n## Process identity and modes\n\n| Option | Default | Meaning and constraint |\n|---|---:|---|\n| `--bind ADDRESS` | `127.0.0.1:8080` | HTTP listener. Insecure development mode is restricted to a loopback address. |\n| `--public-base-url URL` | Unset | External origin advertised for A2A and capability discovery. It must be an origin without credentials, path, query, or fragment. |\n| `--service-id PRINCIPAL_ID` | `agent:getaip:server:local` | Stable principal reported in the manifest and used by configured signing identities. |\n| `--trust-domain DOMAIN` | Unset | Trust domain reported by the deployment. Fleet and delegation composition use `local` when it is unset. |\n| `--print-manifest` | Off | Prepare the complete deployment, print its manifest as JSON, and exit without serving. |\n| `--mcp-stdio` | Off | Prepare the deployment and serve newline-delimited MCP through stdin and stdout instead of HTTP. |\n\nA non-loopback listener requires an explicit HTTPS public base URL. Insecure\ndevelopment is restricted to a loopback listener. HTTP public origins are\naccepted only when both the listener and origin are loopback-scoped and\ninsecure development is explicit.\n\n`--print-manifest` takes precedence over `--mcp-stdio` when both are present.\nStartup failures are emitted as structured JSON on stderr and exit with a\nnon-zero status.\n\n## Native authentication and trust\n\n| Option | Default | Meaning and constraint |\n|---|---:|---|\n| `--require-signed-envelopes` | Signed by default | Explicitly require Ed25519 signatures on incoming native AIP envelopes. |\n| `--trusted-signer DID=PRINCIPAL_ID` | None | Add one Ed25519 `did:key` to principal binding; repeatable. |\n| `--trusted-signer-file PATH` | Unset | Load additional signer bindings from a bounded JSON file. |\n| `--native-bearer-token TOKEN` | Unset | Inline bearer token for native HTTP routes. Prefer the file form. |\n| `--native-bearer-token-file FILE` | Unset | Load the native bearer token from a mode-0600 file. |\n| `--native-principal PRINCIPAL_ID` | `service:getaip:server:http-edge` | Principal established after native bearer authentication. |\n| `--native-tenant-id TENANT_ID` | Unset | Verified tenant bound to the native bearer identity for fleet discovery and routing. |\n| `--native-principal-scope SCOPE` | None | Add one scope to the authenticated native principal; repeatable. |\n| `--trusted-identity-file PATH` | Deny all | Load revisioned trusted principal, tenant, credential, and identity bindings. |\n| `--approval-authority-file PATH` | Deny all | Load revisioned approval-authority memberships. |\n| `--allow-insecure-development` | Off | Permit unauthenticated native traffic only on a loopback listener. |\n\nIncoming envelopes are signed by default unless\n`GETAIP_SERVER_ALLOW_UNSIGNED_ENVELOPES` explicitly disables the default and neither\nthe CLI nor `GETAIP_SERVER_REQUIRE_SIGNED_ENVELOPES` restores it. Outside insecure\ndevelopment, unsigned native envelopes still require native bearer\nauthentication. Caller-supplied `from` data is not a replacement for an\nauthenticated edge identity.\n\nInline and file signer bindings are merged. Every signer DID must be a valid\nEd25519 `did:key`, and DIDs must be unique across both sources. The signer file\nuses this exact shape and rejects unknown fields:\n\n```json\n[\n  {\n    \"signer_did\": \"did:key:<ed25519-multibase-value>\",\n    \"principal_id\": \"service:trusted-edge\"\n  }\n]\n```\n\nThe trusted identity file rejects an empty directory, zero revisions, revoked\nor expired entries, duplicate principals, and invalid tenant or credential\nbindings. The approval file rejects an empty directory, zero revisions,\nduplicate principals, and invalid memberships. When either file is absent,\nthe corresponding resolver denies the operation rather than trusting an\nimplicit identity.\n\n## Callback policy and runtime work budgets\n\n| Option | Default | Meaning and constraint |\n|---|---:|---|\n| `--callback-allowed-host HOST` | None | Add one exact outbound callback host; repeatable. |\n| `--callback-signing-seed-hex HEX` | Unset | Inline 32-byte Ed25519 seed as 64 hexadecimal characters. Prefer the file form. |\n| `--callback-signing-seed-file FILE` | Unset | Load the response and callback signing seed from a mode-0600 file. |\n| `--a2a-push-encryption-key-hex HEX` | Unset | Inline 32-byte key used to encrypt stored A2A push credentials. |\n| `--callback-allow-http` | Off | Permit plaintext HTTP callback targets. |\n| `--callback-allow-private-networks` | Off | Permit private, loopback, link-local, or otherwise non-public callback targets. |\n| `--callback-max-in-flight COUNT` | `64` | Maximum callback deliveries executing concurrently in one runtime. |\n| `--callback-recovery-batch COUNT` | `64` | Maximum callback records leased by one recovery cycle. |\n| `--reconciliation-max-in-flight COUNT` | `32` | Maximum transaction reconciliations executing concurrently. |\n\nAn allowed callback host requires a response and callback signing seed. An A2A\npush encryption key also requires that signing seed. Each work budget must be\ngreater than zero.\n\nThe callback request timeout and maximum response size are environment-only\nsettings in this revision. Their defaults are 5,000 milliseconds and 4 MiB.\nSee the environment reference for their exact names.\n\nThe HTTP and private-network switches weaken the default destination policy.\nThey affect callbacks, HTTP delegation destinations, and other routes that use\nthe shared callback policy. Keep them disabled unless the deployment owns and\nreviews the complete isolated network path.\n\n## Runtime storage\n\n| Option | Default | Meaning and constraint |\n|---|---:|---|\n| `--storage-dir DIR` | Unset | Durable local runtime and auxiliary file state for a single-process topology. |\n| `--postgres-url URL` | Unset | Inline clustered runtime PostgreSQL URL. Prefer the file form. |\n| `--postgres-url-file FILE` | Unset | Load the clustered runtime PostgreSQL URL from a mode-0600 file. |\n\n`--postgres-url` and `--postgres-url-file` are mutually exclusive. PostgreSQL\nis the core runtime store when either form resolves. Otherwise, a configured\nstorage directory supplies durable local runtime state; without either, core\nruntime state is in memory.\n\nThe storage directory can still own MCP correlation and replay files when\nPostgreSQL owns core runtime state. Treat both stores as one recovery boundary\nwhen both are configured. Use PostgreSQL for replicas that share one logical\nruntime; do not point several processes at one local storage directory.\n\n## Connector-fleet activation and transport\n\nFleet mode is disabled when no connector-registry URL resolves. Supplying any\nother fleet, topology, admission, or connector-event CLI option without that\nURL is a configuration error. The environment reference records the exact\nactivation behavior for environment-only settings.\n\n| Option | Default | Meaning and constraint |\n|---|---:|---|\n| `--connector-registry-url URL` | Unset | Inline PostgreSQL data-plane URL for catalog and routing. Prefer the file form. |\n| `--connector-registry-url-file FILE` | Unset | Load the registry data-plane URL from a mode-0600 file. |\n| `--connector-registry-data-max-connections COUNT` | `32` | Maximum registry data-plane connections; greater than zero. |\n| `--connector-registry-acquire-timeout-ms MILLISECONDS` | `5000` | Maximum registry connection wait; greater than zero and no more than 60 seconds. |\n| `--connector-fleet-signing-seed-file FILE` | Required in fleet mode | Mode-0600 file containing the gateway's 32-byte Ed25519 seed as hexadecimal text. |\n| `--connector-fleet-callback-url URL` | Unset | Central streamed-action callback URL ending exactly in `/aip/v1/connector-callbacks`. |\n| `--connector-fleet-allowed-host HOST` | None | Add one exact connector-host DNS name or IP literal; repeatable. |\n| `--connector-fleet-trust-registry-endpoints` | Off | Derive the destination host allowlist from admitted registry endpoints per route. |\n| `--connector-fleet-allow-http` | Off | Permit plaintext connector-host or fleet callback URLs. |\n| `--connector-fleet-allow-private-networks` | Off | Permit private, loopback, link-local, or otherwise non-public connector-host addresses. |\n| `--connector-fleet-timeout-ms MILLISECONDS` | `5000` | Timeout for one connector-host request; greater than zero. |\n| `--connector-fleet-max-response-bytes BYTES` | `4194304` | Maximum accepted connector-host response; greater than zero. |\n| `--connector-fleet-retry-budget COUNT` | `2` | Transport retries after the first connector-host attempt. |\n| `--connector-fleet-max-cached-clients COUNT` | `256` | Maximum cached connector-host HTTP connection pools; greater than zero. |\n| `--connector-fleet-tls-ca-file FILE` | Unset | Additional PEM root used to verify private-PKI connector-host TLS. |\n\nFleet mode requires a registry URL, signing-seed file, and one of these\ndestination policies:\n\n- at least one explicit `--connector-fleet-allowed-host`; or\n- `--connector-fleet-trust-registry-endpoints`.\n\nThe gateway opens the registry through the data-plane constructor. The\nconfigured database role must not have registry-administrator authority. The\nadditional CA augments the public trust roots; it does not disable certificate\nor hostname verification.\n\nThe fleet callback URL must be an absolute HTTP(S) URL with no credentials,\nquery, or fragment and the exact callback path. Plain HTTP requires the\nexplicit fleet HTTP exception. Configuring the URL makes remote streaming\navailable; without it, the remote implementation support does not advertise\nstreaming.\n\n## Fleet topology and local admission\n\n| Option | Default | Meaning and constraint |\n|---|---:|---|\n| `--connector-fleet-region REGION` | No preference | Prefer this region for a new route assignment. |\n| `--connector-fleet-zone ZONE` | No preference | Prefer this zone for a new route assignment. |\n| `--connector-fleet-capacity-class CLASS` | No preference | Require this capacity class for a new route assignment. |\n| `--connector-fleet-disable-cross-region-failover` | Off | Reject fallback to another region for a new assignment. |\n| `--connector-fleet-max-in-flight COUNT` | `1024` | Maximum remote connector actions executing through this daemon. |\n| `--connector-fleet-max-in-flight-per-tenant COUNT` | `128` | Maximum executing remote actions for one verified tenant. |\n| `--connector-fleet-max-queued COUNT` | `4096` | Maximum remote actions waiting for a local dispatch permit. |\n| `--connector-fleet-max-queued-per-tenant COUNT` | `512` | Maximum waiting actions for one verified tenant. |\n| `--connector-fleet-max-queue-bytes BYTES` | `67108864` | Maximum canonical bytes retained by all waiting actions. |\n| `--connector-fleet-max-request-bytes BYTES` | `4194304` | Maximum canonical size of one remote action. |\n| `--connector-fleet-max-queue-age-ms MILLISECONDS` | `30000` | Maximum time an action may wait for local admission. |\n| `--connector-fleet-tenant-weight TENANT_ID=WEIGHT` | None | Add one positive scheduling weight for a verified tenant; repeatable. |\n\nEvery numeric admission bound must be greater than zero. The per-tenant\nin-flight bound cannot exceed the global in-flight bound, and the per-tenant\nqueue bound cannot exceed the global queue bound. Tenant IDs in weight entries\ncontain 1–256 bytes, weights are positive, and a tenant can appear only once\nacross the merged CLI and environment list.\n\nTopology preferences apply when the registry creates a new assignment. An\nexisting action remains pinned to its assigned replica; changing a preference\ndoes not move active work.\n\n## Connector-event and stream ingress\n\nThese options configure the gateway's shared authenticated connector-event\ningress. They are valid only in fleet mode.\n\n| Option | Default | Meaning and constraint |\n|---|---:|---|\n| `--connector-event-max-envelope-bytes BYTES` | `4194304` | Maximum serialized signed envelope size. |\n| `--connector-event-max-events-per-envelope COUNT` | `100` | Maximum events in one existing AIP event stream; range 1–1000. |\n| `--connector-event-max-event-bytes BYTES` | `262144` | Maximum serialized size of one enriched event; no more than the envelope bound. |\n| `--connector-stream-max-chunk-bytes BYTES` | `262144` | Maximum serialized connector stream chunk; no more than the envelope bound. |\n| `--connector-event-max-in-flight COUNT` | `128` | Maximum concurrent connector-event storage operations. |\n| `--connector-event-max-age-seconds SECONDS` | `86400` | Maximum accepted age of a connector-originated event. |\n| `--connector-event-max-future-skew-seconds SECONDS` | `300` | Maximum accepted future clock skew for a connector event. |\n| `--connector-stream-callback-max-age-seconds SECONDS` | `300` | Maximum accepted age of a signed connector stream callback. |\n\nEvery limit must be greater than zero. Event and stream envelopes still require\nthe admitted route identity, signature, timestamp, sequence, replay, and\nassignment checks; increasing a size or time limit does not bypass those\nchecks.\n\n## Native NATS\n\n| Option | Default | Meaning and constraint |\n|---|---:|---|\n| `--nats-url URL` | Unset | Enable the native NATS request/reply listener. |\n| `--nats-username USERNAME` | Unset | NATS username; requires a password file and server URL. |\n| `--nats-password-file FILE` | Unset | Mode-0600 NATS password file; requires a username and server URL. |\n| `--nats-trust-domain DOMAIN` | Daemon trust domain | Trust-domain subject segment. |\n| `--nats-service SERVICE` | `getaip-server` | Service subject segment. |\n| `--nats-version VERSION` | `v1` | Version subject segment. |\n| `--nats-queue-group GROUP` | Unset | Optional queue group for scaled consumers. |\n| `--nats-request-timeout-ms MILLISECONDS` | `30000` | Outbound NATS request timeout. |\n\nNATS is disabled when the server URL is absent. Supplying authentication\nwithout a server URL is an error. Username and password file must appear\ntogether; configuring neither selects an unauthenticated connection and does\nnot create TLS, account, or subject authorization outside the process.\n\n## Remote delegation routes\n\n| Option | Default | Meaning and constraint |\n|---|---:|---|\n| `--delegation-http-route SPEC` | None | Route one delegate principal to an authenticated native HTTP peer; repeatable. |\n| `--delegation-nats-route SPEC` | None | Route one child capability to an authenticated native NATS peer; repeatable. |\n\nHTTP route syntax is:\n\n```text\nDELEGATE_ID=URL,PEER_ID,PEER_DID[,TRUST_DOMAIN]\n```\n\nNATS route syntax is:\n\n```text\nCAPABILITY_ID=SERVER_URL,SUBJECT,PEER_ID,PEER_DID[,TIMEOUT_MS[,TRUST_DOMAIN]]\n```\n\nThe NATS route timeout defaults to 30,000 milliseconds. Both route forms use\nthe daemon trust domain when the optional route trust domain is absent. Routes\nrequire a response and callback signing seed, a valid peer principal and\n`did:key`, and a destination accepted by the shared callback policy. The\ndaemon validates each route before serving.\n\n## MCP compatibility profile\n\n| Option | Default | Meaning and constraint |\n|---|---:|---|\n| `--mcp-bearer-token TOKEN` | Unset | Static bearer token for MCP HTTP. Do not combine with introspection. |\n| `--mcp-resource RESOURCE` | Derived or unset | Protected-resource identifier advertised for MCP HTTP. |\n| `--mcp-authorization-server ISSUER` | None | Add one advertised authorization server; repeatable. |\n| `--mcp-scope SCOPE` | None | Add one advertised supported scope; repeatable. |\n| `--mcp-required-scope SCOPE` | None | Add one scope required to establish an MCP HTTP session; repeatable. |\n| `--mcp-introspection-url HTTPS_URL` | Unset | RFC 7662 token introspection endpoint. |\n| `--mcp-introspection-issuer ISSUER` | Unset | Trusted issuer represented by the introspection endpoint. |\n| `--mcp-introspection-client-id CLIENT_ID` | Unset | OAuth client ID used for introspection. |\n| `--mcp-introspection-client-secret-file FILE` | Unset | Mode-0600 introspection client-secret file. |\n| `--mcp-introspection-allow-loopback-http` | Off | Permit a loopback plaintext introspection endpoint. |\n| `--mcp-resource-documentation URL` | Unset | Human-readable protected-resource documentation URL. |\n| `--mcp-allowed-origin ORIGIN` | None | Add one browser origin allowed to call MCP HTTP; repeatable. |\n| `--mcp-principal PRINCIPAL_ID` | `service:getaip:server:mcp-edge` | Principal established after MCP transport authentication. |\n| `--mcp-principal-scope SCOPE` | None | Add one scope to that authenticated principal; repeatable. |\n\nIf a static token, authorization server, supported scope, or documentation URL\nis set without an explicit resource, the implementation derives\n`http://<bind>/mcp`. Set `--mcp-resource` explicitly for a public deployment so\nthe protected-resource identifier matches the external origin.\n\nIntrospection is an all-or-none group: URL, issuer, client ID, and secret file\nmust all resolve. It also requires a protected-resource policy, rejects a\nsimultaneous static token, and requires the introspection issuer to appear in\nthe advertised authorization-server list. The URL must use HTTPS unless the\nexplicit exception permits a loopback HTTP fixture.\n\nThe protected-resource configuration permits loopback browser origins in\naddition to the explicit origin list. Treat MCP stdio as a separate local\ntransport whose authentication boundary is the trusted spawning process.\n\n## File contracts\n\nSecret files must be regular non-symlink files. On Unix the loader rejects any\ngroup or other permission bit and reports the expected contract as mode\n`0600`; an owner-readable `0400` mount also satisfies the implemented bitmask.\n\nSecret values are bounded by their owning option and decoded as UTF-8 where\nrequired. The common inline-or-file text resolver trims values and rejects an\nempty result; other secret consumers apply their own parser.\n\nTrusted signer, trusted identity, approval authority, and fleet TLS CA files\nuse the secure-configuration loader. They must be regular non-symlink files,\ncannot exceed 1 MiB, and cannot be group- or world-writable on Unix. Read-only\naccess for a deployment-owned group is therefore different from secret-file\npermission and should be granted only when the owning policy requires it.\n\nMount configuration and secrets read-only. The process reads them during\nstartup; this revision does not implement an in-process configuration reload.\nA changed value requires a controlled restart and the recovery procedure owned\nby that setting.\n\n## Startup coupling summary\n\n| Setting present | Required companion configuration |\n|---|---|\n| Non-loopback listener | Public HTTPS base URL and an authenticated deployment edge |\n| Unsigned native envelopes | Native bearer authentication or loopback-only insecure development |\n| Callback allowed hosts | Response and callback signing seed |\n| A2A push encryption key | Response and callback signing seed |\n| Delegation route | Response and callback signing seed plus valid peer identity and destination |\n| PostgreSQL URL | Exactly one inline or file source |\n| Any fleet option | Connector-registry URL |\n| Fleet registry URL | Signing-seed file and explicit or registry-derived host allowlist |\n| Fleet stream callback | Exact central callback URL; HTTP exception if plaintext |\n| NATS username or password | NATS URL and the other credential half |\n| Any introspection field | Complete four-field introspection group and protected resource |\n| MCP introspection | Advertised matching issuer and no static MCP token |\n\nUse [Deploy AIP in production](../guides/production-deployment.md) for the\nordered deployment procedure, [Connector host configuration](connector-host-configuration.md)\nfor the separate host process, and [Observe and recover](../guides/observe-and-recover.md)\nfor runtime diagnosis. This page owns option lookup; those guides own task\nflow and recovery decisions.\n",
    "text": "getaip-server configuration\n\nThis reference lists the complete command-line configuration of the\nproduct-neutral getaip-server gateway. Use it to look up process identity, native\nauthentication, durable state, callbacks, connector-fleet routing, NATS,\ndelegation, and MCP settings without mixing product credentials into the\ngateway process.\n\nThe option surface is implemented by CoreArgs at source revision\nd7cce13d1d555644d04a4d73c66c95b113737635. It does not include Cal.diy,\nHermes Agent, Chatwoot, Dify, CrewAI, or Twenty provider settings. Those belong\nto standalone connector hosts. Existing bundled Cal.diy or Hermes Agent\ndeployments use the separate\nlegacy bundled deployment (../guides/legacy-bundled-deployment.md).\n\nAll defaults below are implementation defaults for the reviewed revision, not\ncapacity recommendations or evidence that a deployment has qualified for its\nintended load.\n\nValue resolution\n\nMost single-value settings resolve in this order:\n1. command-line option;\n2. corresponding environment variable;\n3. implementation default or unset.\n\nBoolean command-line and environment switches are combined: either one can\nenable the behavior. Repeatable command-line lists are extended with values\nfrom their environment list. The complete environment inventory and delimiter\nrules live in Environment variables (environment-variables.md).\n\nThere are two precedence exceptions. GETAIPSERVERNATIVEPRINCIPAL overrides the\nvalue parsed from --native-principal, and GETAIPSERVERMCPPRINCIPAL overrides the\nvalue parsed from --mcp-principal. GETAIPSERVERNATSREQUESTTIMEOUTMS also\noverrides the CLI timeout value. Configure only one source for these values.\n\nInline and file forms of the same secret are mutually exclusive even when one\nform comes from the environment. Prefer the file form when it exists.\n\nProcess identity and modes\n\n| Option | Default | Meaning and constraint |\n\n| --bind ADDRESS | 127.0.0.1:8080 | HTTP listener. Insecure development mode is restricted to a loopback address. |\n| --public-base-url URL | Unset | External origin advertised for A2A and capability discovery. It must be an origin without credentials, path, query, or fragment. |\n| --service-id PRINCIPALID | agent:getaip:server:local | Stable principal reported in the manifest and used by configured signing identities. |\n| --trust-domain DOMAIN | Unset | Trust domain reported by the deployment. Fleet and delegation composition use local when it is unset. |\n| --print-manifest | Off | Prepare the complete deployment, print its manifest as JSON, and exit without serving. |\n| --mcp-stdio | Off | Prepare the deployment and serve newline-delimited MCP through stdin and stdout instead of HTTP. |\n\nA non-loopback listener requires an explicit HTTPS public base URL. Insecure\ndevelopment is restricted to a loopback listener. HTTP public origins are\naccepted only when both the listener and origin are loopback-scoped and\ninsecure development is explicit.\n\n--print-manifest takes precedence over --mcp-stdio when both are present.\nStartup failures are emitted as structured JSON on stderr and exit with a\nnon-zero status.\n\nNative authentication and trust\n\n| Option | Default | Meaning and constraint |\n\n| --require-signed-envelopes | Signed by default | Explicitly require Ed25519 signatures on incoming native AIP envelopes. |\n| --trusted-signer DID=PRINCIPALID | None | Add one Ed25519 did:key to principal binding; repeatable. |\n| --trusted-signer-file PATH | Unset | Load additional signer bindings from a bounded JSON file. |\n| --native-bearer-token TOKEN | Unset | Inline bearer token for native HTTP routes. Prefer the file form. |\n| --native-bearer-token-file FILE | Unset | Load the native bearer token from a mode-0600 file. |\n| --native-principal PRINCIPALID | service:getaip:server:http-edge | Principal established after native bearer authentication. |\n| --native-tenant-id TENANTID | Unset | Verified tenant bound to the native bearer identity for fleet discovery and routing. |\n| --native-principal-scope SCOPE | None | Add one scope to the authenticated native principal; repeatable. |\n| --trusted-identity-file PATH | Deny all | Load revisioned trusted principal, tenant, credential, and identity bindings. |\n| --approval-authority-file PATH | Deny all | Load revisioned approval-authority memberships. |\n| --allow-insecure-development | Off | Permit unauthenticated native traffic only on a loopback listener. |\n\nIncoming envelopes are signed by default unless\nGETAIPSERVERALLOWUNSIGNEDENVELOPES explicitly disables the default and neither\nthe CLI nor GETAIPSERVERREQUIRESIGNEDENVELOPES restores it. Outside insecure\ndevelopment, unsigned native envelopes still require native bearer\nauthentication. Caller-supplied from data is not a replacement for an\nauthenticated edge identity.\n\nInline and file signer bindings are merged. Every signer DID must be a valid\nEd25519 did:key, and DIDs must be unique across both sources. The signer file\nuses this exact shape and rejects unknown fields:\n\n[\n  {\n    \"signerdid\": \"did:key:\",\n    \"principalid\": \"service:trusted-edge\"\n  }\n]\n\nThe trusted identity file rejects an empty directory, zero revisions, revoked\nor expired entries, duplicate principals, and invalid tenant or credential\nbindings. The approval file rejects an empty directory, zero revisions,\nduplicate principals, and invalid memberships. When either file is absent,\nthe corresponding resolver denies the operation rather than trusting an\nimplicit identity.\n\nCallback policy and runtime work budgets\n\n| Option | Default | Meaning and constraint |\n\n| --callback-allowed-host HOST | None | Add one exact outbound callback host; repeatable. |\n| --callback-signing-seed-hex HEX | Unset | Inline 32-byte Ed25519 seed as 64 hexadecimal characters. Prefer the file form. |\n| --callback-signing-seed-file FILE | Unset | Load the response and callback signing seed from a mode-0600 file. |\n| --a2a-push-encryption-key-hex HEX | Unset | Inline 32-byte key used to encrypt stored A2A push credentials. |\n| --callback-allow-http | Off | Permit plaintext HTTP callback targets. |\n| --callback-allow-private-networks | Off | Permit private, loopback, link-local, or otherwise non-public callback targets. |\n| --callback-max-in-flight COUNT | 64 | Maximum callback deliveries executing concurrently in one runtime. |\n| --callback-recovery-batch COUNT | 64 | Maximum callback records leased by one recovery cycle. |\n| --reconciliation-max-in-flight COUNT | 32 | Maximum transaction reconciliations executing concurrently. |\n\nAn allowed callback host requires a response and callback signing seed. An A2A\npush encryption key also requires that signing seed. Each work budget must be\ngreater than zero.\n\nThe callback request timeout and maximum response size are environment-only\nsettings in this revision. Their defaults are 5,000 milliseconds and 4 MiB.\nSee the environment reference for their exact names.\n\nThe HTTP and private-network switches weaken the default destination policy.\nThey affect callbacks, HTTP delegation destinations, and other routes that use\nthe shared callback policy. Keep them disabled unless the deployment owns and\nreviews the complete isolated network path.\n\nRuntime storage\n\n| Option | Default | Meaning and constraint |\n\n| --storage-dir DIR | Unset | Durable local runtime and auxiliary file state for a single-process topology. |\n| --postgres-url URL | Unset | Inline clustered runtime PostgreSQL URL. Prefer the file form. |\n| --postgres-url-file FILE | Unset | Load the clustered runtime PostgreSQL URL from a mode-0600 file. |\n\n--postgres-url and --postgres-url-file are mutually exclusive. PostgreSQL\nis the core runtime store when either form resolves. Otherwise, a configured\nstorage directory supplies durable local runtime state; without either, core\nruntime state is in memory.\n\nThe storage directory can still own MCP correlation and replay files when\nPostgreSQL owns core runtime state. Treat both stores as one recovery boundary\nwhen both are configured. Use PostgreSQL for replicas that share one logical\nruntime; do not point several processes at one local storage directory.\n\nConnector-fleet activation and transport\n\nFleet mode is disabled when no connector-registry URL resolves. Supplying any\nother fleet, topology, admission, or connector-event CLI option without that\nURL is a configuration error. The environment reference records the exact\nactivation behavior for environment-only settings.\n\n| Option | Default | Meaning and constraint |\n\n| --connector-registry-url URL | Unset | Inline PostgreSQL data-plane URL for catalog and routing. Prefer the file form. |\n| --connector-registry-url-file FILE | Unset | Load the registry data-plane URL from a mode-0600 file. |\n| --connector-registry-data-max-connections COUNT | 32 | Maximum registry data-plane connections; greater than zero. |\n| --connector-registry-acquire-timeout-ms MILLISECONDS | 5000 | Maximum registry connection wait; greater than zero and no more than 60 seconds. |\n| --connector-fleet-signing-seed-file FILE | Required in fleet mode | Mode-0600 file containing the gateway's 32-byte Ed25519 seed as hexadecimal text. |\n| --connector-fleet-callback-url URL | Unset | Central streamed-action callback URL ending exactly in /aip/v1/connector-callbacks. |\n| --connector-fleet-allowed-host HOST | None | Add one exact connector-host DNS name or IP literal; repeatable. |\n| --connector-fleet-trust-registry-endpoints | Off | Derive the destination host allowlist from admitted registry endpoints per route. |\n| --connector-fleet-allow-http | Off | Permit plaintext connector-host or fleet callback URLs. |\n| --connector-fleet-allow-private-networks | Off | Permit private, loopback, link-local, or otherwise non-public connector-host addresses. |\n| --connector-fleet-timeout-ms MILLISECONDS | 5000 | Timeout for one connector-host request; greater than zero. |\n| --connector-fleet-max-response-bytes BYTES | 4194304 | Maximum accepted connector-host response; greater than zero. |\n| --connector-fleet-retry-budget COUNT | 2 | Transport retries after the first connector-host attempt. |\n| --connector-fleet-max-cached-clients COUNT | 256 | Maximum cached connector-host HTTP connection pools; greater than zero. |\n| --connector-fleet-tls-ca-file FILE | Unset | Additional PEM root used to verify private-PKI connector-host TLS. |\n\nFleet mode requires a registry URL, signing-seed file, and one of these\ndestination policies:\n• at least one explicit --connector-fleet-allowed-host; or\n• --connector-fleet-trust-registry-endpoints.\n\nThe gateway opens the registry through the data-plane constructor. The\nconfigured database role must not have registry-administrator authority. The\nadditional CA augments the public trust roots; it does not disable certificate\nor hostname verification.\n\nThe fleet callback URL must be an absolute HTTP(S) URL with no credentials,\nquery, or fragment and the exact callback path. Plain HTTP requires the\nexplicit fleet HTTP exception. Configuring the URL makes remote streaming\navailable; without it, the remote implementation support does not advertise\nstreaming.\n\nFleet topology and local admission\n\n| Option | Default | Meaning and constraint |\n\n| --connector-fleet-region REGION | No preference | Prefer this region for a new route assignment. |\n| --connector-fleet-zone ZONE | No preference | Prefer this zone for a new route assignment. |\n| --connector-fleet-capacity-class CLASS | No preference | Require this capacity class for a new route assignment. |\n| --connector-fleet-disable-cross-region-failover | Off | Reject fallback to another region for a new assignment. |\n| --connector-fleet-max-in-flight COUNT | 1024 | Maximum remote connector actions executing through this daemon. |\n| --connector-fleet-max-in-flight-per-tenant COUNT | 128 | Maximum executing remote actions for one verified tenant. |\n| --connector-fleet-max-queued COUNT | 4096 | Maximum remote actions waiting for a local dispatch permit. |\n| --connector-fleet-max-queued-per-tenant COUNT | 512 | Maximum waiting actions for one verified tenant. |\n| --connector-fleet-max-queue-bytes BYTES | 67108864 | Maximum canonical bytes retained by all waiting actions. |\n| --connector-fleet-max-request-bytes BYTES | 4194304 | Maximum canonical size of one remote action. |\n| --connector-fleet-max-queue-age-ms MILLISECONDS | 30000 | Maximum time an action may wait for local admission. |\n| --connector-fleet-tenant-weight TENANTID=WEIGHT | None | Add one positive scheduling weight for a verified tenant; repeatable. |\n\nEvery numeric admission bound must be greater than zero. The per-tenant\nin-flight bound cannot exceed the global in-flight bound, and the per-tenant\nqueue bound cannot exceed the global queue bound. Tenant IDs in weight entries\ncontain 1–256 bytes, weights are positive, and a tenant can appear only once\nacross the merged CLI and environment list.\n\nTopology preferences apply when the registry creates a new assignment. An\nexisting action remains pinned to its assigned replica; changing a preference\ndoes not move active work.\n\nConnector-event and stream ingress\n\nThese options configure the gateway's shared authenticated connector-event\ningress. They are valid only in fleet mode.\n\n| Option | Default | Meaning and constraint |\n\n| --connector-event-max-envelope-bytes BYTES | 4194304 | Maximum serialized signed envelope size. |\n| --connector-event-max-events-per-envelope COUNT | 100 | Maximum events in one existing AIP event stream; range 1–1000. |\n| --connector-event-max-event-bytes BYTES | 262144 | Maximum serialized size of one enriched event; no more than the envelope bound. |\n| --connector-stream-max-chunk-bytes BYTES | 262144 | Maximum serialized connector stream chunk; no more than the envelope bound. |\n| --connector-event-max-in-flight COUNT | 128 | Maximum concurrent connector-event storage operations. |\n| --connector-event-max-age-seconds SECONDS | 86400 | Maximum accepted age of a connector-originated event. |\n| --connector-event-max-future-skew-seconds SECONDS | 300 | Maximum accepted future clock skew for a connector event. |\n| --connector-stream-callback-max-age-seconds SECONDS | 300 | Maximum accepted age of a signed connector stream callback. |\n\nEvery limit must be greater than zero. Event and stream envelopes still require\nthe admitted route identity, signature, timestamp, sequence, replay, and\nassignment checks; increasing a size or time limit does not bypass those\nchecks.\n\nNative NATS\n\n| Option | Default | Meaning and constraint |\n\n| --nats-url URL | Unset | Enable the native NATS request/reply listener. |\n| --nats-username USERNAME | Unset | NATS username; requires a password file and server URL. |\n| --nats-password-file FILE | Unset | Mode-0600 NATS password file; requires a username and server URL. |\n| --nats-trust-domain DOMAIN | Daemon trust domain | Trust-domain subject segment. |\n| --nats-service SERVICE | getaip-server | Service subject segment. |\n| --nats-version VERSION | v1 | Version subject segment. |\n| --nats-queue-group GROUP | Unset | Optional queue group for scaled consumers. |\n| --nats-request-timeout-ms MILLISECONDS | 30000 | Outbound NATS request timeout. |\n\nNATS is disabled when the server URL is absent. Supplying authentication\nwithout a server URL is an error. Username and password file must appear\ntogether; configuring neither selects an unauthenticated connection and does\nnot create TLS, account, or subject authorization outside the process.\n\nRemote delegation routes\n\n| Option | Default | Meaning and constraint |\n\n| --delegation-http-route SPEC | None | Route one delegate principal to an authenticated native HTTP peer; repeatable. |\n| --delegation-nats-route SPEC | None | Route one child capability to an authenticated native NATS peer; repeatable. |\n\nHTTP route syntax is:\n\nDELEGATEID=URL,PEERID,PEERDID[,TRUSTDOMAIN]\n\nNATS route syntax is:\n\nCAPABILITYID=SERVERURL,SUBJECT,PEERID,PEERDID[,TIMEOUTMS[,TRUSTDOMAIN]]\n\nThe NATS route timeout defaults to 30,000 milliseconds. Both route forms use\nthe daemon trust domain when the optional route trust domain is absent. Routes\nrequire a response and callback signing seed, a valid peer principal and\ndid:key, and a destination accepted by the shared callback policy. The\ndaemon validates each route before serving.\n\nMCP compatibility profile\n\n| Option | Default | Meaning and constraint |\n\n| --mcp-bearer-token TOKEN | Unset | Static bearer token for MCP HTTP. Do not combine with introspection. |\n| --mcp-resource RESOURCE | Derived or unset | Protected-resource identifier advertised for MCP HTTP. |\n| --mcp-authorization-server ISSUER | None | Add one advertised authorization server; repeatable. |\n| --mcp-scope SCOPE | None | Add one advertised supported scope; repeatable. |\n| --mcp-required-scope SCOPE | None | Add one scope required to establish an MCP HTTP session; repeatable. |\n| --mcp-introspection-url HTTPSURL | Unset | RFC 7662 token introspection endpoint. |\n| --mcp-introspection-issuer ISSUER | Unset | Trusted issuer represented by the introspection endpoint. |\n| --mcp-introspection-client-id CLIENTID | Unset | OAuth client ID used for introspection. |\n| --mcp-introspection-client-secret-file FILE | Unset | Mode-0600 introspection client-secret file. |\n| --mcp-introspection-allow-loopback-http | Off | Permit a loopback plaintext introspection endpoint. |\n| --mcp-resource-documentation URL | Unset | Human-readable protected-resource documentation URL. |\n| --mcp-allowed-origin ORIGIN | None | Add one browser origin allowed to call MCP HTTP; repeatable. |\n| --mcp-principal PRINCIPALID | service:getaip:server:mcp-edge | Principal established after MCP transport authentication. |\n| --mcp-principal-scope SCOPE | None | Add one scope to that authenticated principal; repeatable. |\n\nIf a static token, authorization server, supported scope, or documentation URL\nis set without an explicit resource, the implementation derives\nhttp:///mcp. Set --mcp-resource explicitly for a public deployment so\nthe protected-resource identifier matches the external origin.\n\nIntrospection is an all-or-none group: URL, issuer, client ID, and secret file\nmust all resolve. It also requires a protected-resource policy, rejects a\nsimultaneous static token, and requires the introspection issuer to appear in\nthe advertised authorization-server list. The URL must use HTTPS unless the\nexplicit exception permits a loopback HTTP fixture.\n\nThe protected-resource configuration permits loopback browser origins in\naddition to the explicit origin list. Treat MCP stdio as a separate local\ntransport whose authentication boundary is the trusted spawning process.\n\nFile contracts\n\nSecret files must be regular non-symlink files. On Unix the loader rejects any\ngroup or other permission bit and reports the expected contract as mode\n0600; an owner-readable 0400 mount also satisfies the implemented bitmask.\n\nSecret values are bounded by their owning option and decoded as UTF-8 where\nrequired. The common inline-or-file text resolver trims values and rejects an\nempty result; other secret consumers apply their own parser.\n\nTrusted signer, trusted identity, approval authority, and fleet TLS CA files\nuse the secure-configuration loader. They must be regular non-symlink files,\ncannot exceed 1 MiB, and cannot be group- or world-writable on Unix. Read-only\naccess for a deployment-owned group is therefore different from secret-file\npermission and should be granted only when the owning policy requires it.\n\nMount configuration and secrets read-only. The process reads them during\nstartup; this revision does not implement an in-process configuration reload.\nA changed value requires a controlled restart and the recovery procedure owned\nby that setting.\n\nStartup coupling summary\n\n| Setting present | Required companion configuration |\n\n| Non-loopback listener | Public HTTPS base URL and an authenticated deployment edge |\n| Unsigned native envelopes | Native bearer authentication or loopback-only insecure development |\n| Callback allowed hosts | Response and callback signing seed |\n| A2A push encryption key | Response and callback signing seed |\n| Delegation route | Response and callback signing seed plus valid peer identity and destination |\n| PostgreSQL URL | Exactly one inline or file source |\n| Any fleet option | Connector-registry URL |\n| Fleet registry URL | Signing-seed file and explicit or registry-derived host allowlist |\n| Fleet stream callback | Exact central callback URL; HTTP exception if plaintext |\n| NATS username or password | NATS URL and the other credential half |\n| Any introspection field | Complete four-field introspection group and protected resource |\n| MCP introspection | Advertised matching issuer and no static MCP token |\n\nUse Deploy AIP in production (../guides/production-deployment.md) for the\nordered deployment procedure, Connector host configuration (connector-host-configuration.md)\nfor the separate host process, and Observe and recover (../guides/observe-and-recover.md)\nfor runtime diagnosis. This page owns option lookup; those guides own task\nflow and recovery decisions.\n"
  },
  "integrity": {
    "algorithm": "sha256",
    "sourceDigest": "45439243da36373c2bd55bc3f6fd7c79e774fe3cc7ef74e06dcb1cc15c3f86bd"
  }
}