Environment variables

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 process owns a value, how it combines with command-line configuration,
and whether it activates an optional subsystem.

The inventory reflects source revision
d7cce13d1d555644d04a4d73c66c95b113737635. It does not include variables
used only by the migration-only bundled binary or by non-public development
modules.

Choose the correct owner

| Prefix | Owning process | Canonical configuration owner |

| GETAIPSERVER | Product-neutral getaip-server gateway | This page and getaip-server configuration (configuration.md) |
| AIPCONNECTORCONTROL | Standalone connector lifecycle control plane | Control-plane section on this page |
| AIPCONNECTORHOST | Common bootstrap for every standalone connector host | Connector host configuration (connector-host-configuration.md) |
| AIPCALDIY | Standalone Cal.diy host | Cal.diy connector-local configuration |
| AIPHERMES | Standalone Hermes Agent host | Hermes Agent connector-local configuration |
| AIPCHATWOOT | Standalone Chatwoot host | Chatwoot connector-local configuration |
| AIPDIFY | Standalone Dify host | Dify connector-local configuration |
| AIPCREWAI | Standalone CrewAI host | CrewAI connector-local configuration |
| AIPTWENTY | Standalone Twenty host | Twenty connector-local configuration |
| GETAIP | getaip client process | Tool section on this page and the getaip reference (cli.md) |

Do not copy provider credentials from a standalone host into a
GETAIPSERVER variable. The AIPCALDIY prefix is owned by the standalone
Cal.diy host; it does not make Cal.diy part of the
product-neutral gateway.

Resolution and parsing rules

For most scalar getaip-server settings, an explicit CLI value wins and the environment
is the fallback. These variables are exceptions:
• GETAIPSERVERNATIVEPRINCIPAL overrides the CLI principal, including an explicit
  --native-principal value;
• GETAIPSERVERMCPPRINCIPAL overrides the CLI principal, including an explicit
  --mcp-principal value;
• GETAIPSERVERNATSREQUESTTIMEOUTMS overrides
  --nats-request-timeout-ms.

Boolean variables are true only for 1, true, TRUE, yes, or YES.
Every other value, including an empty string, is false. Boolean environment and
CLI switches are otherwise combined as logical OR.

Unsigned integer variables use strict decimal parsing. A malformed or negative
value fails startup even when the subsystem would later remain disabled.
Values that must be positive receive an additional validation check.

Two list formats exist:

| Format | Separators | Variables using it |

| Route list | Semicolon or newline | Trusted signer and delegation specifications |
| General list | Comma, semicolon, or newline | Hosts, scopes, issuers, origins, topology weights, and other repeatable values |

Environment list entries extend the corresponding CLI list. They do not
replace it. Duplicate entries can fail a later uniqueness check.

An empty environment value is not a portable substitute for unsetting a
variable. Some paths filter empty values, while other paths parse or validate
them and fail. Remove an unused variable from the process environment.

getaip-server process and storage

| Variable | CLI relation | Default or purpose |

| GETAIPSERVERPUBLICBASEURL | Fallback for --public-base-url | External HTTPS origin advertised for A2A and discovery. |
| GETAIPSERVERSTORAGEDIR | Fallback for --storage-dir | Durable local and auxiliary file state. |
| GETAIPSERVERPOSTGRESURL | Fallback for --postgres-url | Inline clustered runtime PostgreSQL URL. Prefer the file variable. |
| GETAIPSERVERPOSTGRESURLFILE | Fallback for --postgres-url-file | Mode-0600 file containing the runtime PostgreSQL URL. |

The PostgreSQL inline and file variables are mutually exclusive after CLI and
environment resolution. PostgreSQL owns core runtime state when either form
resolves; otherwise the storage directory owns local runtime state. With
neither, core runtime state is in memory.

The listener address, service ID, trust domain, manifest-print mode, and MCP
stdio mode have no GETAIPSERVER environment equivalent in this revision. Configure
them with CLI options.

getaip-server native identity and authorization

| Variable | Type or format | Default or purpose |

