Environment Variables — AIP Documentation

aipd accepts environment variables for deployment wiring and secret-file references. Command-line options are easier to inspect locally; environment variables are useful in orchestrators that inject configuration at process start.

For single-value settings, an explicit CLI value normally takes precedence. AIPD_NATIVE_PRINCIPAL and AIPD_MCP_PRINCIPAL are the exceptions in the 1.0 binary: when present, the environment value wins. Repeatable lists merge CLI and environment values. List variables accept comma, semicolon, or newline separators unless a row states otherwise. Boolean CLI and environment switches are combined as logical OR, except that AIPD_ALLOW_UNSIGNED_ENVELOPES controls the default signature requirement directly.

Boolean variables are enabled by 1, true, TRUE, yes, or YES.

Runtime and Native Security

Variable	Purpose
`AIPD_STORAGE_DIR`	Single-host durable state directory
`AIPD_POSTGRES_URL`	PostgreSQL runtime backend URL
`AIPD_NATIVE_BEARER_TOKEN`	Inline native operational bearer token
`AIPD_NATIVE_BEARER_TOKEN_FILE`	Owner-only file containing the native token
`AIPD_NATIVE_PRINCIPAL`	Principal established by native bearer authentication
`AIPD_NATIVE_PRINCIPAL_SCOPES`	Scopes granted to the native principal
`AIPD_TRUSTED_IDENTITY_FILE`	Trusted identity, tenant, and credential-reference directory
`AIPD_APPROVAL_AUTHORITY_FILE`	Trusted approval authority directory
`AIPD_TRUSTED_SIGNERS`	`DID=PRINCIPAL_ID` bindings; semicolon or newline separated
`AIPD_REQUIRE_SIGNED_ENVELOPES`	Explicitly require signed native envelopes
`AIPD_ALLOW_UNSIGNED_ENVELOPES`	Disable the default signed-envelope requirement; dangerous
`AIPD_INSECURE_DEVELOPMENT`	Permit unauthenticated native traffic on loopback only

AIPD_ALLOW_UNSIGNED_ENVELOPES does not make production traffic safe. Use it only when another explicit, tested trust boundary owns native authentication.

NATS

Variable	Purpose
`AIPD_NATS_URL`	NATS server URL
`AIPD_NATS_USERNAME`	NATS username
`AIPD_NATS_PASSWORD_FILE`	Owner-only NATS password file
`AIPD_NATS_TRUST_DOMAIN`	Native subject trust-domain segment
`AIPD_NATS_SERVICE`	Native subject service segment
`AIPD_NATS_VERSION`	Native subject version segment
`AIPD_NATS_QUEUE_GROUP`	Queue group for scaled consumers
`AIPD_NATS_REQUEST_TIMEOUT_MS`	Request timeout in milliseconds

Username and password-file settings must be provided together.

aipctl accepts an independent client-side NATS security set:

Variable	Purpose
`AIPCTL_NATS_USERNAME`	NATS username used by native CLI requests
`AIPCTL_NATS_PASSWORD_FILE`	Owner-only NATS password file used by the CLI
`AIPCTL_NATS_SIGNING_SEED_FILE`	Owner-only file containing a hex-encoded 32-byte Ed25519 seed

The CLI password file is required with the CLI username. Signed native requests additionally require the seed-derived DID to be bound to agent:aipctl in AIPD_TRUSTED_SIGNERS and in the deployment’s trusted identity directory.

Delegation and Callbacks

Variable	Purpose
`AIPD_DELEGATION_HTTP_ROUTES`	HTTP delegation routes; semicolon or newline separated
`AIPD_DELEGATION_NATS_ROUTES`	NATS delegation routes; semicolon or newline separated
`AIPD_CALLBACK_ALLOWED_HOSTS`	Exact outbound callback hosts
`AIPD_CALLBACK_SIGNING_SEED_HEX`	Hex-encoded 32-byte Ed25519 signing seed
`AIPD_CALLBACK_TIMEOUT_MS`	Per-attempt callback timeout; default 5000 ms
`AIPD_CALLBACK_ALLOW_HTTP`	Permit plaintext callback targets
`AIPD_CALLBACK_ALLOW_PRIVATE_NETWORKS`	Permit private or loopback targets
`AIPD_A2A_PUSH_ENCRYPTION_KEY_HEX`	Hex-encoded 32-byte key for A2A push credentials at rest

Delegation routes require the callback signing seed because native remote requests are signed. A2A push encryption also requires callback signing.

MCP

