Appendix: Environment Variables
The normalized 32-entry installed RC.6 environment contract, with explicit ownership, setting, secret, and process-boundary behavior.
Audience: Developers, operators, integrators, and release engineers
What this appendix covers#
This is the complete installed process-environment contract for the current ait-native 1.0.0-rc.6 family: ait, Agent workers, ait-server, and ait-runner. It contains 32 normalized names or bounded families. The entries come from the three machine-readable runtime registries, not from a search for every AIT_ token in source files.
The contract stays in one document. Each row says which component owns the value, who sets it, whether it is secret, and what it changes.
- User and operator values may be placed in the launched process environment. Explicit command options still win where a command exposes the same choice.
- AIT-injected values cross a managed child-process boundary. A user should not set them to redirect another Task or CI attempt.
- Automation values belong only to the named supported build or release boundary.
- A secret belongs in a service or CI secret store. Do not commit it, print it, or place it in retained command-line history.
Neither ait-server nor ait-runner automatically loads a project .env file. A shell, service manager, container runtime, or the Agent supervisor must place configured values into the process environment.
Registry accounting#
| Registry | Published accounting |
|---|---|
ait.environment-contract/v1 | 24 ait-core, CLI, Agent, and release-boundary entries. |
ait.server.environment-contract/v1 | 7 server entries. AIT_NATIVE_SERVER_DATA and AIT_PERFETTO_TRACE are already owned by core, so the server contributes 5 new names. |
ait.runner.environment-contract/v1 | 4 runner entries. Its external-repository family includes core's concrete AIT_EXTERNAL_CORE_REPO_ROOT input, so the runner contributes 3 additional normalized names. |
| Published total | 32 unique names or bounded families. |
Runtime, repository, and identity#
| Name | Owner, setting, secret, and behavior |
|---|---|
AIT_NATIVE_ACTOR | ait-core · user or operator · not secret. Authorship identity recorded with local provenance and remote requests. |
AIT_NATIVE_SERVER_DATA | ait-core and ait-server · operator · not secret. Durable server authority root used when ait-server --data is not supplied and by server-aware core operations. Keep it on durable storage. |
AIT_REPO_ROOT | ait-cli · user or supervisor · not secret. Explicit repository root used for process discovery. Prefer entering the repository normally; use this only when the caller cannot establish the working directory. |
AIT_RUNTIME_DATA | ait-core · operator · not secret. Runtime-data root shared by local diagnostics, Snapshot metadata, status caches, and server-aware operations. |
AIT_SERVER_TOKEN | ait-runner · operator · secret. Optional bearer credential sent by the runner to the configured ait-server endpoint. Server URL and worker identity remain explicit runner command options. |
Agent worker and integration credentials#
Agent workers select a typed worker manifest first. These environment values supply the bounded worker bootstrap and credentials that cannot safely be embedded in ordinary repository content.
| Name | Owner, setting, secret, and behavior |
|---|---|
AIT_AGENT_CONFIG_PATH | ait-agent-worker · user or supervisor · not secret. Path to the typed Agent worker manifest. The ordinary repository default is .ait/agent-workers.json. |
AIT_DISCORD_APPLICATION_ID | ait-agent-worker · operator · not secret. Discord application identity for the selected worker. |
AIT_DISCORD_BOT_TOKEN | ait-agent-worker · operator · secret. Discord bot credential for the selected worker. |
AIT_DISCORD_PUBLIC_KEY | ait-agent-worker · operator · not secret. Discord public verification key used to authenticate interaction requests. |
AIT_LINE_CHANNEL_ACCESS_TOKEN | ait-agent-worker · operator · secret. LINE channel access credential for the selected worker. |
AIT_LINE_CHANNEL_SECRET | ait-agent-worker · operator · secret. LINE request-verification secret for the selected worker. |
AIT_OPENAI_API_KEY | ait-agent-worker · operator · secret. OpenAI credential made available to the selected worker when that worker uses the OpenAI boundary. |
AIT_SLACK_APP_TOKEN | ait-agent-worker · operator · secret. Slack app-level credential for the selected worker. |
AIT_SLACK_SIGNING_SECRET | ait-agent-worker · operator · secret. Slack request-signature verification secret. |
AIT_TELEGRAM_BOT_TOKEN | ait-agent-worker · operator · secret. Telegram bot credential for the selected worker. |
AIT_TELEGRAM_OPENAI_API_KEY | ait-agent-worker · operator · secret. Telegram-scoped OpenAI credential when that worker uses a separate key. |
AIT_TELEGRAM_WEBHOOK_SECRET | ait-agent-worker · operator · secret. Telegram webhook verification secret. |
Server CI memory admission#
These three variables belong only to server-owned CI admission. Task-worktree RAM placement is repository configuration under task_worktree.memory_root, not process-environment configuration. Its typed fields, macOS 8 GiB default, read-only diagnostic, and persistent-disk fallback rules are documented in Parallel Task Isolation.
| Name | Owner, setting, secret, and behavior |
|---|---|
AIT_NATIVE_SERVER_CI_RAM_MIN_AVAILABLE_BYTES | ait-server · operator · not secret. Optional exact free-byte floor applied when admitting server CI onto the validated RAM root. Unset adds no floor beyond mount validation. |
AIT_NATIVE_SERVER_CI_RAM_RECLAIM_TARGET_BYTES | ait-server · operator · not secret. Optional post-reclamation free-byte target. The effective target is never lower than the admission floor. |
AIT_NATIVE_SERVER_CI_RAM_ROOT | ait-server · operator · not secret. Absolute, validated memory-backed host root for isolated server CI work. It must remain outside persistent server authority. |
Storage and remote-operation tuning#
These are advanced bounded controls. Invalid values use the documented fallback or fail validation at the owning boundary; they do not rewrite existing stored objects.
| Name | Owner, setting, secret, and behavior |
|---|---|
AIT_OBJECT_PACK_CHUNK_MIB | ait-server · operator · not secret. Positive object-pack write chunk size in MiB. Unset, invalid, or zero uses 8 MiB. |
AIT_REMOTE_MUTATION_RESPONSE_DEADLINE_SECONDS | ait-core · operator · not secret. Remote mutation response deadline. Ordinary mutations default to 10 seconds and Task Land defaults to 30 seconds; a value at or below zero disables only this response deadline. |
AIT_REMOTE_MUTATION_SETTLE_POLL_SECONDS | ait-core · operator · not secret. Reconciliation polling interval after a remote mutation. Default 0.25 seconds. |
AIT_REMOTE_MUTATION_SETTLE_WINDOW_SECONDS | ait-core · operator · not secret. Post-mutation reconciliation window. Default 5 seconds. |
AIT_TREE_PACK_CHUNK_MIB | ait-server · operator · not secret. Positive Tree-pack write chunk size in MiB. Unset, invalid, or zero uses 8 MiB. |
Managed process boundaries#
The values below are observable in child processes but are not ordinary configuration. AIT overwrites them with the exact paths or ownership token for the active operation.
| Name | Owner, setting, secret, and behavior |
|---|---|
AIT_EXTERNAL_<NAME>_REPO_ROOT | ait-runner and ait-core · AIT-injected family · not secret. Runner-created path to one locked external repository. <NAME> is nonempty normalized uppercase ASCII with digits or underscores; the core diagnostic uses the concrete AIT_EXTERNAL_CORE_REPO_ROOT member. |
AIT_RUNNER_ATTEMPT_ROOT | ait-runner · AIT-injected · not secret. Exact runner-owned root of the current execution attempt. The runner's parent location is selected with --attempt-root; ambient values cannot redirect a child attempt. |
AIT_RUNNER_WORKSPACE | ait-runner · AIT-injected · not secret. Exact materialized workspace for the current execution. |
AIT_WORKSPACE_LOCK_OWNER_TOKEN | ait-cli · AIT-injected · secret. Opaque token propagated only to validated nested commands sharing the current workspace lock. Do not synthesize or log it. |
Diagnostics and release-boundary automation#
| Name | Owner, setting, secret, and behavior |
|---|---|
AIT_JSON_MODE | ait-cli · user · not secret. Case-insensitive debug enables the supported extended JSON diagnostic projection. Other values leave normal JSON output unchanged. |
AIT_PERFETTO_TRACE | ait-core and ait-server · user or operator · not secret. Nonempty output path for opt-in Perfetto trace capture in a tracing-enabled process. |
AIT_SHARED_CARGO_TARGET_DIR | ait-release · automation · not secret. Explicit shared Cargo target directory used by the supported native release smoke boundary. It is not a general runtime storage selector. |
What is deliberately excluded#
Release-manifest placeholders are argv template tokens resolved by the release adapter, not environment inputs. Workflow-local CI env: aliases, test fixtures, failure-injection controls, generated IDs, report labels, and values owned only by repository build or deployment scripts are likewise outside the installed runtime contract. They should be explained next to the workflow or script that owns them, not presented as settings users must understand.
This scope rule keeps the appendix complete without turning every source token into a public configuration promise.