| GETAIPSERVERTRUSTEDSIGNERS | Route list of DID=PRINCIPALID | Extends inline trusted signer bindings. |
| GETAIPSERVERTRUSTEDSIGNERFILE | Path | Additional bounded JSON signer directory. |
| GETAIPSERVERNATIVEBEARERTOKEN | Secret text | Inline native HTTP bearer token. Prefer the file variable. |
| GETAIPSERVERNATIVEBEARERTOKENFILE | Secret-file path | Mode-0600 native bearer-token file. |
| GETAIPSERVERNATIVEPRINCIPAL | Principal ID | Overrides the CLI native principal; CLI default is service:getaip:server:http-edge. |
| GETAIPSERVERNATIVETENANTID | Tenant ID | Verified tenant bound to native bearer authentication. |
| GETAIPSERVERNATIVEPRINCIPALSCOPES | General list | Extends scopes granted to the native principal. |
| GETAIPSERVERTRUSTEDIDENTITYFILE | Path | Revisioned trusted identity, tenant, credential, and context directory. |
| GETAIPSERVERAPPROVALAUTHORITYFILE | Path | Revisioned approval-authority membership directory. |
| GETAIPSERVERREQUIRESIGNEDENVELOPES | Boolean | Explicitly enables signed native envelopes. |
| GETAIPSERVERALLOWUNSIGNEDENVELOPES | Boolean | Disables the default signature requirement unless another require switch restores it. |
| GETAIPSERVERINSECUREDEVELOPMENT | Boolean | Enables unauthenticated native development only on loopback. |

GETAIPSERVERNATIVEBEARERTOKEN and GETAIPSERVERNATIVEBEARERTOKENFILE cannot both
resolve. Signatures are required by default. To accept unsigned envelopes,
GETAIPSERVERALLOWUNSIGNEDENVELOPES must be true while the CLI and environment
require switches are false. Outside loopback-only insecure development, native
bearer authentication is still required for unsigned traffic.

Signer bindings from the route list and file are merged. Every signer must use
a valid Ed25519 did:key, and a DID cannot occur twice across the combined
sources.

getaip-server callbacks and runtime budgets

| Variable | Type or format | Default or purpose |

| GETAIPSERVERCALLBACKALLOWEDHOSTS | General list | Exact outbound callback hosts. |
| GETAIPSERVERCALLBACKSIGNINGSEEDHEX | Secret hex | Inline 32-byte response and callback signing seed. Prefer the file variable. |
| GETAIPSERVERCALLBACKSIGNINGSEEDFILE | Secret-file path | Mode-0600 response and callback signing-seed file. |
| GETAIPSERVERA2APUSHENCRYPTIONKEYHEX | Secret hex | Inline 32-byte key for stored A2A push credentials. |
| GETAIPSERVERCALLBACKALLOWHTTP | Boolean | Permits plaintext callback and shared-policy destinations. |
| GETAIPSERVERCALLBACKALLOWPRIVATENETWORKS | Boolean | Permits private or loopback shared-policy destinations. |
| GETAIPSERVERCALLBACKTIMEOUTMS | Unsigned integer | Callback request timeout; default 5000. Environment-only. |
| GETAIPSERVERCALLBACKMAXRESPONSEBYTES | Unsigned integer | Callback response bound; default 4194304. Environment-only. |
| GETAIPSERVERCALLBACKMAXINFLIGHT | Positive integer | Concurrent callback deliveries; default 64. |
| GETAIPSERVERCALLBACKRECOVERYBATCH | Positive integer | Callback records leased per recovery cycle; default 64. |
| GETAIPSERVERRECONCILIATIONMAXINFLIGHT | Positive integer | Concurrent transaction reconciliations; default 32. |

The inline and file signing-seed variables are mutually exclusive. An allowed
callback host, A2A push key, or delegation route requires a response and
callback signing seed. The HTTP and private-network variables expand the
destination boundary shared by callbacks and HTTP delegation.

getaip-server connector registry and fleet transport

| Variable | Type or format | Default or purpose |