Variable	Purpose
`AIPD_MCP_BEARER_TOKEN`	Static MCP Streamable HTTP token
`AIPD_MCP_RESOURCE`	Protected-resource identifier
`AIPD_MCP_AUTHORIZATION_SERVERS`	Advertised authorization-server issuers
`AIPD_MCP_SCOPES`	Advertised supported scopes
`AIPD_MCP_REQUIRED_SCOPES`	Scopes required when establishing an MCP session
`AIPD_MCP_RESOURCE_DOCUMENTATION`	Human-readable protected-resource documentation URL
`AIPD_MCP_ALLOWED_ORIGINS`	Allowed browser origins
`AIPD_MCP_INTROSPECTION_URL`	RFC 7662 endpoint
`AIPD_MCP_INTROSPECTION_ISSUER`	Trusted introspection issuer
`AIPD_MCP_INTROSPECTION_CLIENT_ID`	Introspection client id
`AIPD_MCP_INTROSPECTION_CLIENT_SECRET_FILE`	Owner-only introspection client-secret file
`AIPD_MCP_INTROSPECTION_ALLOW_LOOPBACK_HTTP`	Permit a loopback plaintext introspection fixture
`AIPD_MCP_PRINCIPAL`	AIP principal established for MCP traffic
`AIPD_MCP_PRINCIPAL_SCOPES`	Scopes granted to the MCP principal

The loopback introspection exception is for isolated qualification fixtures. A network deployment must use HTTPS and validate issuer, audience, subject, activity, expiration, and required scopes.

Hermes Agent

Variable	Purpose
`AIPD_HERMES_ENDPOINTS`	`ID=URL` entries; comma, semicolon, or newline separated
`AIPD_HERMES_API_KEY`	Shared Hermes API-server bearer token
`AIPD_HERMES_OPERATOR_DELEGATION_ENABLED`	Enable governed operator routing
`AIPD_HERMES_OPERATOR_MODEL`	Model route for operator runs
`AIPD_HERMES_OPERATOR_INSTRUCTIONS_FILE`	Trusted instructions file
`AIPD_HERMES_OPERATOR_INSTRUCTIONS`	Inline trusted instructions; file form is preferred
`AIPD_HERMES_OPERATOR_TIMEOUT_MS`	Maximum observation duration
`AIPD_HERMES_OPERATOR_POLL_MS`	Recovery polling interval
`AIPD_HERMES_OPERATOR_MAX_EVENTS`	Maximum accepted structured run events
`AIPD_HERMES_OPERATOR_MAX_INPUT_BYTES`	Maximum serialized AIP input size
`AIPD_HERMES_OPERATOR_MAX_DELEGATION_DEPTH`	Accepted delegation depth
`AIPD_HERMES_OPERATOR_CLAIM_TTL_MS`	Exclusive run/approval claim TTL
`AIPD_HERMES_OPERATOR_CANCEL_GRACE_MS`	Cancellation reconciliation grace period
`AIPD_HERMES_OPERATOR_CAPABILITY_PREFIXES`	Allowed delegated capability prefixes
`AIPD_HERMES_OPERATOR_APPROVAL_EXEMPT_CAPABILITY_PREFIXES`	Explicit unattended capability prefixes
`AIPD_HERMES_OPERATOR_SCOPE_PREFIXES`	Allowed delegated scope prefixes

Treat inline API keys and instructions as sensitive process configuration. Use the deployment secret boundary and the file form where available.

Cal.diy

Variable	Purpose
`AIPD_CAL_DIY_BASE_URL`	Self-hosted Cal.diy API base URL
`AIPD_CAL_DIY_ACCOUNT_ID`	Deployment-local account id
`AIPD_CAL_DIY_MAX_RESPONSE_BYTES`	Accepted provider response limit
`AIPD_CAL_DIY_BEARER_TOKEN_FILE`	API key or access-token file
`AIPD_CAL_DIY_OAUTH_CLIENT_ID`	OAuth client id
`AIPD_CAL_DIY_OAUTH_CLIENT_SECRET_FILE`	OAuth client-secret file
`AIPD_CAL_DIY_TENANT_ACCOUNTS`	`TENANT_ID=ACCOUNT_ID` mappings
`AIPD_CAL_DIY_CREDENTIAL_FILES`	`OPAQUE_HANDLE=FILE` mappings
`AIPD_CAL_DIY_WEBHOOK_SECRET_FILES`	`OPAQUE_REF=FILE` mappings
`AIPD_CAL_DIY_WEBHOOK_REPLAY_FILE`	Durable single-process replay-observation file
`AIPD_CAL_DIY_WEBHOOK_SUBSCRIBER_PREFIXES`	Allowed deployment-owned HTTPS ingress prefixes

Bearer and OAuth client authentication are mutually exclusive. Mapping lists accept semicolons or newlines as separators so URLs and values remain intact.

Deterministic Sandbox Connectors

Variable	Purpose
`AIPD_SUPPORT_SANDBOX_DATABASE_URL`	Support-system test database
`AIPD_ENTERPRISE_SANDBOX_DATABASE_URL`	Enterprise-scenario test database

These connectors support deterministic protocol campaigns. They are not a substitute for production product connectors.

`aipctl`

Variable	Purpose
`AIPCTL_NATIVE_BEARER_TOKEN`	Default native HTTP token for `aipctl`
`AIPCTL_MCP_BEARER_TOKEN`	Default MCP HTTP token for MCP subcommands

An explicit CLI token takes precedence. Avoid exporting long-lived tokens into shared shell profiles or command histories.