getaip-server configuration

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 MCP settings without mixing product credentials into the gateway process.

The option surface is implemented by CoreArgs at source revision d7cce13d1d555644d04a4d73c66c95b113737635. It does not include Cal.diy, Hermes Agent, Chatwoot, Dify, CrewAI, or Twenty provider settings. Those belong to standalone connector hosts. Existing bundled Cal.diy or Hermes Agent deployments use the separate legacy bundled deployment.

All defaults below are implementation defaults for the reviewed revision, not capacity recommendations or evidence that a deployment has qualified for its intended load.

Value resolution

Most single-value settings resolve in this order:

1. command-line option;
2. corresponding environment variable;
3. implementation default or unset.

Boolean command-line and environment switches are combined: either one can enable the behavior. Repeatable command-line lists are extended with values from their environment list. The complete environment inventory and delimiter rules live in Environment variables.

There are two precedence exceptions. GETAIP_SERVER_NATIVE_PRINCIPAL overrides the value parsed from --native-principal, and GETAIP_SERVER_MCP_PRINCIPAL overrides the value parsed from --mcp-principal. GETAIP_SERVER_NATS_REQUEST_TIMEOUT_MS also overrides the CLI timeout value. Configure only one source for these values.

Inline and file forms of the same secret are mutually exclusive even when one form comes from the environment. Prefer the file form when it exists.

Process identity and modes

A non-loopback listener requires an explicit HTTPS public base URL. Insecure development is restricted to a loopback listener. HTTP public origins are accepted only when both the listener and origin are loopback-scoped and insecure development is explicit.

--print-manifest takes precedence over --mcp-stdio when both are present. Startup failures are emitted as structured JSON on stderr and exit with a non-zero status.

Native authentication and trust

Incoming envelopes are signed by default unless GETAIP_SERVER_ALLOW_UNSIGNED_ENVELOPES explicitly disables the default and neither the CLI nor GETAIP_SERVER_REQUIRE_SIGNED_ENVELOPES restores it. Outside insecure development, unsigned native envelopes still require native bearer authentication. Caller-supplied from data is not a replacement for an authenticated edge identity.

Inline and file signer bindings are merged. Every signer DID must be a valid Ed25519 did:key, and DIDs must be unique across both sources. The signer file uses this exact shape and rejects unknown fields:

[
  {
    "signer_did": "did:key:<ed25519-multibase-value>",
    "principal_id": "service:trusted-edge"
  }
]

The trusted identity file rejects an empty directory, zero revisions, revoked or expired entries, duplicate principals, and invalid tenant or credential bindings. The approval file rejects an empty directory, zero revisions, duplicate principals, and invalid memberships. When either file is absent, the corresponding resolver denies the operation rather than trusting an implicit identity.

Callback policy and runtime work budgets

An allowed callback host requires a response and callback signing seed. An A2A push encryption key also requires that signing seed. Each work budget must be greater than zero.

The callback request timeout and maximum response size are environment-only settings in this revision. Their defaults are 5,000 milliseconds and 4 MiB. See the environment reference for their exact names.

The HTTP and private-network switches weaken the default destination policy. They affect callbacks, HTTP delegation destinations, and other routes that use the shared callback policy. Keep them disabled unless the deployment owns and reviews the complete isolated network path.

Runtime storage

--postgres-url and --postgres-url-file are mutually exclusive. PostgreSQL is the core runtime store when either form resolves. Otherwise, a configured storage directory supplies durable local runtime state; without either, core runtime state is in memory.

The storage directory can still own MCP correlation and replay files when PostgreSQL owns core runtime state. Treat both stores as one recovery boundary when both are configured. Use PostgreSQL for replicas that share one logical runtime; do not point several processes at one local storage directory.

Connector-fleet activation and transport

Fleet mode is disabled when no connector-registry URL resolves. Supplying any other fleet, topology, admission, or connector-event CLI option without that URL is a configuration error. The environment reference records the exact activation behavior for environment-only settings.