| GETAIPSERVERCONNECTORREGISTRYURL | Secret text | Inline registry data-plane PostgreSQL URL. Prefer the file variable. |
| GETAIPSERVERCONNECTORREGISTRYURLFILE | Secret-file path | Mode-0600 registry data-plane URL file. |
| GETAIPSERVERCONNECTORREGISTRYDATAMAXCONNECTIONS | Positive integer | Registry data connections; default 32. |
| GETAIPSERVERCONNECTORREGISTRYACQUIRETIMEOUTMS | Positive integer | Connection wait; default 5000, maximum 60000. |
| GETAIPSERVERCONNECTORFLEETSIGNINGSEEDFILE | Secret-file path | Required 32-byte Ed25519 seed file for fleet mode. |
| GETAIPSERVERCONNECTORFLEETCALLBACKURL | URL | Central stream callback ending in /aip/v1/connector-callbacks. |
| GETAIPSERVERCONNECTORFLEETALLOWEDHOSTS | General list | Exact connector-host destination hosts. |
| GETAIPSERVERCONNECTORFLEETTRUSTREGISTRYENDPOINTS | Boolean | Uses admitted registry endpoints as the per-route host allowlist. |
| GETAIPSERVERCONNECTORFLEETALLOWHTTP | Boolean | Permits plaintext host and fleet callback URLs. |
| GETAIPSERVERCONNECTORFLEETALLOWPRIVATENETWORKS | Boolean | Permits private or loopback connector-host addresses. |
| GETAIPSERVERCONNECTORFLEETTIMEOUTMS | Positive integer | Connector-host request timeout; default 5000. |
| GETAIPSERVERCONNECTORFLEETMAXRESPONSEBYTES | Positive integer | Host response bound; default 4194304. |
| GETAIPSERVERCONNECTORFLEETRETRYBUDGET | Unsigned integer | Retries after the first attempt; default 2. |
| GETAIPSERVERCONNECTORFLEETMAXCACHEDCLIENTS | Positive integer | Cached host HTTP pools; default 256. |
| GETAIPSERVERCONNECTORFLEETTLSCAFILE | Path | Additional PEM root for private-PKI host TLS. |

The registry inline and file variables are mutually exclusive. A resolved
registry URL activates fleet composition and then requires the signing-seed
file plus either explicit allowed hosts or registry endpoint trust.

getaip-server fleet topology and admission

| Variable | Type or format | Default or purpose |

| GETAIPSERVERCONNECTORFLEETREGION | Text | Preferred region for new assignments; unset by default. |
| GETAIPSERVERCONNECTORFLEETZONE | Text | Preferred zone for new assignments; unset by default. |
| GETAIPSERVERCONNECTORFLEETCAPACITYCLASS | Text | Required capacity class for new assignments; unset by default. |
| GETAIPSERVERCONNECTORFLEETDISABLECROSSREGIONFAILOVER | Boolean | Forbids new-assignment fallback to another region. |
| GETAIPSERVERCONNECTORFLEETMAXINFLIGHT | Positive integer | Global active remote actions; default 1024. |
| GETAIPSERVERCONNECTORFLEETMAXINFLIGHTPERTENANT | Positive integer | Active remote actions per tenant; default 128. |
| GETAIPSERVERCONNECTORFLEETMAXQUEUED | Positive integer | Global waiting actions; default 4096. |
| GETAIPSERVERCONNECTORFLEETMAXQUEUEDPERTENANT | Positive integer | Waiting actions per tenant; default 512. |
| GETAIPSERVERCONNECTORFLEETMAXQUEUEBYTES | Positive integer | Canonical bytes retained by queued actions; default 67108864. |
| GETAIPSERVERCONNECTORFLEETMAXREQUESTBYTES | Positive integer | Canonical size of one remote action; default 4194304. |
| GETAIPSERVERCONNECTORFLEETMAXQUEUEAGEMS | Positive integer | Maximum local queue time; default 30000. |
| GETAIPSERVERCONNECTORFLEETTENANTWEIGHTS | General list of TENANTID=WEIGHT | Positive scheduling weights; none by default. |

Per-tenant limits cannot exceed their global counterparts. Weight tenant IDs
contain 1–256 bytes, each weight is positive, and duplicate tenant IDs fail
startup. Topology preferences affect new assignments, not already pinned work.

getaip-server fleet activation nuance

GETAIPSERVERCONNECTORREGISTRYURL or
GETAIPSERVERCONNECTORREGISTRYURLFILE is the only environment activation boundary
for fleet mode. Do not infer activation from another fleet variable.

Without a registry URL, these environment groups explicitly make the
configuration partial and fail startup:
• signing-seed file and fleet callback URL;
• allowed hosts or any fleet network-policy Boolean;
• tenant weights;
• cross-region failover disablement;
• any connector-event or stream-ingress limit.

