aipd Configuration Reference

aipd uses explicit command-line options to compose storage, identity, transports, profiles, delegation routes, and product connectors. Run aipd --help for the exact binary you are deploying.

Use this reference to understand ownership and safe combinations. Use Environment Variables for orchestrator equivalents.

Configuration Rules

• Command-line values normally take precedence over single-value environment variables. In the current 1.0 binary, AIPD_NATIVE_PRINCIPAL and AIPD_MCP_PRINCIPAL override their CLI defaults and explicit values; avoid configuring both forms for those identities.
• Repeatable CLI and environment lists are merged.
• Secrets should enter through owner-only files or a deployment secret provider, not literal process arguments.
• File storage and PostgreSQL are alternative runtime state owners. Do not use them as an accidental mixed cluster.
• Connector capabilities are admitted only when their required configuration is complete and their handlers match the published manifest.

Process and Service Identity

Option	Purpose
--bind ADDRESS	HTTP listener; default 127.0.0.1:8080
--service-id PRINCIPAL_ID	Stable manifest principal; default agent:aipd:local
--trust-domain DOMAIN	Administrative trust domain published by the manifest
--print-manifest	Compose the deployment, print its manifest, and exit

Use a stable service id for one logical deployment. Changing it changes signer, callback, routing, and discovery identity assumptions.

Native Authentication and Identity

Option	Purpose
--require-signed-envelopes	Explicitly require Ed25519 signatures on native envelopes
--trusted-signer DID=PRINCIPAL_ID	Bind one accepted did:key signer to a principal; repeatable
--native-bearer-token TOKEN	Inline token for ergonomic native operational routes
--native-bearer-token-file FILE	Owner-only file containing the native token
--native-principal PRINCIPAL_ID	Principal established by native bearer auth; default service:aipd:http-edge
--native-principal-scope SCOPE	Scope granted to the native principal; repeatable
--trusted-identity-file FILE	Revisioned actor, tenant, external-account, and credential-reference bindings
--approval-authority-file FILE	Approval memberships, rules, grants, and revocation state
--allow-insecure-development	Permit unauthenticated native traffic on loopback only

--native-bearer-token and --native-bearer-token-file are mutually exclusive. The authenticated edge replaces caller-supplied sender metadata; an envelope’s from field is not authentication.

Signed native envelopes are required by default unless the deployment explicitly enables the dangerous AIPD_ALLOW_UNSIGNED_ENVELOPES environment override. Operational HTTP routes still require their configured native edge identity.

Runtime Storage

Option	Purpose
--storage-dir DIR	Durable single-host file state
--postgres-url URL	Shared PostgreSQL runtime state with atomic leases and fencing
--support-sandbox-postgres-url URL	Deterministic support-system test connector database
--enterprise-sandbox-postgres-url URL	Deterministic enterprise-scenario test connector database

The sandbox connectors exist for protocol campaigns. Do not treat them as production customer, billing, incident, travel, or identity systems.

Native NATS

Option	Purpose
--nats-url URL	Enable native NATS request/reply
--nats-username NAME	NATS username
--nats-password-file FILE	Owner-only password file
--nats-trust-domain DOMAIN	Subject trust-domain segment
--nats-service SERVICE	Subject service segment
--nats-version VERSION	Subject version segment
--nats-queue-group GROUP	Queue group for scaled consumers
--nats-request-timeout-ms MS	Request timeout; default 30000

Username and password file must be configured together. Production NATS also needs TLS as applicable, account isolation, subject ACLs, and broker availability outside this process.

Remote Delegation

Option	Purpose
--delegation-http-route SPEC	Authenticated native HTTP peer route selected by delegate principal; repeatable
--delegation-nats-route SPEC	Authenticated native NATS peer route selected by child capability; repeatable

Authenticated HTTP routes use:

--delegation-http-route DELEGATE_ID=URL,PEER_ID,PEER_DID[,TRUST_DOMAIN]

Authenticated NATS routes use:

--delegation-nats-route CAPABILITY_ID=SERVER_URL,SUBJECT,PEER_ID,PEER_DID[,TIMEOUT_MS[,TRUST_DOMAIN]]

Both options are repeatable. Remote delegation also requires a callback signing seed because the daemon signs native peer requests. A URL or NATS subject alone is never a peer identity.

Callbacks and A2A Push Delivery

Option	Purpose
--callback-allowed-host HOST	Exact outbound host allowlist; repeatable
--callback-signing-seed-hex HEX	Hex-encoded 32-byte Ed25519 seed
--a2a-push-encryption-key-hex HEX	Hex-encoded 32-byte key for push credentials at rest
--callback-allow-http	Permit plaintext HTTP callback targets
--callback-allow-private-networks	Permit private and loopback callback destinations

An allowlist or A2A push encryption key requires a callback signing seed. The two allow switches weaken the default SSRF and transport boundary and should be limited to an explicitly owned isolated network.