Fleet mode requires a registry URL, signing-seed file, and one of these destination policies:

• at least one explicit --connector-fleet-allowed-host; or
• --connector-fleet-trust-registry-endpoints.

The gateway opens the registry through the data-plane constructor. The configured database role must not have registry-administrator authority. The additional CA augments the public trust roots; it does not disable certificate or hostname verification.

The fleet callback URL must be an absolute HTTP(S) URL with no credentials, query, or fragment and the exact callback path. Plain HTTP requires the explicit fleet HTTP exception. Configuring the URL makes remote streaming available; without it, the remote implementation support does not advertise streaming.

Fleet topology and local admission

Every numeric admission bound must be greater than zero. The per-tenant in-flight bound cannot exceed the global in-flight bound, and the per-tenant queue bound cannot exceed the global queue bound. Tenant IDs in weight entries contain 1–256 bytes, weights are positive, and a tenant can appear only once across the merged CLI and environment list.

Topology preferences apply when the registry creates a new assignment. An existing action remains pinned to its assigned replica; changing a preference does not move active work.

Connector-event and stream ingress

These options configure the gateway’s shared authenticated connector-event ingress. They are valid only in fleet mode.

Every limit must be greater than zero. Event and stream envelopes still require the admitted route identity, signature, timestamp, sequence, replay, and assignment checks; increasing a size or time limit does not bypass those checks.

Native NATS

NATS is disabled when the server URL is absent. Supplying authentication without a server URL is an error. Username and password file must appear together; configuring neither selects an unauthenticated connection and does not create TLS, account, or subject authorization outside the process.

Remote delegation routes

HTTP route syntax is:

DELEGATE_ID=URL,PEER_ID,PEER_DID[,TRUST_DOMAIN]

NATS route syntax is:

CAPABILITY_ID=SERVER_URL,SUBJECT,PEER_ID,PEER_DID[,TIMEOUT_MS[,TRUST_DOMAIN]]

The NATS route timeout defaults to 30,000 milliseconds. Both route forms use the daemon trust domain when the optional route trust domain is absent. Routes require a response and callback signing seed, a valid peer principal and did:key, and a destination accepted by the shared callback policy. The daemon validates each route before serving.

MCP compatibility profile

If a static token, authorization server, supported scope, or documentation URL is set without an explicit resource, the implementation derives http://<bind>/mcp. Set --mcp-resource explicitly for a public deployment so the protected-resource identifier matches the external origin.

Introspection is an all-or-none group: URL, issuer, client ID, and secret file must all resolve. It also requires a protected-resource policy, rejects a simultaneous static token, and requires the introspection issuer to appear in the advertised authorization-server list. The URL must use HTTPS unless the explicit exception permits a loopback HTTP fixture.

The protected-resource configuration permits loopback browser origins in addition to the explicit origin list. Treat MCP stdio as a separate local transport whose authentication boundary is the trusted spawning process.

File contracts

Secret files must be regular non-symlink files. On Unix the loader rejects any group or other permission bit and reports the expected contract as mode 0600; an owner-readable 0400 mount also satisfies the implemented bitmask.

Secret values are bounded by their owning option and decoded as UTF-8 where required. The common inline-or-file text resolver trims values and rejects an empty result; other secret consumers apply their own parser.

Trusted signer, trusted identity, approval authority, and fleet TLS CA files use the secure-configuration loader. They must be regular non-symlink files, cannot exceed 1 MiB, and cannot be group- or world-writable on Unix. Read-only access for a deployment-owned group is therefore different from secret-file permission and should be granted only when the owning policy requires it.

Mount configuration and secrets read-only. The process reads them during startup; this revision does not implement an in-process configuration reload. A changed value requires a controlled restart and the recovery procedure owned by that setting.

Startup coupling summary

Use Deploy AIP in production for the ordered deployment procedure, Connector host configuration for the separate host process, and Observe and recover for runtime diagnosis. This page owns option lookup; those guides own task flow and recovery decisions.