Valid environment-only pool, transport numeric, topology text, admission
numeric, and TLS CA settings do not activate fleet mode and are not all treated
as partial configuration in the reviewed implementation. They can be parsed or
their file can be read, then discarded when the registry URL is absent. An
invalid numeric value or unreadable CA file can still fail startup.

Set the registry URL explicitly and verify the /ready fleet section rather
than using a tuning value as an activation probe.

getaip-server connector-event and stream ingress

| Variable | Type | Default or purpose |

| GETAIPSERVERCONNECTOREVENTMAXENVELOPEBYTES | Positive integer | Signed envelope bound; default 4194304. |
| GETAIPSERVERCONNECTOREVENTMAXEVENTSPERENVELOPE | Integer 1–1000 | Events per envelope; default 100. |
| GETAIPSERVERCONNECTOREVENTMAXEVENTBYTES | Positive integer | One enriched event; default 262144, no more than envelope bound. |
| GETAIPSERVERCONNECTORSTREAMMAXCHUNKBYTES | Positive integer | One stream chunk; default 262144, no more than envelope bound. |
| GETAIPSERVERCONNECTOREVENTMAXINFLIGHT | Positive integer | Concurrent storage operations; default 128. |
| GETAIPSERVERCONNECTOREVENTMAXAGESECONDS | Positive integer | Maximum event age; default 86400. |
| GETAIPSERVERCONNECTOREVENTMAXFUTURESKEWSECONDS | Positive integer | Future clock skew; default 300. |
| GETAIPSERVERCONNECTORSTREAMCALLBACKMAXAGESECONDS | Positive integer | Signed stream callback age; default 300. |

Any one of these variables without a registry URL is rejected as partial fleet
configuration. The limits do not replace route, tenant, signature, timestamp,
sequence, lease, or replay validation.

getaip-server NATS and delegation

| Variable | Type or format | Default or purpose |

| GETAIPSERVERNATSURL | URL | Enables native NATS request/reply. |
| GETAIPSERVERNATSUSERNAME | Text | NATS username; requires the password file. |
| GETAIPSERVERNATSPASSWORDFILE | Secret-file path | Mode-0600 NATS password; requires the username. |
| GETAIPSERVERNATSTRUSTDOMAIN | Text | Subject trust domain; defaults to the daemon trust domain. |
| GETAIPSERVERNATSSERVICE | Text | Subject service; default getaip-server. |
| GETAIPSERVERNATSVERSION | Text | Subject version; default v1. |
| GETAIPSERVERNATSQUEUEGROUP | Text | Optional queue group. |
| GETAIPSERVERNATSREQUESTTIMEOUTMS | Unsigned integer | Request timeout; overrides CLI, whose default is 30000. |
| GETAIPSERVERDELEGATIONHTTPROUTES | Route list | DELEGATEID=URL,PEERID,PEERDID[,TRUSTDOMAIN]. |
| GETAIPSERVERDELEGATIONNATSROUTES | Route list | CAPABILITYID=SERVERURL,SUBJECT,PEERID,PEERDID[,TIMEOUTMS[,TRUSTDOMAIN]]. |

Authentication values without GETAIPSERVERNATSURL fail startup. Username and
password file must resolve together. Delegation lists extend CLI routes and
require the response and callback signing seed.

getaip-server MCP

| Variable | Type or format | Default or purpose |

| GETAIPSERVERMCPBEARERTOKEN | Secret text | Static MCP HTTP bearer token. |
| GETAIPSERVERMCPRESOURCE | Resource identifier | Protected-resource identifier. |
| GETAIPSERVERMCPAUTHORIZATIONSERVERS | General list | Advertised authorization-server issuers. |
| GETAIPSERVERMCPSCOPES | General list | Advertised supported scopes. |
| GETAIPSERVERMCPREQUIREDSCOPES | General list | Scopes required to establish an MCP HTTP session. |
| GETAIPSERVERMCPRESOURCEDOCUMENTATION | URL | Human-readable protected-resource documentation. |
| GETAIPSERVERMCPALLOWEDORIGINS | General list | Browser origins allowed to call MCP HTTP. |
| GETAIPSERVERMCPINTROSPECTIONURL | HTTPS URL | RFC 7662 endpoint. |
| GETAIPSERVERMCPINTROSPECTIONISSUER | Issuer | Trusted issuer represented by introspection. |
| GETAIPSERVERMCPINTROSPECTIONCLIENTID | Text | OAuth introspection client ID. |
| GETAIPSERVERMCPINTROSPECTIONCLIENTSECRETFILE | Secret-file path | Mode-0600 introspection client secret. |
| GETAIPSERVERMCPINTROSPECTIONALLOWLOOPBACKHTTP | Boolean | Permits a loopback plaintext introspection fixture. |
| GETAIPSERVERMCPPRINCIPAL | Principal ID | Overrides the CLI MCP principal; CLI default is service:getaip:server:mcp-edge. |
| GETAIPSERVERMCPPRINCIPALSCOPES | General list | Extends scopes granted to the MCP principal. |