MCP Compatibility

Option	Purpose
--mcp-stdio	Serve newline-delimited MCP on stdin/stdout instead of HTTP
--mcp-bearer-token TOKEN	Static token for MCP Streamable HTTP
--mcp-resource URI	Protected-resource identifier
--mcp-authorization-server ISSUER	Advertised authorization server; repeatable
--mcp-scope SCOPE	Advertised supported scope; repeatable
--mcp-required-scope SCOPE	Scope required to establish a session; repeatable
--mcp-introspection-url HTTPS_URL	RFC 7662 token introspection endpoint
--mcp-introspection-issuer ISSUER	Trusted issuer represented by introspection
--mcp-introspection-client-id CLIENT_ID	Introspection client id
--mcp-introspection-client-secret-file FILE	Owner-only introspection secret file
--mcp-introspection-allow-loopback-http	Permit a loopback plaintext introspection fixture
--mcp-resource-documentation URL	Human-readable protected-resource documentation
--mcp-allowed-origin ORIGIN	Allowed browser origin; repeatable
--mcp-principal PRINCIPAL_ID	AIP principal established for MCP; default service:aipd:mcp-edge
--mcp-principal-scope SCOPE	Scope granted to the MCP principal; repeatable

Static bearer authentication is suitable for an isolated endpoint. OAuth deployments should publish resource metadata and verify active token issuer, audience, subject, expiration, and required scopes. The loopback HTTP exception is only for an owned qualification fixture.

Hermes Agent Connector

Option	Purpose
--hermes-endpoint ID=URL	Register a Hermes API-server instance; repeatable
--hermes-api-key TOKEN	API-server bearer token shared by configured endpoints
--hermes-operator-delegation-enabled	Register governed Hermes operator principals as delegation routes
--hermes-operator-model MODEL	Model route used by operator runs
--hermes-operator-instructions-file FILE	Trusted system instructions
--hermes-operator-timeout-ms MS	Maximum operator observation duration
--hermes-operator-poll-ms MS	Durable recovery polling interval
--hermes-operator-max-events COUNT	Maximum accepted structured events
--hermes-operator-max-input-bytes BYTES	Maximum serialized AIP input
--hermes-operator-max-delegation-depth COUNT	Maximum accepted delegation depth
--hermes-operator-claim-ttl-ms MS	Exclusive start and approval-command claim TTL
--hermes-operator-cancel-grace-ms MS	Cancellation reconciliation grace period
--hermes-operator-capability-prefix PREFIX	Allowed delegated capability prefix; repeatable
--hermes-operator-approval-exempt-capability-prefix PREFIX	Explicit unattended prefix; repeatable
--hermes-operator-scope-prefix PREFIX	Allowed delegated scope prefix; repeatable

Operator mode requires explicit instructions, model, allowlists, and delegation enablement. An approval-exempt prefix is a policy grant, not a convenience switch. See Hermes Agent Connector.

Cal.diy Connector

Option	Purpose
--cal-diy-base-url HTTPS_URL	Self-hosted API base URL
--cal-diy-account-id ACCOUNT_ID	Deployment-local account id used for idempotency scope
--cal-diy-tenant-account TENANT_ID=ACCOUNT_ID	Trusted tenant route; repeatable
--cal-diy-credential-file HANDLE=FILE	Owner-only routed credential; repeatable
--cal-diy-max-response-bytes BYTES	Provider response memory bound
--cal-diy-bearer-token-file FILE	API key or access-token file
--cal-diy-oauth-client-id CLIENT_ID	OAuth client id
--cal-diy-oauth-client-secret-file FILE	OAuth client-secret file
--cal-diy-webhook-secret-file REF=FILE	Signed webhook secret selector; repeatable
--cal-diy-webhook-replay-file FILE	Durable single-process replay-observation file
--cal-diy-webhook-subscriber-prefix HTTPS_URL_PREFIX	Allowed deployment-owned ingress prefix; repeatable

Bearer and OAuth client authentication are mutually exclusive. Tenant routing requires the trusted identity directory and a credential file for every routed handle. Outbound webhook registration fails closed unless the target matches an allowed HTTPS prefix and configured secret selector.

See the Cal.diy Connector.

File Security

Secret and trust files must be regular, bounded, owner-controlled files. Mount them read-only and reject group- or world-writable permissions. Do not use symlinks for secret inputs accepted by the daemon.

Rotate files through the deployment control plane, then restart or reload only according to the owning component’s contract. Record the revision used for qualification.

Validate before Serving Traffic

Print the composed manifest without starting the listener:

aipd \
  --service-id agent:aipd:validation \
  --storage-dir .aipd-validation \
  --print-manifest

This validates startup composition, not external capacity, credentials, or provider semantics. A production rollout still needs readiness and the applicable qualification campaign.