# Environment Variables

`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.