Introspection URL, issuer, client ID, and secret file are an all-or-none group.
Introspection also requires a protected resource, rejects a simultaneous static
token, and requires its issuer in the advertised authorization-server list.

When resource is absent, a static token, authorization server, supported scope,
or documentation URL causes the implementation to derive
http:///mcp. Set GETAIPSERVERMCPRESOURCE explicitly for a public origin.

Connector control-plane variables

The standalone aip-connector-control-plane consumes two environment
variables:

| Variable | CLI relation | Purpose |

| AIPCONNECTORCONTROLDATABASEURLFILE | Fallback for --database-url-file | Required owner-only file containing the restricted lifecycle PostgreSQL URL. |
| AIPCONNECTORCONTROLSIGNINGSEEDFILE | Fallback for --signing-seed-file | Required owner-only file containing the response-signing Ed25519 seed. |

An explicit CLI path wins. Empty environment paths are treated as absent. Both
files must be regular non-symlink files with no group or other permission bits.
Other control-plane settings, including bind address, proxy-network exception,
principal ID, lease TTL, pool size, and acquire timeout, are CLI-only in this
revision.

Standalone connector-host variables

Every one of the six public standalone hosts consumes the 45 common
AIPCONNECTORHOST variables documented in the Connector host configuration
page linked from the ownership table. That page is the canonical inventory for
common endpoint, admitted identity, tenant, trust, storage, topology,
credential, lifecycle, callback, event, and limit settings.

Each host then adds its product-owned prefix shown in the ownership table. The
connector-local configuration page owns those provider endpoints, account or
workspace identifiers, operation descriptors, policy files, and credential
file references. This global page does not duplicate them because their
required combinations and defaults differ by connector.

getaip variables

| Variable | Default or purpose |

| GETAIPNATIVEBEARERTOKEN | Fallback inline native HTTP bearer token. Prefer the file variable. |
| GETAIPNATIVEBEARERTOKENFILE | Owner-only native bearer-token file. |
| GETAIPNATIVESIGNINGSEEDFILE | Owner-only Ed25519 seed file for signed native HTTP requests. |
| GETAIPNATIVEPRINCIPALID | Signed native principal; environment overrides CLI, whose default is agent:getaip:cli. |
| GETAIPNATIVETRUSTDOMAIN | Trust domain carried by signed native HTTP requests. |
| GETAIPNATIVETLSCAFILE | Additional PEM root for native private-PKI TLS. |
| GETAIPNATIVEPEERDID | Pinned Ed25519 DID expected on native responses. |
| GETAIPNATIVEPEERDIDFILE | File containing the pinned response DID; mutually exclusive with inline DID. |
| GETAIPNATIVEMAXRESPONSEBYTES | Native HTTP response bound; environment overrides CLI, whose default is 4194304. |
| GETAIPNATSUSERNAME | Native NATS username; requires the password file. |
| GETAIPNATSPASSWORDFILE | Owner-only native NATS password file; requires the username. |
| GETAIPNATSSIGNINGSEEDFILE | Owner-only Ed25519 seed file for signed native NATS requests. |
| GETAIPMCPBEARERTOKEN | Fallback bearer token for MCP HTTP subcommands. |

Except for the documented principal and response-size overrides, explicit
getaip options take precedence. Do not export long-lived inline tokens into a
shared shell profile. Prefer owner-only files and give the CLI process access
only for the duration of the operation.

The native bearer token and bearer-token file are mutually exclusive. The
inline native peer DID and peer-DID file are also mutually exclusive. NATS
username and password file must resolve together; the NATS signing seed remains
a separate AIP message-signing identity.