{
  "schemaVersion": "1.0",
  "title": "Environment variables",
  "description": "This reference lists all 86 environment variables consumed by the product-neutral getaip-server gateway and separates them from connector control-plane, standalone host, product connector, and getaip settings. Use it to identify which proce",
  "canonical": "https://getaip.org/docs/reference/environment-variables",
  "route": "/docs/reference/environment-variables",
  "source": "docs/reference/environment-variables.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/environment-variables.md",
    "txt": "/docs/download/reference/environment-variables.txt",
    "json": "/docs/download/reference/environment-variables.json",
    "pdf": "/docs/download/reference/environment-variables.pdf"
  },
  "content": {
    "format": "text/markdown",
    "markdown": "---\ntitle: Environment variables\ndescription: Look up product-neutral AIP environment variables and their owning process\nkind: reference\naudience: operator\nappliesTo: \"1.x\"\nwritingStandard: \"aip-docs/1.0\"\nlastReviewedRevision: \"d7cce13d1d555644d04a4d73c66c95b113737635\"\n---\n\n# Environment variables\n\nThis reference lists all 86 environment variables consumed by the\nproduct-neutral `getaip-server` gateway and separates them from connector control-plane,\nstandalone host, product connector, and `getaip` settings. Use it to identify\nwhich process owns a value, how it combines with command-line configuration,\nand whether it activates an optional subsystem.\n\nThe inventory reflects source revision\n`d7cce13d1d555644d04a4d73c66c95b113737635`. It does not include variables\nused only by the migration-only bundled binary or by non-public development\nmodules.\n\n## Choose the correct owner\n\n| Prefix | Owning process | Canonical configuration owner |\n|---|---|---|\n| `GETAIP_SERVER_` | Product-neutral `getaip-server` gateway | This page and [`getaip-server` configuration](configuration.md) |\n| `AIP_CONNECTOR_CONTROL_` | Standalone connector lifecycle control plane | Control-plane section on this page |\n| `AIP_CONNECTOR_HOST_` | Common bootstrap for every standalone connector host | [Connector host configuration](connector-host-configuration.md) |\n| `AIP_CAL_DIY_` | Standalone Cal.diy host | Cal.diy connector-local configuration |\n| `AIP_HERMES_` | Standalone Hermes Agent host | Hermes Agent connector-local configuration |\n| `AIP_CHATWOOT_` | Standalone Chatwoot host | Chatwoot connector-local configuration |\n| `AIP_DIFY_` | Standalone Dify host | Dify connector-local configuration |\n| `AIP_CREWAI_` | Standalone CrewAI host | CrewAI connector-local configuration |\n| `AIP_TWENTY_` | Standalone Twenty host | Twenty connector-local configuration |\n| `GETAIP_` | `getaip` client process | Tool section on this page and the [`getaip` reference](cli.md) |\n\nDo not copy provider credentials from a standalone host into a\n`GETAIP_SERVER_` variable. The `AIP_CAL_DIY_` prefix is owned by the standalone\nCal.diy host; it does not make Cal.diy part of the\nproduct-neutral gateway.\n\n## Resolution and parsing rules\n\nFor most scalar `getaip-server` settings, an explicit CLI value wins and the environment\nis the fallback. These variables are exceptions:\n\n- `GETAIP_SERVER_NATIVE_PRINCIPAL` overrides the CLI principal, including an explicit\n  `--native-principal` value;\n- `GETAIP_SERVER_MCP_PRINCIPAL` overrides the CLI principal, including an explicit\n  `--mcp-principal` value;\n- `GETAIP_SERVER_NATS_REQUEST_TIMEOUT_MS` overrides\n  `--nats-request-timeout-ms`.\n\nBoolean variables are true only for `1`, `true`, `TRUE`, `yes`, or `YES`.\nEvery other value, including an empty string, is false. Boolean environment and\nCLI switches are otherwise combined as logical OR.\n\nUnsigned integer variables use strict decimal parsing. A malformed or negative\nvalue fails startup even when the subsystem would later remain disabled.\nValues that must be positive receive an additional validation check.\n\nTwo list formats exist:\n\n| Format | Separators | Variables using it |\n|---|---|---|\n| Route list | Semicolon or newline | Trusted signer and delegation specifications |\n| General list | Comma, semicolon, or newline | Hosts, scopes, issuers, origins, topology weights, and other repeatable values |\n\nEnvironment list entries extend the corresponding CLI list. They do not\nreplace it. Duplicate entries can fail a later uniqueness check.\n\nAn empty environment value is not a portable substitute for unsetting a\nvariable. Some paths filter empty values, while other paths parse or validate\nthem and fail. Remove an unused variable from the process environment.\n\n## `getaip-server` process and storage\n\n| Variable | CLI relation | Default or purpose |\n|---|---|---|\n| `GETAIP_SERVER_PUBLIC_BASE_URL` | Fallback for `--public-base-url` | External HTTPS origin advertised for A2A and discovery. |\n| `GETAIP_SERVER_STORAGE_DIR` | Fallback for `--storage-dir` | Durable local and auxiliary file state. |\n| `GETAIP_SERVER_POSTGRES_URL` | Fallback for `--postgres-url` | Inline clustered runtime PostgreSQL URL. Prefer the file variable. |\n| `GETAIP_SERVER_POSTGRES_URL_FILE` | Fallback for `--postgres-url-file` | Mode-0600 file containing the runtime PostgreSQL URL. |\n\nThe PostgreSQL inline and file variables are mutually exclusive after CLI and\nenvironment resolution. PostgreSQL owns core runtime state when either form\nresolves; otherwise the storage directory owns local runtime state. With\nneither, core runtime state is in memory.\n\nThe listener address, service ID, trust domain, manifest-print mode, and MCP\nstdio mode have no `GETAIP_SERVER_` environment equivalent in this revision. Configure\nthem with CLI options.\n\n## `getaip-server` native identity and authorization\n\n| Variable | Type or format | Default or purpose |\n|---|---|---|\n| `GETAIP_SERVER_TRUSTED_SIGNERS` | Route list of `DID=PRINCIPAL_ID` | Extends inline trusted signer bindings. |\n| `GETAIP_SERVER_TRUSTED_SIGNER_FILE` | Path | Additional bounded JSON signer directory. |\n| `GETAIP_SERVER_NATIVE_BEARER_TOKEN` | Secret text | Inline native HTTP bearer token. Prefer the file variable. |\n| `GETAIP_SERVER_NATIVE_BEARER_TOKEN_FILE` | Secret-file path | Mode-0600 native bearer-token file. |\n| `GETAIP_SERVER_NATIVE_PRINCIPAL` | Principal ID | Overrides the CLI native principal; CLI default is `service:getaip:server:http-edge`. |\n| `GETAIP_SERVER_NATIVE_TENANT_ID` | Tenant ID | Verified tenant bound to native bearer authentication. |\n| `GETAIP_SERVER_NATIVE_PRINCIPAL_SCOPES` | General list | Extends scopes granted to the native principal. |\n| `GETAIP_SERVER_TRUSTED_IDENTITY_FILE` | Path | Revisioned trusted identity, tenant, credential, and context directory. |\n| `GETAIP_SERVER_APPROVAL_AUTHORITY_FILE` | Path | Revisioned approval-authority membership directory. |\n| `GETAIP_SERVER_REQUIRE_SIGNED_ENVELOPES` | Boolean | Explicitly enables signed native envelopes. |\n| `GETAIP_SERVER_ALLOW_UNSIGNED_ENVELOPES` | Boolean | Disables the default signature requirement unless another require switch restores it. |\n| `GETAIP_SERVER_INSECURE_DEVELOPMENT` | Boolean | Enables unauthenticated native development only on loopback. |\n\n`GETAIP_SERVER_NATIVE_BEARER_TOKEN` and `GETAIP_SERVER_NATIVE_BEARER_TOKEN_FILE` cannot both\nresolve. Signatures are required by default. To accept unsigned envelopes,\n`GETAIP_SERVER_ALLOW_UNSIGNED_ENVELOPES` must be true while the CLI and environment\nrequire switches are false. Outside loopback-only insecure development, native\nbearer authentication is still required for unsigned traffic.\n\nSigner bindings from the route list and file are merged. Every signer must use\na valid Ed25519 `did:key`, and a DID cannot occur twice across the combined\nsources.\n\n## `getaip-server` callbacks and runtime budgets\n\n| Variable | Type or format | Default or purpose |\n|---|---|---|\n| `GETAIP_SERVER_CALLBACK_ALLOWED_HOSTS` | General list | Exact outbound callback hosts. |\n| `GETAIP_SERVER_CALLBACK_SIGNING_SEED_HEX` | Secret hex | Inline 32-byte response and callback signing seed. Prefer the file variable. |\n| `GETAIP_SERVER_CALLBACK_SIGNING_SEED_FILE` | Secret-file path | Mode-0600 response and callback signing-seed file. |\n| `GETAIP_SERVER_A2A_PUSH_ENCRYPTION_KEY_HEX` | Secret hex | Inline 32-byte key for stored A2A push credentials. |\n| `GETAIP_SERVER_CALLBACK_ALLOW_HTTP` | Boolean | Permits plaintext callback and shared-policy destinations. |\n| `GETAIP_SERVER_CALLBACK_ALLOW_PRIVATE_NETWORKS` | Boolean | Permits private or loopback shared-policy destinations. |\n| `GETAIP_SERVER_CALLBACK_TIMEOUT_MS` | Unsigned integer | Callback request timeout; default `5000`. Environment-only. |\n| `GETAIP_SERVER_CALLBACK_MAX_RESPONSE_BYTES` | Unsigned integer | Callback response bound; default `4194304`. Environment-only. |\n| `GETAIP_SERVER_CALLBACK_MAX_IN_FLIGHT` | Positive integer | Concurrent callback deliveries; default `64`. |\n| `GETAIP_SERVER_CALLBACK_RECOVERY_BATCH` | Positive integer | Callback records leased per recovery cycle; default `64`. |\n| `GETAIP_SERVER_RECONCILIATION_MAX_IN_FLIGHT` | Positive integer | Concurrent transaction reconciliations; default `32`. |\n\nThe inline and file signing-seed variables are mutually exclusive. An allowed\ncallback host, A2A push key, or delegation route requires a response and\ncallback signing seed. The HTTP and private-network variables expand the\ndestination boundary shared by callbacks and HTTP delegation.\n\n## `getaip-server` connector registry and fleet transport\n\n| Variable | Type or format | Default or purpose |\n|---|---|---|\n| `GETAIP_SERVER_CONNECTOR_REGISTRY_URL` | Secret text | Inline registry data-plane PostgreSQL URL. Prefer the file variable. |\n| `GETAIP_SERVER_CONNECTOR_REGISTRY_URL_FILE` | Secret-file path | Mode-0600 registry data-plane URL file. |\n| `GETAIP_SERVER_CONNECTOR_REGISTRY_DATA_MAX_CONNECTIONS` | Positive integer | Registry data connections; default `32`. |\n| `GETAIP_SERVER_CONNECTOR_REGISTRY_ACQUIRE_TIMEOUT_MS` | Positive integer | Connection wait; default `5000`, maximum `60000`. |\n| `GETAIP_SERVER_CONNECTOR_FLEET_SIGNING_SEED_FILE` | Secret-file path | Required 32-byte Ed25519 seed file for fleet mode. |\n| `GETAIP_SERVER_CONNECTOR_FLEET_CALLBACK_URL` | URL | Central stream callback ending in `/aip/v1/connector-callbacks`. |\n| `GETAIP_SERVER_CONNECTOR_FLEET_ALLOWED_HOSTS` | General list | Exact connector-host destination hosts. |\n| `GETAIP_SERVER_CONNECTOR_FLEET_TRUST_REGISTRY_ENDPOINTS` | Boolean | Uses admitted registry endpoints as the per-route host allowlist. |\n| `GETAIP_SERVER_CONNECTOR_FLEET_ALLOW_HTTP` | Boolean | Permits plaintext host and fleet callback URLs. |\n| `GETAIP_SERVER_CONNECTOR_FLEET_ALLOW_PRIVATE_NETWORKS` | Boolean | Permits private or loopback connector-host addresses. |\n| `GETAIP_SERVER_CONNECTOR_FLEET_TIMEOUT_MS` | Positive integer | Connector-host request timeout; default `5000`. |\n| `GETAIP_SERVER_CONNECTOR_FLEET_MAX_RESPONSE_BYTES` | Positive integer | Host response bound; default `4194304`. |\n| `GETAIP_SERVER_CONNECTOR_FLEET_RETRY_BUDGET` | Unsigned integer | Retries after the first attempt; default `2`. |\n| `GETAIP_SERVER_CONNECTOR_FLEET_MAX_CACHED_CLIENTS` | Positive integer | Cached host HTTP pools; default `256`. |\n| `GETAIP_SERVER_CONNECTOR_FLEET_TLS_CA_FILE` | Path | Additional PEM root for private-PKI host TLS. |\n\nThe registry inline and file variables are mutually exclusive. A resolved\nregistry URL activates fleet composition and then requires the signing-seed\nfile plus either explicit allowed hosts or registry endpoint trust.\n\n## `getaip-server` fleet topology and admission\n\n| Variable | Type or format | Default or purpose |\n|---|---|---|\n| `GETAIP_SERVER_CONNECTOR_FLEET_REGION` | Text | Preferred region for new assignments; unset by default. |\n| `GETAIP_SERVER_CONNECTOR_FLEET_ZONE` | Text | Preferred zone for new assignments; unset by default. |\n| `GETAIP_SERVER_CONNECTOR_FLEET_CAPACITY_CLASS` | Text | Required capacity class for new assignments; unset by default. |\n| `GETAIP_SERVER_CONNECTOR_FLEET_DISABLE_CROSS_REGION_FAILOVER` | Boolean | Forbids new-assignment fallback to another region. |\n| `GETAIP_SERVER_CONNECTOR_FLEET_MAX_IN_FLIGHT` | Positive integer | Global active remote actions; default `1024`. |\n| `GETAIP_SERVER_CONNECTOR_FLEET_MAX_IN_FLIGHT_PER_TENANT` | Positive integer | Active remote actions per tenant; default `128`. |\n| `GETAIP_SERVER_CONNECTOR_FLEET_MAX_QUEUED` | Positive integer | Global waiting actions; default `4096`. |\n| `GETAIP_SERVER_CONNECTOR_FLEET_MAX_QUEUED_PER_TENANT` | Positive integer | Waiting actions per tenant; default `512`. |\n| `GETAIP_SERVER_CONNECTOR_FLEET_MAX_QUEUE_BYTES` | Positive integer | Canonical bytes retained by queued actions; default `67108864`. |\n| `GETAIP_SERVER_CONNECTOR_FLEET_MAX_REQUEST_BYTES` | Positive integer | Canonical size of one remote action; default `4194304`. |\n| `GETAIP_SERVER_CONNECTOR_FLEET_MAX_QUEUE_AGE_MS` | Positive integer | Maximum local queue time; default `30000`. |\n| `GETAIP_SERVER_CONNECTOR_FLEET_TENANT_WEIGHTS` | General list of `TENANT_ID=WEIGHT` | Positive scheduling weights; none by default. |\n\nPer-tenant limits cannot exceed their global counterparts. Weight tenant IDs\ncontain 1–256 bytes, each weight is positive, and duplicate tenant IDs fail\nstartup. Topology preferences affect new assignments, not already pinned work.\n\n## `getaip-server` fleet activation nuance\n\n`GETAIP_SERVER_CONNECTOR_REGISTRY_URL` or\n`GETAIP_SERVER_CONNECTOR_REGISTRY_URL_FILE` is the only environment activation boundary\nfor fleet mode. Do not infer activation from another fleet variable.\n\nWithout a registry URL, these environment groups explicitly make the\nconfiguration partial and fail startup:\n\n- signing-seed file and fleet callback URL;\n- allowed hosts or any fleet network-policy Boolean;\n- tenant weights;\n- cross-region failover disablement;\n- any connector-event or stream-ingress limit.\n\nValid environment-only pool, transport numeric, topology text, admission\nnumeric, and TLS CA settings do not activate fleet mode and are not all treated\nas partial configuration in the reviewed implementation. They can be parsed or\ntheir file can be read, then discarded when the registry URL is absent. An\ninvalid numeric value or unreadable CA file can still fail startup.\n\nSet the registry URL explicitly and verify the `/ready` fleet section rather\nthan using a tuning value as an activation probe.\n\n## `getaip-server` connector-event and stream ingress\n\n| Variable | Type | Default or purpose |\n|---|---|---|\n| `GETAIP_SERVER_CONNECTOR_EVENT_MAX_ENVELOPE_BYTES` | Positive integer | Signed envelope bound; default `4194304`. |\n| `GETAIP_SERVER_CONNECTOR_EVENT_MAX_EVENTS_PER_ENVELOPE` | Integer `1`–`1000` | Events per envelope; default `100`. |\n| `GETAIP_SERVER_CONNECTOR_EVENT_MAX_EVENT_BYTES` | Positive integer | One enriched event; default `262144`, no more than envelope bound. |\n| `GETAIP_SERVER_CONNECTOR_STREAM_MAX_CHUNK_BYTES` | Positive integer | One stream chunk; default `262144`, no more than envelope bound. |\n| `GETAIP_SERVER_CONNECTOR_EVENT_MAX_IN_FLIGHT` | Positive integer | Concurrent storage operations; default `128`. |\n| `GETAIP_SERVER_CONNECTOR_EVENT_MAX_AGE_SECONDS` | Positive integer | Maximum event age; default `86400`. |\n| `GETAIP_SERVER_CONNECTOR_EVENT_MAX_FUTURE_SKEW_SECONDS` | Positive integer | Future clock skew; default `300`. |\n| `GETAIP_SERVER_CONNECTOR_STREAM_CALLBACK_MAX_AGE_SECONDS` | Positive integer | Signed stream callback age; default `300`. |\n\nAny one of these variables without a registry URL is rejected as partial fleet\nconfiguration. The limits do not replace route, tenant, signature, timestamp,\nsequence, lease, or replay validation.\n\n## `getaip-server` NATS and delegation\n\n| Variable | Type or format | Default or purpose |\n|---|---|---|\n| `GETAIP_SERVER_NATS_URL` | URL | Enables native NATS request/reply. |\n| `GETAIP_SERVER_NATS_USERNAME` | Text | NATS username; requires the password file. |\n| `GETAIP_SERVER_NATS_PASSWORD_FILE` | Secret-file path | Mode-0600 NATS password; requires the username. |\n| `GETAIP_SERVER_NATS_TRUST_DOMAIN` | Text | Subject trust domain; defaults to the daemon trust domain. |\n| `GETAIP_SERVER_NATS_SERVICE` | Text | Subject service; default `getaip-server`. |\n| `GETAIP_SERVER_NATS_VERSION` | Text | Subject version; default `v1`. |\n| `GETAIP_SERVER_NATS_QUEUE_GROUP` | Text | Optional queue group. |\n| `GETAIP_SERVER_NATS_REQUEST_TIMEOUT_MS` | Unsigned integer | Request timeout; overrides CLI, whose default is `30000`. |\n| `GETAIP_SERVER_DELEGATION_HTTP_ROUTES` | Route list | `DELEGATE_ID=URL,PEER_ID,PEER_DID[,TRUST_DOMAIN]`. |\n| `GETAIP_SERVER_DELEGATION_NATS_ROUTES` | Route list | `CAPABILITY_ID=SERVER_URL,SUBJECT,PEER_ID,PEER_DID[,TIMEOUT_MS[,TRUST_DOMAIN]]`. |\n\nAuthentication values without `GETAIP_SERVER_NATS_URL` fail startup. Username and\npassword file must resolve together. Delegation lists extend CLI routes and\nrequire the response and callback signing seed.\n\n## `getaip-server` MCP\n\n| Variable | Type or format | Default or purpose |\n|---|---|---|\n| `GETAIP_SERVER_MCP_BEARER_TOKEN` | Secret text | Static MCP HTTP bearer token. |\n| `GETAIP_SERVER_MCP_RESOURCE` | Resource identifier | Protected-resource identifier. |\n| `GETAIP_SERVER_MCP_AUTHORIZATION_SERVERS` | General list | Advertised authorization-server issuers. |\n| `GETAIP_SERVER_MCP_SCOPES` | General list | Advertised supported scopes. |\n| `GETAIP_SERVER_MCP_REQUIRED_SCOPES` | General list | Scopes required to establish an MCP HTTP session. |\n| `GETAIP_SERVER_MCP_RESOURCE_DOCUMENTATION` | URL | Human-readable protected-resource documentation. |\n| `GETAIP_SERVER_MCP_ALLOWED_ORIGINS` | General list | Browser origins allowed to call MCP HTTP. |\n| `GETAIP_SERVER_MCP_INTROSPECTION_URL` | HTTPS URL | RFC 7662 endpoint. |\n| `GETAIP_SERVER_MCP_INTROSPECTION_ISSUER` | Issuer | Trusted issuer represented by introspection. |\n| `GETAIP_SERVER_MCP_INTROSPECTION_CLIENT_ID` | Text | OAuth introspection client ID. |\n| `GETAIP_SERVER_MCP_INTROSPECTION_CLIENT_SECRET_FILE` | Secret-file path | Mode-0600 introspection client secret. |\n| `GETAIP_SERVER_MCP_INTROSPECTION_ALLOW_LOOPBACK_HTTP` | Boolean | Permits a loopback plaintext introspection fixture. |\n| `GETAIP_SERVER_MCP_PRINCIPAL` | Principal ID | Overrides the CLI MCP principal; CLI default is `service:getaip:server:mcp-edge`. |\n| `GETAIP_SERVER_MCP_PRINCIPAL_SCOPES` | General list | Extends scopes granted to the MCP principal. |\n\nIntrospection URL, issuer, client ID, and secret file are an all-or-none group.\nIntrospection also requires a protected resource, rejects a simultaneous static\ntoken, and requires its issuer in the advertised authorization-server list.\n\nWhen resource is absent, a static token, authorization server, supported scope,\nor documentation URL causes the implementation to derive\n`http://<bind>/mcp`. Set `GETAIP_SERVER_MCP_RESOURCE` explicitly for a public origin.\n\n## Connector control-plane variables\n\nThe standalone `aip-connector-control-plane` consumes two environment\nvariables:\n\n| Variable | CLI relation | Purpose |\n|---|---|---|\n| `AIP_CONNECTOR_CONTROL_DATABASE_URL_FILE` | Fallback for `--database-url-file` | Required owner-only file containing the restricted lifecycle PostgreSQL URL. |\n| `AIP_CONNECTOR_CONTROL_SIGNING_SEED_FILE` | Fallback for `--signing-seed-file` | Required owner-only file containing the response-signing Ed25519 seed. |\n\nAn explicit CLI path wins. Empty environment paths are treated as absent. Both\nfiles must be regular non-symlink files with no group or other permission bits.\nOther control-plane settings, including bind address, proxy-network exception,\nprincipal ID, lease TTL, pool size, and acquire timeout, are CLI-only in this\nrevision.\n\n## Standalone connector-host variables\n\nEvery one of the six public standalone hosts consumes the 45 common\n`AIP_CONNECTOR_HOST_` variables documented in the Connector host configuration\npage linked from the ownership table. That page is the canonical inventory for\ncommon endpoint, admitted identity, tenant, trust, storage, topology,\ncredential, lifecycle, callback, event, and limit settings.\n\nEach host then adds its product-owned prefix shown in the ownership table. The\nconnector-local configuration page owns those provider endpoints, account or\nworkspace identifiers, operation descriptors, policy files, and credential\nfile references. This global page does not duplicate them because their\nrequired combinations and defaults differ by connector.\n\n## `getaip` variables\n\n| Variable | Default or purpose |\n|---|---|\n| `GETAIP_NATIVE_BEARER_TOKEN` | Fallback inline native HTTP bearer token. Prefer the file variable. |\n| `GETAIP_NATIVE_BEARER_TOKEN_FILE` | Owner-only native bearer-token file. |\n| `GETAIP_NATIVE_SIGNING_SEED_FILE` | Owner-only Ed25519 seed file for signed native HTTP requests. |\n| `GETAIP_NATIVE_PRINCIPAL_ID` | Signed native principal; environment overrides CLI, whose default is `agent:getaip:cli`. |\n| `GETAIP_NATIVE_TRUST_DOMAIN` | Trust domain carried by signed native HTTP requests. |\n| `GETAIP_NATIVE_TLS_CA_FILE` | Additional PEM root for native private-PKI TLS. |\n| `GETAIP_NATIVE_PEER_DID` | Pinned Ed25519 DID expected on native responses. |\n| `GETAIP_NATIVE_PEER_DID_FILE` | File containing the pinned response DID; mutually exclusive with inline DID. |\n| `GETAIP_NATIVE_MAX_RESPONSE_BYTES` | Native HTTP response bound; environment overrides CLI, whose default is `4194304`. |\n| `GETAIP_NATS_USERNAME` | Native NATS username; requires the password file. |\n| `GETAIP_NATS_PASSWORD_FILE` | Owner-only native NATS password file; requires the username. |\n| `GETAIP_NATS_SIGNING_SEED_FILE` | Owner-only Ed25519 seed file for signed native NATS requests. |\n| `GETAIP_MCP_BEARER_TOKEN` | Fallback bearer token for MCP HTTP subcommands. |\n\nExcept for the documented principal and response-size overrides, explicit\n`getaip` options take precedence. Do not export long-lived inline tokens into a\nshared shell profile. Prefer owner-only files and give the CLI process access\nonly for the duration of the operation.\n\nThe native bearer token and bearer-token file are mutually exclusive. The\ninline native peer DID and peer-DID file are also mutually exclusive. NATS\nusername and password file must resolve together; the NATS signing seed remains\na separate AIP message-signing identity.\n",
    "text": "Environment variables\n\nThis reference lists all 86 environment variables consumed by the\nproduct-neutral getaip-server gateway and separates them from connector control-plane,\nstandalone host, product connector, and getaip settings. Use it to identify\nwhich process owns a value, how it combines with command-line configuration,\nand whether it activates an optional subsystem.\n\nThe inventory reflects source revision\nd7cce13d1d555644d04a4d73c66c95b113737635. It does not include variables\nused only by the migration-only bundled binary or by non-public development\nmodules.\n\nChoose the correct owner\n\n| Prefix | Owning process | Canonical configuration owner |\n\n| GETAIPSERVER | Product-neutral getaip-server gateway | This page and getaip-server configuration (configuration.md) |\n| AIPCONNECTORCONTROL | Standalone connector lifecycle control plane | Control-plane section on this page |\n| AIPCONNECTORHOST | Common bootstrap for every standalone connector host | Connector host configuration (connector-host-configuration.md) |\n| AIPCALDIY | Standalone Cal.diy host | Cal.diy connector-local configuration |\n| AIPHERMES | Standalone Hermes Agent host | Hermes Agent connector-local configuration |\n| AIPCHATWOOT | Standalone Chatwoot host | Chatwoot connector-local configuration |\n| AIPDIFY | Standalone Dify host | Dify connector-local configuration |\n| AIPCREWAI | Standalone CrewAI host | CrewAI connector-local configuration |\n| AIPTWENTY | Standalone Twenty host | Twenty connector-local configuration |\n| GETAIP | getaip client process | Tool section on this page and the getaip reference (cli.md) |\n\nDo not copy provider credentials from a standalone host into a\nGETAIPSERVER variable. The AIPCALDIY prefix is owned by the standalone\nCal.diy host; it does not make Cal.diy part of the\nproduct-neutral gateway.\n\nResolution and parsing rules\n\nFor most scalar getaip-server settings, an explicit CLI value wins and the environment\nis the fallback. These variables are exceptions:\n• GETAIPSERVERNATIVEPRINCIPAL overrides the CLI principal, including an explicit\n  --native-principal value;\n• GETAIPSERVERMCPPRINCIPAL overrides the CLI principal, including an explicit\n  --mcp-principal value;\n• GETAIPSERVERNATSREQUESTTIMEOUTMS overrides\n  --nats-request-timeout-ms.\n\nBoolean variables are true only for 1, true, TRUE, yes, or YES.\nEvery other value, including an empty string, is false. Boolean environment and\nCLI switches are otherwise combined as logical OR.\n\nUnsigned integer variables use strict decimal parsing. A malformed or negative\nvalue fails startup even when the subsystem would later remain disabled.\nValues that must be positive receive an additional validation check.\n\nTwo list formats exist:\n\n| Format | Separators | Variables using it |\n\n| Route list | Semicolon or newline | Trusted signer and delegation specifications |\n| General list | Comma, semicolon, or newline | Hosts, scopes, issuers, origins, topology weights, and other repeatable values |\n\nEnvironment list entries extend the corresponding CLI list. They do not\nreplace it. Duplicate entries can fail a later uniqueness check.\n\nAn empty environment value is not a portable substitute for unsetting a\nvariable. Some paths filter empty values, while other paths parse or validate\nthem and fail. Remove an unused variable from the process environment.\n\ngetaip-server process and storage\n\n| Variable | CLI relation | Default or purpose |\n\n| GETAIPSERVERPUBLICBASEURL | Fallback for --public-base-url | External HTTPS origin advertised for A2A and discovery. |\n| GETAIPSERVERSTORAGEDIR | Fallback for --storage-dir | Durable local and auxiliary file state. |\n| GETAIPSERVERPOSTGRESURL | Fallback for --postgres-url | Inline clustered runtime PostgreSQL URL. Prefer the file variable. |\n| GETAIPSERVERPOSTGRESURLFILE | Fallback for --postgres-url-file | Mode-0600 file containing the runtime PostgreSQL URL. |\n\nThe PostgreSQL inline and file variables are mutually exclusive after CLI and\nenvironment resolution. PostgreSQL owns core runtime state when either form\nresolves; otherwise the storage directory owns local runtime state. With\nneither, core runtime state is in memory.\n\nThe listener address, service ID, trust domain, manifest-print mode, and MCP\nstdio mode have no GETAIPSERVER environment equivalent in this revision. Configure\nthem with CLI options.\n\ngetaip-server native identity and authorization\n\n| Variable | Type or format | Default or purpose |\n\n| GETAIPSERVERTRUSTEDSIGNERS | Route list of DID=PRINCIPALID | Extends inline trusted signer bindings. |\n| GETAIPSERVERTRUSTEDSIGNERFILE | Path | Additional bounded JSON signer directory. |\n| GETAIPSERVERNATIVEBEARERTOKEN | Secret text | Inline native HTTP bearer token. Prefer the file variable. |\n| GETAIPSERVERNATIVEBEARERTOKENFILE | Secret-file path | Mode-0600 native bearer-token file. |\n| GETAIPSERVERNATIVEPRINCIPAL | Principal ID | Overrides the CLI native principal; CLI default is service:getaip:server:http-edge. |\n| GETAIPSERVERNATIVETENANTID | Tenant ID | Verified tenant bound to native bearer authentication. |\n| GETAIPSERVERNATIVEPRINCIPALSCOPES | General list | Extends scopes granted to the native principal. |\n| GETAIPSERVERTRUSTEDIDENTITYFILE | Path | Revisioned trusted identity, tenant, credential, and context directory. |\n| GETAIPSERVERAPPROVALAUTHORITYFILE | Path | Revisioned approval-authority membership directory. |\n| GETAIPSERVERREQUIRESIGNEDENVELOPES | Boolean | Explicitly enables signed native envelopes. |\n| GETAIPSERVERALLOWUNSIGNEDENVELOPES | Boolean | Disables the default signature requirement unless another require switch restores it. |\n| GETAIPSERVERINSECUREDEVELOPMENT | Boolean | Enables unauthenticated native development only on loopback. |\n\nGETAIPSERVERNATIVEBEARERTOKEN and GETAIPSERVERNATIVEBEARERTOKENFILE cannot both\nresolve. Signatures are required by default. To accept unsigned envelopes,\nGETAIPSERVERALLOWUNSIGNEDENVELOPES must be true while the CLI and environment\nrequire switches are false. Outside loopback-only insecure development, native\nbearer authentication is still required for unsigned traffic.\n\nSigner bindings from the route list and file are merged. Every signer must use\na valid Ed25519 did:key, and a DID cannot occur twice across the combined\nsources.\n\ngetaip-server callbacks and runtime budgets\n\n| Variable | Type or format | Default or purpose |\n\n| GETAIPSERVERCALLBACKALLOWEDHOSTS | General list | Exact outbound callback hosts. |\n| GETAIPSERVERCALLBACKSIGNINGSEEDHEX | Secret hex | Inline 32-byte response and callback signing seed. Prefer the file variable. |\n| GETAIPSERVERCALLBACKSIGNINGSEEDFILE | Secret-file path | Mode-0600 response and callback signing-seed file. |\n| GETAIPSERVERA2APUSHENCRYPTIONKEYHEX | Secret hex | Inline 32-byte key for stored A2A push credentials. |\n| GETAIPSERVERCALLBACKALLOWHTTP | Boolean | Permits plaintext callback and shared-policy destinations. |\n| GETAIPSERVERCALLBACKALLOWPRIVATENETWORKS | Boolean | Permits private or loopback shared-policy destinations. |\n| GETAIPSERVERCALLBACKTIMEOUTMS | Unsigned integer | Callback request timeout; default 5000. Environment-only. |\n| GETAIPSERVERCALLBACKMAXRESPONSEBYTES | Unsigned integer | Callback response bound; default 4194304. Environment-only. |\n| GETAIPSERVERCALLBACKMAXINFLIGHT | Positive integer | Concurrent callback deliveries; default 64. |\n| GETAIPSERVERCALLBACKRECOVERYBATCH | Positive integer | Callback records leased per recovery cycle; default 64. |\n| GETAIPSERVERRECONCILIATIONMAXINFLIGHT | Positive integer | Concurrent transaction reconciliations; default 32. |\n\nThe inline and file signing-seed variables are mutually exclusive. An allowed\ncallback host, A2A push key, or delegation route requires a response and\ncallback signing seed. The HTTP and private-network variables expand the\ndestination boundary shared by callbacks and HTTP delegation.\n\ngetaip-server connector registry and fleet transport\n\n| Variable | Type or format | Default or purpose |\n\n| GETAIPSERVERCONNECTORREGISTRYURL | Secret text | Inline registry data-plane PostgreSQL URL. Prefer the file variable. |\n| GETAIPSERVERCONNECTORREGISTRYURLFILE | Secret-file path | Mode-0600 registry data-plane URL file. |\n| GETAIPSERVERCONNECTORREGISTRYDATAMAXCONNECTIONS | Positive integer | Registry data connections; default 32. |\n| GETAIPSERVERCONNECTORREGISTRYACQUIRETIMEOUTMS | Positive integer | Connection wait; default 5000, maximum 60000. |\n| GETAIPSERVERCONNECTORFLEETSIGNINGSEEDFILE | Secret-file path | Required 32-byte Ed25519 seed file for fleet mode. |\n| GETAIPSERVERCONNECTORFLEETCALLBACKURL | URL | Central stream callback ending in /aip/v1/connector-callbacks. |\n| GETAIPSERVERCONNECTORFLEETALLOWEDHOSTS | General list | Exact connector-host destination hosts. |\n| GETAIPSERVERCONNECTORFLEETTRUSTREGISTRYENDPOINTS | Boolean | Uses admitted registry endpoints as the per-route host allowlist. |\n| GETAIPSERVERCONNECTORFLEETALLOWHTTP | Boolean | Permits plaintext host and fleet callback URLs. |\n| GETAIPSERVERCONNECTORFLEETALLOWPRIVATENETWORKS | Boolean | Permits private or loopback connector-host addresses. |\n| GETAIPSERVERCONNECTORFLEETTIMEOUTMS | Positive integer | Connector-host request timeout; default 5000. |\n| GETAIPSERVERCONNECTORFLEETMAXRESPONSEBYTES | Positive integer | Host response bound; default 4194304. |\n| GETAIPSERVERCONNECTORFLEETRETRYBUDGET | Unsigned integer | Retries after the first attempt; default 2. |\n| GETAIPSERVERCONNECTORFLEETMAXCACHEDCLIENTS | Positive integer | Cached host HTTP pools; default 256. |\n| GETAIPSERVERCONNECTORFLEETTLSCAFILE | Path | Additional PEM root for private-PKI host TLS. |\n\nThe registry inline and file variables are mutually exclusive. A resolved\nregistry URL activates fleet composition and then requires the signing-seed\nfile plus either explicit allowed hosts or registry endpoint trust.\n\ngetaip-server fleet topology and admission\n\n| Variable | Type or format | Default or purpose |\n\n| GETAIPSERVERCONNECTORFLEETREGION | Text | Preferred region for new assignments; unset by default. |\n| GETAIPSERVERCONNECTORFLEETZONE | Text | Preferred zone for new assignments; unset by default. |\n| GETAIPSERVERCONNECTORFLEETCAPACITYCLASS | Text | Required capacity class for new assignments; unset by default. |\n| GETAIPSERVERCONNECTORFLEETDISABLECROSSREGIONFAILOVER | Boolean | Forbids new-assignment fallback to another region. |\n| GETAIPSERVERCONNECTORFLEETMAXINFLIGHT | Positive integer | Global active remote actions; default 1024. |\n| GETAIPSERVERCONNECTORFLEETMAXINFLIGHTPERTENANT | Positive integer | Active remote actions per tenant; default 128. |\n| GETAIPSERVERCONNECTORFLEETMAXQUEUED | Positive integer | Global waiting actions; default 4096. |\n| GETAIPSERVERCONNECTORFLEETMAXQUEUEDPERTENANT | Positive integer | Waiting actions per tenant; default 512. |\n| GETAIPSERVERCONNECTORFLEETMAXQUEUEBYTES | Positive integer | Canonical bytes retained by queued actions; default 67108864. |\n| GETAIPSERVERCONNECTORFLEETMAXREQUESTBYTES | Positive integer | Canonical size of one remote action; default 4194304. |\n| GETAIPSERVERCONNECTORFLEETMAXQUEUEAGEMS | Positive integer | Maximum local queue time; default 30000. |\n| GETAIPSERVERCONNECTORFLEETTENANTWEIGHTS | General list of TENANTID=WEIGHT | Positive scheduling weights; none by default. |\n\nPer-tenant limits cannot exceed their global counterparts. Weight tenant IDs\ncontain 1–256 bytes, each weight is positive, and duplicate tenant IDs fail\nstartup. Topology preferences affect new assignments, not already pinned work.\n\ngetaip-server fleet activation nuance\n\nGETAIPSERVERCONNECTORREGISTRYURL or\nGETAIPSERVERCONNECTORREGISTRYURLFILE is the only environment activation boundary\nfor fleet mode. Do not infer activation from another fleet variable.\n\nWithout a registry URL, these environment groups explicitly make the\nconfiguration partial and fail startup:\n• signing-seed file and fleet callback URL;\n• allowed hosts or any fleet network-policy Boolean;\n• tenant weights;\n• cross-region failover disablement;\n• any connector-event or stream-ingress limit.\n\nValid environment-only pool, transport numeric, topology text, admission\nnumeric, and TLS CA settings do not activate fleet mode and are not all treated\nas partial configuration in the reviewed implementation. They can be parsed or\ntheir file can be read, then discarded when the registry URL is absent. An\ninvalid numeric value or unreadable CA file can still fail startup.\n\nSet the registry URL explicitly and verify the /ready fleet section rather\nthan using a tuning value as an activation probe.\n\ngetaip-server connector-event and stream ingress\n\n| Variable | Type | Default or purpose |\n\n| GETAIPSERVERCONNECTOREVENTMAXENVELOPEBYTES | Positive integer | Signed envelope bound; default 4194304. |\n| GETAIPSERVERCONNECTOREVENTMAXEVENTSPERENVELOPE | Integer 1–1000 | Events per envelope; default 100. |\n| GETAIPSERVERCONNECTOREVENTMAXEVENTBYTES | Positive integer | One enriched event; default 262144, no more than envelope bound. |\n| GETAIPSERVERCONNECTORSTREAMMAXCHUNKBYTES | Positive integer | One stream chunk; default 262144, no more than envelope bound. |\n| GETAIPSERVERCONNECTOREVENTMAXINFLIGHT | Positive integer | Concurrent storage operations; default 128. |\n| GETAIPSERVERCONNECTOREVENTMAXAGESECONDS | Positive integer | Maximum event age; default 86400. |\n| GETAIPSERVERCONNECTOREVENTMAXFUTURESKEWSECONDS | Positive integer | Future clock skew; default 300. |\n| GETAIPSERVERCONNECTORSTREAMCALLBACKMAXAGESECONDS | Positive integer | Signed stream callback age; default 300. |\n\nAny one of these variables without a registry URL is rejected as partial fleet\nconfiguration. The limits do not replace route, tenant, signature, timestamp,\nsequence, lease, or replay validation.\n\ngetaip-server NATS and delegation\n\n| Variable | Type or format | Default or purpose |\n\n| GETAIPSERVERNATSURL | URL | Enables native NATS request/reply. |\n| GETAIPSERVERNATSUSERNAME | Text | NATS username; requires the password file. |\n| GETAIPSERVERNATSPASSWORDFILE | Secret-file path | Mode-0600 NATS password; requires the username. |\n| GETAIPSERVERNATSTRUSTDOMAIN | Text | Subject trust domain; defaults to the daemon trust domain. |\n| GETAIPSERVERNATSSERVICE | Text | Subject service; default getaip-server. |\n| GETAIPSERVERNATSVERSION | Text | Subject version; default v1. |\n| GETAIPSERVERNATSQUEUEGROUP | Text | Optional queue group. |\n| GETAIPSERVERNATSREQUESTTIMEOUTMS | Unsigned integer | Request timeout; overrides CLI, whose default is 30000. |\n| GETAIPSERVERDELEGATIONHTTPROUTES | Route list | DELEGATEID=URL,PEERID,PEERDID[,TRUSTDOMAIN]. |\n| GETAIPSERVERDELEGATIONNATSROUTES | Route list | CAPABILITYID=SERVERURL,SUBJECT,PEERID,PEERDID[,TIMEOUTMS[,TRUSTDOMAIN]]. |\n\nAuthentication values without GETAIPSERVERNATSURL fail startup. Username and\npassword file must resolve together. Delegation lists extend CLI routes and\nrequire the response and callback signing seed.\n\ngetaip-server MCP\n\n| Variable | Type or format | Default or purpose |\n\n| GETAIPSERVERMCPBEARERTOKEN | Secret text | Static MCP HTTP bearer token. |\n| GETAIPSERVERMCPRESOURCE | Resource identifier | Protected-resource identifier. |\n| GETAIPSERVERMCPAUTHORIZATIONSERVERS | General list | Advertised authorization-server issuers. |\n| GETAIPSERVERMCPSCOPES | General list | Advertised supported scopes. |\n| GETAIPSERVERMCPREQUIREDSCOPES | General list | Scopes required to establish an MCP HTTP session. |\n| GETAIPSERVERMCPRESOURCEDOCUMENTATION | URL | Human-readable protected-resource documentation. |\n| GETAIPSERVERMCPALLOWEDORIGINS | General list | Browser origins allowed to call MCP HTTP. |\n| GETAIPSERVERMCPINTROSPECTIONURL | HTTPS URL | RFC 7662 endpoint. |\n| GETAIPSERVERMCPINTROSPECTIONISSUER | Issuer | Trusted issuer represented by introspection. |\n| GETAIPSERVERMCPINTROSPECTIONCLIENTID | Text | OAuth introspection client ID. |\n| GETAIPSERVERMCPINTROSPECTIONCLIENTSECRETFILE | Secret-file path | Mode-0600 introspection client secret. |\n| GETAIPSERVERMCPINTROSPECTIONALLOWLOOPBACKHTTP | Boolean | Permits a loopback plaintext introspection fixture. |\n| GETAIPSERVERMCPPRINCIPAL | Principal ID | Overrides the CLI MCP principal; CLI default is service:getaip:server:mcp-edge. |\n| GETAIPSERVERMCPPRINCIPALSCOPES | General list | Extends scopes granted to the MCP principal. |\n\nIntrospection URL, issuer, client ID, and secret file are an all-or-none group.\nIntrospection also requires a protected resource, rejects a simultaneous static\ntoken, and requires its issuer in the advertised authorization-server list.\n\nWhen resource is absent, a static token, authorization server, supported scope,\nor documentation URL causes the implementation to derive\nhttp:///mcp. Set GETAIPSERVERMCPRESOURCE explicitly for a public origin.\n\nConnector control-plane variables\n\nThe standalone aip-connector-control-plane consumes two environment\nvariables:\n\n| Variable | CLI relation | Purpose |\n\n| AIPCONNECTORCONTROLDATABASEURLFILE | Fallback for --database-url-file | Required owner-only file containing the restricted lifecycle PostgreSQL URL. |\n| AIPCONNECTORCONTROLSIGNINGSEEDFILE | Fallback for --signing-seed-file | Required owner-only file containing the response-signing Ed25519 seed. |\n\nAn explicit CLI path wins. Empty environment paths are treated as absent. Both\nfiles must be regular non-symlink files with no group or other permission bits.\nOther control-plane settings, including bind address, proxy-network exception,\nprincipal ID, lease TTL, pool size, and acquire timeout, are CLI-only in this\nrevision.\n\nStandalone connector-host variables\n\nEvery one of the six public standalone hosts consumes the 45 common\nAIPCONNECTORHOST variables documented in the Connector host configuration\npage linked from the ownership table. That page is the canonical inventory for\ncommon endpoint, admitted identity, tenant, trust, storage, topology,\ncredential, lifecycle, callback, event, and limit settings.\n\nEach host then adds its product-owned prefix shown in the ownership table. The\nconnector-local configuration page owns those provider endpoints, account or\nworkspace identifiers, operation descriptors, policy files, and credential\nfile references. This global page does not duplicate them because their\nrequired combinations and defaults differ by connector.\n\ngetaip variables\n\n| Variable | Default or purpose |\n\n| GETAIPNATIVEBEARERTOKEN | Fallback inline native HTTP bearer token. Prefer the file variable. |\n| GETAIPNATIVEBEARERTOKENFILE | Owner-only native bearer-token file. |\n| GETAIPNATIVESIGNINGSEEDFILE | Owner-only Ed25519 seed file for signed native HTTP requests. |\n| GETAIPNATIVEPRINCIPALID | Signed native principal; environment overrides CLI, whose default is agent:getaip:cli. |\n| GETAIPNATIVETRUSTDOMAIN | Trust domain carried by signed native HTTP requests. |\n| GETAIPNATIVETLSCAFILE | Additional PEM root for native private-PKI TLS. |\n| GETAIPNATIVEPEERDID | Pinned Ed25519 DID expected on native responses. |\n| GETAIPNATIVEPEERDIDFILE | File containing the pinned response DID; mutually exclusive with inline DID. |\n| GETAIPNATIVEMAXRESPONSEBYTES | Native HTTP response bound; environment overrides CLI, whose default is 4194304. |\n| GETAIPNATSUSERNAME | Native NATS username; requires the password file. |\n| GETAIPNATSPASSWORDFILE | Owner-only native NATS password file; requires the username. |\n| GETAIPNATSSIGNINGSEEDFILE | Owner-only Ed25519 seed file for signed native NATS requests. |\n| GETAIPMCPBEARERTOKEN | Fallback bearer token for MCP HTTP subcommands. |\n\nExcept for the documented principal and response-size overrides, explicit\ngetaip options take precedence. Do not export long-lived inline tokens into a\nshared shell profile. Prefer owner-only files and give the CLI process access\nonly for the duration of the operation.\n\nThe native bearer token and bearer-token file are mutually exclusive. The\ninline native peer DID and peer-DID file are also mutually exclusive. NATS\nusername and password file must resolve together; the NATS signing seed remains\na separate AIP message-signing identity.\n"
  },
  "integrity": {
    "algorithm": "sha256",
    "sourceDigest": "c59be0e4871676ac8d5db9ccc4e6656dbd38da20ab2fe8a90d9dac990968c39f"
  }
}