Configuration Reference
This page is the single reference for agent-folder configuration shapes and
every ASSEMBLY_LINE_* environment variable. The guides explain when and why to use
these settings:
- Building Agents for the folder shape and authoring flow.
- Customizing Agents for context, engine routing, hardening, and channels.
- Runtime And Deployment for the runtime lifecycle and production knobs.
- Adapters for provider helpers and provider-specific env (Slack, Postgres, S3, sandboxes, ...).
All define* helpers are identity functions from @assemblyline-agents/core: they give
you type checking, and the compiler reads the declarations statically from the
TypeScript AST. Manifest-affecting values must be statically readable; the
compiler never executes config code.
Contents:
defineAgent(agent.ts)defineSubagent(subagents/<name>/agent.ts)defineGateway(gateway.ts) andadapter()defineInstrumentation(instrumentation.ts)defineContext/defaultContext(context.ts)- Per-file contracts the compiler validates
- Environment variable reference, starting with the alphabetical index of every variable.
defineAgent (agent.ts)
agent.ts default-exports defineAgent({ ... }). model is the only
required field.
| Field | Type | Required | Meaning |
|---|---|---|---|
model | string | yes | provider/model spec. The prefix decides provider auth: for example, openai/* needs OPENAI_API_KEY, while the preview openai-codex/* route uses the Codex CLI's active ChatGPT or API-key session. assembly-line models lists the local catalog. |
id | string | no | Stable logical agent identity. Keeps learned skills, usage attribution, and durable state attached to the agent across revisions and redeploys. |
reasoning | "off" | "minimal" | "low" | "medium" | "high" | "xhigh" | no | Reasoning effort. The runtime defaults to "medium" when omitted. |
name | string | no | Display name. |
description | string | no | Short description recorded in the manifest. |
context | ContextPolicy | no | Context policy from defaultContext(...) or defineContext(...). The compiler stamps defaultContext() when omitted. |
defaultTools | string[] | no | Authored tool names that are visible up front instead of deferred behind tool_search. |
outputSchema | JsonSchema | no | JSON Schema for the final answer. The schema must be statically readable; the runtime validates the final response, performs bounded corrective retries, and exposes the parsed value as RunAgentResult.output. |
maxIterations | positive integer | no | Agent-loop iteration budget for one active execution. Overrides ASSEMBLY_LINE_MAX_MODEL_ITERATIONS; a cap hit fails the run instead of delivering a partial response. |
selfImprovement | object | no | Skill authoring config; see below. |
dynamicAutomations | object | no | Runtime-created automation config; see below. |
dynamicConnections | object | no | Runtime-created connection config; see below. |
metadata | JSON object | no | Free-form metadata recorded in the manifest. |
Pi is the default primary engine; agent.ts has no harness: slot (declaring
one fails validation with harness-not-configurable). The Node host's
openai-codex/* route is selected by model prefix rather than a public harness
field. Subagents use Pi as well; they do not expose a harness slot.
Sub-config blocks (all fields optional):
| Block | Field | Default | Meaning |
|---|---|---|---|
selfImprovement | writable | true | Agent may author and edit its own skills under /skills. |
selfImprovement | writeApproval | false | Skill writes require approval. |
selfImprovement | externalDirs | - | Extra directories treated as skill sources. |
dynamicAutomations | dynamic | true | Agent may create/manage time-based automations through ctx.automationManager. |
dynamicAutomations | approval | false | Dynamic automation changes require approval. |
dynamicConnections | dynamic | false | Agent may persist runtime-provided MCP/OpenAPI/HTTP connections. |
dynamicConnections | approval | true | Saving a dynamic connection requires approval. |
dynamicConnections | allowedHosts | [] | Host allowlist; required non-empty when dynamic is enabled. |
defineSubagent (subagents/<name>/agent.ts)
SubagentDefinition accepts every optional AgentDefinition field plus:
| Field | Type | Meaning |
|---|---|---|
model | string? | Optional (unlike agents). Defaults to the primary agent's model and uses the same built-in provider-prefix route, including the host's active Codex CLI authentication for openai-codex/*. |
workspace | AdapterDefinition? | Sandbox/workspace adapter for the subagent (compiled with role sandbox). |
connections | string[]? | Connection names the subagent may use. |
The compiler also records what the subagent inherits: skills, tools
(declared tools plus defaultTools), and context (context: true).
All subagents run through Pi. harness and the retired engineConnection
field fail validation so child execution stays on one durable code path.
defineGateway (gateway.ts) and adapter()
Every gateway slot is an optional AdapterDefinition. Compiler defaults are
all adapter("local") except runtime, which defaults to adapter("node").
| Slot | Chooses | Default |
|---|---|---|
deploy | Where the compiled runtime service runs. | adapter("local") |
runtime | Runtime host. | adapter("node") |
state | Durable state adapter. | adapter("local") |
blob | Blob storage adapter. | adapter("local") |
sandbox | Default sandbox adapter. | adapter("local") |
scheduler | Where the schedule clock lives (local, gateway, postgres). | adapter("local") |
Telemetry is not a gateway slot — configure it in instrumentation.ts (see
defineInstrumentation).
adapter() builds an AdapterDefinition:
adapter(kind: string, options?: JsonObject, extras?: { package?: string })
kind: adapter kind, e.g."postgres","railway","pi".options: JSON options merged with host-supplied extras at construction.extras.package: npm plugin package name that exportsopeneveProvider; it is stored aspackageNameon the definition. This is how community plugin providers plug in with zero core edits:
state: adapter("neon-state", { pool: 4 }, { package: "@acme/openeve-neon" })
AdapterRole values: deploy, runtime, state, blob, sandbox,
scheduler, channel, and connection. A subagent workspace adapter
compiles with role sandbox.
See Plugins for the extension model,
Authoring Plugin Providers for the provider contract,
and Adapters for the built-in matrix.
Runtime state facets
RuntimeOptions.state may be a full StateAdapter or a StateStores object.
runs is required. Optional facets are conversations, schedules, files,
usage, sandboxSessions, memory, and settings. The settings
(RuntimeSettingsStore) facet holds stable-agent operator settings and their
control-plane audit events. Omitted facets use in-memory fallbacks and produce
one state.degraded warning; in particular, an ingress kill switch backed by
the fallback does not survive process restart. File and Postgres state adapters
implement the durable settings facet.
defineInstrumentation (instrumentation.ts)
agent/instrumentation.ts is the single home for telemetry. It is auto-discovered
and run once at startup; its presence enables telemetry (no separate toggle). Wire
a sink in the setup callback and set capture preferences as sibling fields.
| Field | Type | Meaning |
|---|---|---|
serviceName | string? | service.name on spans; defaults to the agent name. |
functionId | string? | Overrides the function id on spans. |
setup | (ctx) => sink | void | Runs before the first turn with { agentName, manifest, env }; return a TelemetrySink to export spans. |
recordInputs / recordOutputs | boolean? | Legacy capture flags. Default false. |
captureContent | ContentCaptureLevel | ContentCapturePolicy? | Content detail (see below). Default usage. |
@assemblyline-agents/otlp supplies createOtlpSink(options) / createOtlpSinkFromEnv(env)
for the setup callback; see
Customizing Agents → Observability for the full
example and the Langfuse recipe.
Capture detail (captureContent). Controls how much of each model call is
recorded, so a developer decides per environment how verbose logging is:
| Level | Records |
|---|---|
off | No span content. |
usage (default) | Token usage, cost, model, provider, finish reason, tool-call spans. No message bodies. |
content | Adds prompt + completion text and tool input/output, truncated and key-redacted. |
full | Same coverage as content with truncation relaxed; redaction stays on unless explicitly disabled. |
A ContentCapturePolicy object also accepts maxChars, redact, redactKeys,
sampleRate, and includeToolIO. Prompt/completion bodies can contain secrets
and PII and increase telemetry storage/cardinality — treat full as
trusted-operator-only, and prefer usage in production.
defineContext / defaultContext (context.ts)
context.ts is optional; without it the compiler stamps defaultContext().
defaultContext(options?: JsonObject)returns{ kind: "default", name: "defaultContext", options }. Options tune the default bundle, for examplerecentHistory: { maxMessages: 12 }orfiles: { includeManifest: true }.defineContext(policy)declares a customContextPolicy:
| Field | Type | Meaning |
|---|---|---|
kind | string | Policy kind, e.g. "custom". |
name | string? | Policy name recorded in the manifest. |
options | JSON object? | Policy options. |
extends | ContextPolicy? | Base policy, usually defaultContext(...). |
sourcePath | string? | Set by the compiler for attribution. |
transcript options
options.transcript tunes conversation transcript resume and trimming
(see Framework — conversation transcript resume):
| Option | Default | Meaning |
|---|---|---|
resume | true | Resume conversation follow-ups from the stored harness transcript; false always rebuilds from flattened recent history. |
reserveTokens | 16384 | Tokens reserved below the model context window before compaction triggers. |
keepRecentTokens | 20000 | Approximate recent-transcript tokens kept verbatim through trimming and compaction. |
toolResultCapChars | 2000 | Character cap applied to tool-result bodies outside the recent tail at resume time. |
Per-File Contracts The Compiler Validates
Allowed top-level entries in an agent folder: instructions.md, agent.ts,
context.ts, gateway.ts, skills/, tools/, channels/, automations/,
automation-handlers/, connections/, evals/, sandbox/, subagents/,
hooks/, resolvers.ts, instrumentation.ts. Anything else produces an
unknown-top-level warning.
evals/**/*.json holds golden eval cases for assembly-line eval (discovered
recursively; evals/evaluators/ holds custom evaluator modules); see
Evals.
tools/*.ts
The filename is the tool name ([A-Za-z0-9_-], unique). The default export
must declare description and inputSchema (errors: invalid-tool-name,
duplicate-tool-name, missing-tool-export, missing-tool-description,
missing-tool-schema). Optional fields: outputSchema, needsApproval,
toModelOutput, defaultEnabled, sideEffect
("none" | "idempotent" | "external", the tool's declared side-effect class;
approvalRequired() stamps external and approvalNever() stamps none on
the approval policy), and a capability block with visibility
(auto/always/deferred/skill/hidden) and execution
(auto/direct/sandbox/both) plus namespace, tags[], aliases[].
auto (the implicit default) uses inference: visibility is inferred as
always for defaultTools members and deferred otherwise unless declared.
A file named after a built-in harness tool overrides that built-in (the
description/schema checks are skipped so overrides can spread
builtInToolDefaults from @assemblyline-agents/runtime), and it keeps the built-in
slot's always-on visibility. A disableTool() default export (from
@assemblyline-agents/core) removes the built-in of that name; a filename matching no
built-in raises invalid-disable-tool. See
Customizing Agents.
hooks/*.ts
Observe-only event subscribers. The default export must declare an events
map keyed by event type (* matches every event); errors:
missing-hook-export, missing-hook-events. Handlers fire after each durable
event is persisted, cannot alter execution, and thrown errors are logged and
swallowed. See
Customizing Agents.
resolvers.ts
Per-run capability resolver. The default export is a function
(defineRunResolver) returning { model?, instructions?, defaultTools? } or
null; error: missing-resolver-export. The declaration is recorded as a
run.capabilities_resolved event before it is applied. See
Customizing Agents.
skills/<name>/SKILL.md
Markdown with YAML frontmatter. allowed-tools entries must name an authored
tool or a core tool (read, write, edit, delete, list, grep,
bash, ask_question, spawn_subagent, load_skill, tool_search,
tool_describe, tool_call), else unknown-skill-tool. Frontmatter
description, tags, and aliases feed the skill catalog.
channels/*.ts
Fields: transport (http/local/webhook/queue), route, methods[],
requiredEnv[], description, connection, metadata, and ingress.
Custom HTTP channels must declare a route (missing-channel-route), and
channels with production requiredEnv must export send()
(missing-channel-send). Provider helpers (defineSlackChannel,
defineDiscordChannel, defineTelegramChannel, defineTeamsChannel,
definePhotonChannel) stamp kind, route,
requiredEnv, and ingress automatically.
ingress declares production ingress-auth secrets as any-of groups:
ingress: { requiredSecretEnv: [["MY_WEBHOOK_SECRET"], ["MY_BEARER_TOKEN"]] }
Production boot succeeds when every var in at least one group is set; dev mode
logs a warning instead. The compiler stamps the declaration into
CompiledChannel.metadata.ingress.
automations/*.ts
defineAutomation() requires a trigger. Schedule triggers declare
{ type: "schedule", cron, timezone? } and require a top-level
idempotencyKey. Event triggers declare
{ type: "event", source, event, connection?, filter? }; filter is a
recursive JSON subset matched against the normalized provider payload.
Optional fields are description, message, target, lifecycle,
enabled, and metadata.
automation-handlers/*.ts
The filename is the lifecycle handler name.
defineAutomationHandler({ description?, prepare?(ctx), finalize?(ctx, result), metadata? }). A handler named in lifecycle.handler runs around
either a schedule- or event-triggered model turn.
The legacy schedules/ and triggers/ contracts remain accepted with
deprecation warnings.
connections/*.ts
Protocol is inferred from the helper (defineMcpClientConnection,
defineMcpStdioConnection, or defineMcpRelayConnection -> mcp,
defineOpenAPIConnection -> openapi, defineHttpApiConnection -> http,
defineSandboxCliConnection -> cli, otherwise declaration). Fields: subject
(user/workspace/installation/environment, default user), provider,
scopes[], capabilities[], binding (adapter), url/baseUrl/spec,
description, required (default true). Provider helpers
(defineGitHubConnection, defineTeamsConnection, defineLiveKitConnection)
stamp provider, binding, and subject.
Live MCP, OpenAPI, HTTP, and sandbox CLI definitions require access. The generic form is
{ read: { tools: string[] }, write: false | { tools: string[], approval } }.
Tool entries accept exact names, * globs, or regex: patterns. A remote tool
that matches neither class is hidden; a write match wins over a read match.
Official provider helpers expose the simpler author choice
{ read: true, write: false | { approval } } and apply their packaged tool
classifiers. CLI-generated provider files default to write: false.
MCP definitions discriminate on transport. The existing HTTP shape keeps
url and may omit transport (equivalent to "http"). The stdio shape uses
transport: "stdio", command, optional args, cwd, and string-valued
env overrides. The relay shape uses transport: "relay", an HTTPS url, a
fixed credentialEnv, and an optional bounded timeoutMs. Relay and stdio
definitions are static-file-only; dynamic connection definitions are URL-only
and reject process-backed or device-relay transports.
Sandbox CLI definitions use transport: "sandbox", a trusted command, and
reviewed static tool builders. The runtime hydrates declared logical paths and
executes each built argument inside the active run sandbox, not the gateway
host. Dynamic connections cannot select this transport.
Connection plugins may use MCP, OpenAPI, HTTP, or sandbox CLI. OpenAPI helpers can package a
stable remote specification and base URL, while keeping the generated access
policy visible in connections/*.ts. OAuth definitions accept tokenType when
a provider requires an authorization scheme other than Bearer; SoundCloud,
for example, uses tokenType: "OAuth".
Process-backed media helpers can package their own stdio MCP bridge while leaving external executables as trusted host dependencies. The FFmpeg and Remotion helpers fix the Node bridge path, child executable/prefix arguments, working directory, and workspace root in source. Their remote tool schemas do not accept arbitrary shell commands or CLI flags, and output paths cannot escape the configured root.
Platform-specific connection plugins may publish hostRequirements metadata
with deployTargets, Node platforms, and an actionable message. These
constraints are compiler-owned metadata rather than model input. Validation
warns when the default gateway target is incompatible, deployment planning
marks the constraint as a required missing item, and the runtime checks the
platform before loading the connection definition. Peekaboo uses
deployTargets: ["local"] and platforms: ["darwin"].
sandbox/*.ts
defineSandbox({ adapter, image?, workingDirectory?, env?, snapshot? }) or a
provider helper (dockerSandbox(), e2bSandbox(), modalSandbox(), ...).
snapshot is { mode: "never" | "manual" | "on_failure" | "always", retainLast?, reason? } and defaults to never.
workingDirectory defaults to /workspace and may only be /workspace.
Hosted adapters establish it as a physical shell directory and validate it
after create/connect/wake; arbitrary aliases are rejected because they cannot
make absolute paths inside shell commands portable. /runtime is retired and
rejected. The Local adapter is a trusted dev/test emulation over a temporary
host directory; use Docker for exact local namespace parity.
instrumentation.ts
defineInstrumentation({ serviceName?, recordInputs?, recordOutputs?, captureContent?, functionId?, metadata?, setup? }). If setup() returns a telemetry
sink, the runtime uses it unless the host supplied telemetry directly.
Community plugin provider stamping
When gateway slots or subagent harness/workspace definitions carry a
packageName that is not in the built-in registry, the
compiler imports that package from the agent root, reads
openeveProvider.providers[].metadata, records it in
manifest.providerMetadata, and emits the provider's requiredEnv and
setup entries into manifest.preflight. Unresolvable packages produce a
provider-package-unresolved warning (never a build failure) and keep a
generic role-based requirement; the Node host re-validates at boot.
Environment Variable Reference
Every ASSEMBLY_LINE_* variable read by the packages in this repo. Boolean
variables accept true/1 and false/0 unless noted. Provider-specific
non-ASSEMBLY_LINE_ env (API keys, DATABASE_URL, SLACK_*, ...) is documented in
Adapters and Runtime And Deployment.
Every ASSEMBLY_LINE_* variable also accepts its legacy OPENEVE_* spelling
during the rename compatibility window. The new name wins, setting both to
the same value is fine, and conflicting values fail at startup.
Alphabetical index
Every variable in this reference, with the section that documents it.
ASSEMBLY_LINE_ARTIFACT_ROOT, ASSEMBLY_LINE_AGENT_REVISION, and
ASSEMBLY_LINE_MIGRATION_FILES are deploy-time outputs, not knobs; see
Build, deploy, and migrations.
Server and auth (@assemblyline-agents/node)
| Variable | Default | Effect |
|---|---|---|
ASSEMBLY_LINE_ADMIN_TOKEN | unset | Bearer token for control-plane routes (/manifest, /routes, /runs*). Production boot fails without this or a host auth policy. |
ASSEMBLY_LINE_ENABLE_API_RUNS | disabled | true/1 enables authenticated POST /runs in production (always on in dev mode). |
ASSEMBLY_LINE_ENABLE_EVAL_RUNS | disabled | true/1 lets authenticated POST /runs accept the eval block (tool stubs, approval auto-resolve, record-only delivery). Advertised as the eval-runs capability on /healthz. Always on in dev mode; enable on test environments, not production. |
ASSEMBLY_LINE_SCHEDULER_SECRET | unset | Shared secret for /assembly-line/automations/tick and its deprecated scheduler alias (Authorization: Bearer or x-assembly-line-scheduler-secret, compared constant-time). Unset means dev-mode-only tick. |
ASSEMBLY_LINE_HTTP_MAX_BODY_BYTES | 10485760 (10 MiB) | Max HTTP request body size before parsing. |
ASSEMBLY_LINE_PUBLIC_URL | http://localhost | Public base URL; also the fallback for connection callbacks. |
ASSEMBLY_LINE_CONNECTION_CALLBACK_BASE_URL | falls back to ASSEMBLY_LINE_PUBLIC_URL | Base URL for OAuth/connection authorization callbacks. |
Usage accounting
| Variable | Default | Effect |
|---|---|---|
ASSEMBLY_LINE_OPENAI_ADMIN_KEY / OPENAI_ADMIN_KEY | unset | OpenAI organization Admin API key used only by authenticated POST /usage/reconcile. Never stored in the ledger. |
OPENROUTER_MANAGEMENT_KEY | unset | Imports OpenRouter completed-day activity control totals. |
ASSEMBLY_LINE_USAGE_RECONCILIATION_LAG_HOURS | 48 | OpenAI provider-settlement delay excluded from control-total imports. |
ASSEMBLY_LINE_OPENAI_USAGE_PROJECT_IDS | all accessible | Comma-separated OpenAI project filter for provider usage and cost totals. |
ASSEMBLY_LINE_OPENAI_USAGE_API_KEY_IDS | all accessible | Comma-separated OpenAI API-key ID filter for token-usage controls. OpenAI's Costs API does not expose this filter. |
ASSEMBLY_LINE_OPENAI_AGENT_BY_PROJECT_ID | unset | JSON object mapping a dedicated OpenAI project ID to a stable Assembly Line agent ID. This is the finest supported attribution for OpenAI cash controls. |
ASSEMBLY_LINE_OPENAI_AGENT_BY_API_KEY_ID | unset | JSON object mapping a dedicated OpenAI API-key ID to a stable Assembly Line agent ID for token-usage controls. API-key mapping wins over project mapping where the provider result contains both. |
ASSEMBLY_LINE_OPENROUTER_API_KEY_HASH | unset | OpenRouter activity filter for one API-key hash. |
ASSEMBLY_LINE_OPENROUTER_CONTROL_AGENT_ID | unset | Agent attribution applied to activity totals only when the configured activity filter is dedicated to that agent. |
Usage accounting is observational: it does not reserve quota, reject requests,
or estimate missing token/cash values. Provider transactions are stored in
exact integer micro-dollars when the provider reports cash; otherwise cash is
null with unavailable provenance. control_total rows are provider
aggregate evidence and are excluded from the default transaction view so they
cannot double count run receipts.
Concurrency and rate limiting
| Variable | Default | Effect |
|---|---|---|
ASSEMBLY_LINE_MAX_CONCURRENT_RUNS | unlimited (16 in production Node hosts when unset) | Max simultaneously executing brand-new runs. Accepted provider turns wait durably in their conversation mailbox; excess direct runs are rejected with RunCapacityError / HTTP 429. Resumes never queue. |
ASSEMBLY_LINE_MAX_QUEUED_RUNS | 0 | Direct brand-new runs allowed to wait in the in-process semaphore before rejection. Accepted provider turns use the durable conversation mailbox instead. |
ASSEMBLY_LINE_INGRESS_RATE_LIMIT | off | Provider-channel token bucket as capacity/refillPerSecond (e.g. 60/10). |
ASSEMBLY_LINE_RUNS_RATE_LIMIT | off | POST /runs token bucket in the same form. Also seeds the run-resume and run-control buckets unless those are configured separately through NodeRuntimeServerOptions.rateLimit. |
ASSEMBLY_LINE_TRUST_PROXY | off | true (exactly) trusts the first X-Forwarded-For hop as the client address for rate-limit keying. Set it when the host sits behind a reverse proxy or load balancer; without it, all proxied traffic shares one rate-limit bucket keyed by the proxy's address. |
Graceful shutdown
| Variable | Default | Effect |
|---|---|---|
ASSEMBLY_LINE_SHUTDOWN_TIMEOUT_MS | 30000 | Max wait for in-flight runs to drain during graceful shutdown. |
ASSEMBLY_LINE_SIGNAL_HANDLERS | on | false/0 prevents listenNodeRuntime from installing SIGTERM/SIGINT graceful-shutdown handlers. |
OTLP telemetry (@assemblyline-agents/otlp)
| Variable | Default | Effect |
|---|---|---|
OTEL_EXPORTER_OTLP_ENDPOINT | required for createOtlpSinkFromEnv | OTLP/HTTP endpoint. |
OTEL_EXPORTER_OTLP_HEADERS | unset | Comma-separated OTLP headers such as Authorization=Basic .... |
OTEL_SERVICE_NAME | instrumentation service name | Service name override for exported spans. |
OTEL_EXPORTER_OTLP_TIMEOUT | sink default | Per-export timeout in milliseconds. |
ASSEMBLY_LINE_OTLP_BATCH_MAX | sink default | Max spans batched before an OTLP flush. |
ASSEMBLY_LINE_OTLP_FLUSH_MS | sink default | Flush interval for the OTLP sink. |
Durability workers and recovery
| Variable | Default | Effect |
|---|---|---|
ASSEMBLY_LINE_DELIVERY_WORKER | on | false/0 disables the delivery queue worker. |
ASSEMBLY_LINE_SANDBOX_SYNC_WORKER | on | false/0 disables the sandbox-sync worker. |
ASSEMBLY_LINE_CONVERSATION_TURN_WORKER | on | false/0 disables periodic mailbox recovery/polling. Newly accepted and terminally settled turns still request an immediate local drain. |
ASSEMBLY_LINE_RUN_RECOVERY | on | false/0 disables boot recovery and the periodic orphan sweep. |
ASSEMBLY_LINE_RUN_HEARTBEAT_MS | 30000 | How often executing runs bump updatedAt to stay out of the orphan sweep. |
ASSEMBLY_LINE_RUN_RECOVERY_INTERVAL_MS | 60000 | Orphan sweep interval; runs are only candidates after max(5min, 4x heartbeat) staleness. |
ASSEMBLY_LINE_MAX_RUN_DURATION_MS | 3600000 | Wall-clock cap per active run execution segment, enforced by the heartbeat: on expiry the in-flight model request is aborted and the run fails with reason run.max_duration_exceeded. 0 disables. Paused (approval/input) runs do not consume budget. |
ASSEMBLY_LINE_SCHEDULE_MAX_FAILURES | 5 | Consecutive dynamic-schedule failures before the schedule is auto-disabled (escalating backoff between attempts: 5 min doubling, capped at 6 h). |
Delivery queue
| Variable | Default | Effect |
|---|---|---|
ASSEMBLY_LINE_DELIVERY_RETRY_ATTEMPTS | 2 | In-process send attempts before deferring to the durable queue. |
ASSEMBLY_LINE_DELIVERY_RETRY_MIN_MS | 250 | Min backoff between in-process retries. |
ASSEMBLY_LINE_DELIVERY_RETRY_MAX_MS | 5000 | Max backoff between in-process retries. |
ASSEMBLY_LINE_DELIVERY_QUEUE_LEASE_MS | 60000 | Lease duration for a sending delivery before it is requeued. The inline sender's own lease is max(this, 120000) so it outlives the in-process retry envelope. |
ASSEMBLY_LINE_DELIVERY_QUEUE_BATCH_SIZE | 10 | Deliveries leased per worker tick. |
ASSEMBLY_LINE_DELIVERY_QUEUE_MAX_ATTEMPTS | 5 | Total attempts before a delivery goes terminally failed. |
ASSEMBLY_LINE_DELIVERY_QUEUE_INTERVAL_MS | 15000 | Delivery worker tick interval. |
ASSEMBLY_LINE_DELIVERY_FILE_MAX_COUNT | 10 (max 100) | Max attachment files per delivery. |
ASSEMBLY_LINE_DELIVERY_FILE_MAX_BYTES | 52428800 (50 MiB) | Max bytes per delivery file. |
Sandbox sync and hydration
| Variable | Default | Effect |
|---|---|---|
ASSEMBLY_LINE_SANDBOX_SYNC_INLINE | false | Run sandbox sync inline instead of through the background worker. |
ASSEMBLY_LINE_SANDBOX_SYNC_LEASE_MS | 300000 | Lease duration for a claimed sync job. |
ASSEMBLY_LINE_SANDBOX_SYNC_BATCH_SIZE | 10 | Sync jobs leased per worker tick. |
ASSEMBLY_LINE_SANDBOX_SYNC_MAX_ATTEMPTS | 5 | Max attempts before a job is blocked for an operator. |
ASSEMBLY_LINE_SANDBOX_SYNC_INTERVAL_MS | 30000 | Sandbox-sync worker tick interval. |
ASSEMBLY_LINE_LEGACY_FULL_SANDBOX_HYDRATION | off | true/1 forces legacy full hydration instead of minimal per-path hydration. |
Sandbox snapshots
| Variable | Default | Effect |
|---|---|---|
ASSEMBLY_LINE_SANDBOX_SNAPSHOT_MODE | unset (policy default never) | never, manual, on_failure, or always; overrides the declared snapshot policy. |
ASSEMBLY_LINE_SANDBOX_SNAPSHOT_RETAIN_LAST | unset | Snapshots to retain (non-negative integer); only read when a mode is set. |
ASSEMBLY_LINE_SANDBOX_SNAPSHOT_REASON | unset | Free-form snapshot reason label. |
Model loop, memory, and logging
| Variable | Default | Effect |
|---|---|---|
CODEX_HOME | Codex CLI default | Location of the Codex CLI config, login cache, and persisted app-server threads used by openai-codex/*. Assembly Line never reads the OAuth cache directly. |
CODEX_ACCESS_TOKEN | unset | Input for `printenv CODEX_ACCESS_TOKEN |
ASSEMBLY_LINE_CHECKPOINT_EVERY_ITERATION | true | Persist the harness continuation checkpoint after every model iteration (bounds crash loss to one in-flight model call). |
ASSEMBLY_LINE_CHECKPOINT_MAX_ACTIVE_PER_RUN_NAME | 2 | Latest overwrite-style active checkpoints retained per (run_id, name) for live/running/waiting runs. |
ASSEMBLY_LINE_CHECKPOINT_TERMINAL_TTL_MS | 604800000 (7 days) | Default TTL used by checkpoint maintenance for completed/cancelled terminal-run checkpoints. |
ASSEMBLY_LINE_CHECKPOINT_FAILED_TTL_MS | 1209600000 (14 days) | TTL used by checkpoint maintenance for failed-run checkpoints. |
ASSEMBLY_LINE_CHECKPOINT_SCHEDULED_TTL_MS | 86400000 (1 day) | Aggressive TTL used by checkpoint maintenance for terminal runs produced by schedules. |
ASSEMBLY_LINE_CHECKPOINT_BLOB_THRESHOLD_BYTES | 65536 (64 KiB) | Checkpoints at or above this serialized size are gzip-compressed into the configured blob adapter, with SQL storing a pointer/hash/size record. |
ASSEMBLY_LINE_TOOL_OUTPUT_MAX_CHARS | 8000 | Max serialized tool-output size handed back to the model before it becomes a { truncated, preview } object. |
ASSEMBLY_LINE_MAX_MODEL_ITERATIONS | 25 | Default agent-loop iteration budget. A positive integer; agent/subagent maxIterations overrides it. |
ASSEMBLY_LINE_OUTPUT_VALIDATION_MAX_RETRIES | 2 | Corrective model retries after a final response fails outputSchema. Validation retries share the active execution's iteration budget. |
ASSEMBLY_LINE_MODEL_MAX_RETRIES | 2 | Retry attempts (beyond the initial one) for a model request that fails retryably — 408/429/5xx, overload, network errors — with jittered exponential backoff. Also forwarded to provider SDK clients. Fatal errors (bad key, invalid request) never retry. |
ASSEMBLY_LINE_MODEL_TIMEOUT_MS | 600000 | HTTP request timeout per model call, forwarded to the provider SDK. |
ASSEMBLY_LINE_MODEL_MAX_RETRY_DELAY_MS | 60000 | Cap on backoff delays and server-requested (Retry-After) waits between model retries. |
ASSEMBLY_LINE_MODEL_STREAM_IDLE_TIMEOUT_MS | 300000 | Abort a model stream when no event arrives for this long (a stalled provider stream would otherwise hang the run). The aborted attempt is retried when the retry budget allows. 0 disables. |
ASSEMBLY_LINE_TOOL_TIMEOUT_MS | 600000 | Default wall-clock deadline for tool execute calls; a per-tool timeoutMs on the tool definition overrides it. The promise is raced, not cancelled. 0 disables. |
ASSEMBLY_LINE_BASH_TIMEOUT_MAX_MS | 600000 | Upper clamp on model-supplied bash timeouts. timeoutMs: 0/negative falls back to the 30 s default instead of disabling the timeout. |
ASSEMBLY_LINE_EVAL_JUDGE_MODEL | agent model | Default provider/model for eval cases with expect.judge; --judge-model takes precedence. |
ASSEMBLY_LINE_MEMORY_EMBEDDINGS_ENABLED | on only when an embedding provider is configured | Enables embedding-backed semantic memory search. |
ASSEMBLY_LINE_LOG_LEVEL | info | Structured log verbosity: debug, info, warn, or error. |
ASSEMBLY_LINE_BASH_TOOL_MODE | enabled | Core bash tool policy: enabled, approval, or disabled. Hosts can gate any tool by name with RuntimeOptions.coreToolPolicy (e.g. { write: "disabled" }). |
Attachments and resource projection
| Variable | Default | Effect |
|---|---|---|
ASSEMBLY_LINE_ATTACHMENT_MAX_COUNT | 20 (max 100) | Max inbound attachments per turn. |
ASSEMBLY_LINE_ATTACHMENT_MAX_BYTES | 52428800 (50 MiB) | Max bytes per attachment. |
ASSEMBLY_LINE_ATTACHMENT_FETCH_TIMEOUT_MS | 30000 (1s-120s) | Attachment download timeout. |
ASSEMBLY_LINE_MODEL_IMAGE_MAX_COUNT | 20 (max 100) | Max stored images hydrated as native model input per turn. |
ASSEMBLY_LINE_MODEL_IMAGE_MAX_BYTES | 20971520 (20 MiB) | Max decoded bytes for one native model image input. |
ASSEMBLY_LINE_MODEL_IMAGE_MAX_TOTAL_BYTES | 52428800 (50 MiB) | Max decoded image bytes supplied to one model turn. |
ASSEMBLY_LINE_MODEL_VIDEO_MAX_COUNT | 4 (max 20) | Max stored videos hydrated as native model input per turn. |
ASSEMBLY_LINE_MODEL_VIDEO_MAX_BYTES | 52428800 (50 MiB) | Max decoded bytes for one native model video input. |
ASSEMBLY_LINE_MODEL_VIDEO_MAX_TOTAL_BYTES | 104857600 (100 MiB) | Max decoded video bytes supplied to one model turn. |
ASSEMBLY_LINE_ZIP_MAX_FILES | 500 (max 10000) | Max entries when expanding a ZIP attachment. |
ASSEMBLY_LINE_ZIP_MAX_TOTAL_BYTES | 104857600 (100 MiB) | Max total uncompressed ZIP bytes. |
ASSEMBLY_LINE_RESOURCE_PROJECTION_MAX_FILES | 8 | Max resources projected into a sandbox per request. |
ASSEMBLY_LINE_RESOURCE_PROJECTION_MAX_BYTES | 262144 (256 KiB) | Max bytes per projected resource. |
ASSEMBLY_LINE_RESOURCE_PROJECTION_ALLOWED_KINDS | all kinds | Comma-separated allowlist of projectable resource kinds. |
ASSEMBLY_LINE_RESOURCE_PROJECTION_ALLOW_WRITABLE | false | Allow projecting writable resources. |
Self-improvement, dynamic automations, dynamic connections
Env overrides for the agent.ts blocks of the same names.
| Variable | Default | Effect |
|---|---|---|
ASSEMBLY_LINE_SKILLS_WRITABLE | true | Agent may author/edit its own skills. |
ASSEMBLY_LINE_SKILLS_WRITE_APPROVAL | false | Skill writes require approval. |
ASSEMBLY_LINE_AUTOMATIONS_DYNAMIC | true | Agent may create dynamic time-based automations. |
ASSEMBLY_LINE_AUTOMATIONS_APPROVAL | false | Dynamic automation changes require approval. |
ASSEMBLY_LINE_SCHEDULES_DYNAMIC | — | Deprecated alias for ASSEMBLY_LINE_AUTOMATIONS_DYNAMIC. |
ASSEMBLY_LINE_SCHEDULES_APPROVAL | — | Deprecated alias for ASSEMBLY_LINE_AUTOMATIONS_APPROVAL. |
ASSEMBLY_LINE_CONNECTIONS_DYNAMIC | false | Agent may persist dynamic connections. |
ASSEMBLY_LINE_CONNECTIONS_APPROVAL | true | Saving a dynamic connection requires approval. |
ASSEMBLY_LINE_CONNECTIONS_ALLOWED_HOSTS | manifest allowedHosts or empty | Comma-separated dynamic-connection host allowlist. |
Scheduler
| Variable | Default | Effect |
|---|---|---|
ASSEMBLY_LINE_SCHEDULER_ENABLED | on | false/0 disables the in-process scheduler loop. |
Secrets and local store paths (@assemblyline-agents/node)
| Variable | Default | Effect |
|---|---|---|
ASSEMBLY_LINE_CONNECTION_STORE_SECRET | unset | Encryption secret for file-backed connection credential stores. Must be at least 32 characters outside dev mode. |
ASSEMBLY_LINE_SECRET | unset | Fallback for ASSEMBLY_LINE_CONNECTION_STORE_SECRET; the same 32-character minimum applies. |
ASSEMBLY_LINE_CONNECTION_GRANTS_FILE | <artifactRoot>/connection-grants.enc.json | Encrypted connection-grant store path. |
ASSEMBLY_LINE_CONNECTION_AUTH_SESSIONS_FILE | <artifactRoot>/connection-auth-sessions.enc.json | Encrypted authorization-session store path. |
ASSEMBLY_LINE_CONNECTION_DEFINITIONS_FILE | <artifactRoot>/connection-definitions.json | Dynamic connection definition store path. |
ASSEMBLY_LINE_SKILLS_FILE | <artifactRoot>/skills-store.json | Durable skill store path (file-backed state). |
ASSEMBLY_LINE_SCHEDULES_FILE | <artifactRoot>/dynamic-schedules.json | Dynamic schedule store path (file-backed state). |
ASSEMBLY_LINE_STATE_FILE | <artifactRoot>/runtime-state.json | File-backed runtime state path. |
ASSEMBLY_LINE_BLOB_ROOT | <artifactRoot>/blobs | Local blob storage root. |
ASSEMBLY_LINE_SANDBOX_ROOT | <artifactRoot>/sandbox | Local sandbox root. |
Build, deploy, and migrations (CLI and compiler)
| Variable | Default | Effect |
|---|---|---|
ASSEMBLY_LINE_ARTIFACT_PACKAGE_MODE | local | release makes build artifacts reference published @assemblyline-agents/* versions instead of vendored workspace copies. |
ASSEMBLY_LINE_DOCKER_IMAGE | openeve:<agentRevision[0:12]> | Docker deploy image tag (after --docker-image). |
ASSEMBLY_LINE_DEPLOY_ENV | development | Deployment environment after --env and before the gateway.ts option/default. |
ASSEMBLY_LINE_MIGRATION_COMMAND | unset | Migration runner executable for hosted deploys (after --migration-command). |
ASSEMBLY_LINE_ALLOW_LOCAL_SANDBOX_IN_PRODUCTION | off | true (exactly) acknowledges and permits an unconfined local sandbox on a non-local deploy target; otherwise planning fails before publish. |
Built-in deploy options use the same precedence everywhere: CLI flag,
environment variable, static gateway.ts option, then provider default. A
hosted plan warns when local state or local blob storage is selected because
those files may disappear when a container is replaced.
During a hosted deploy the CLI sets these in the migration process
environment (they are outputs, not knobs): ASSEMBLY_LINE_ARTIFACT_ROOT,
ASSEMBLY_LINE_AGENT_REVISION, ASSEMBLY_LINE_DEPLOY_ENV, ASSEMBLY_LINE_MIGRATION_FILES.
Provider: Postgres (@assemblyline-agents/postgres)
| Variable | Default | Effect |
|---|---|---|
ASSEMBLY_LINE_POSTGRES_CONNECTION_ENV | DATABASE_URL | Name of the env var holding the connection string. |
ASSEMBLY_LINE_POSTGRES_SSL_REJECT_UNAUTHORIZED | true (Railway preset: false) | Certificate verification is on by default when SSL is used; Railway's generated certificate is self-signed. |
ASSEMBLY_LINE_AUTO_MIGRATE | on | false (exactly) skips running Assembly Line migrations at provider construction. |
neonPostgres(), railwayPostgres(), and supabasePostgres() all read
DATABASE_URL by default and use the same Assembly Line schema and migrations.
railwayPostgres() additionally accepts databaseService (default Postgres)
and provision (default true). During a Railway deploy, those options create
or reuse that Railway database service and wire a private DATABASE_URL
reference onto the application service. Named non-default services must already
exist and use provision: false. The preset also defaults
sslRejectUnauthorized to false for Railway's generated Postgres certificate;
TLS remains enabled. For Supabase, use the direct URL on an IPv6-capable
persistent host or the session-pooler URL when IPv4 is required.
Provider: Docker (@assemblyline-agents/docker)
| Variable | Default | Effect |
|---|---|---|
ASSEMBLY_LINE_DOCKER_NETWORK | none | Container network for sandbox containers. |
ASSEMBLY_LINE_DOCKER_CPUS | unset | CPU limit passed to docker run. |
ASSEMBLY_LINE_DOCKER_MEMORY | unset | Memory limit passed to docker run. |
ASSEMBLY_LINE_DOCKER_PULL_POLICY | unset (Docker default) | never, missing, or always. |
ASSEMBLY_LINE_DOCKER_COMMAND_TIMEOUT_MS | unset | Timeout for Docker CLI commands. |
Provider: VPS (@assemblyline-agents/vps)
Preview — this surface may change without notice.
| Variable | Default | Effect |
|---|---|---|
ASSEMBLY_LINE_VPS_HOSTS_FILE | nearest assembly-line.hosts.json | Explicit versioned named-host inventory path; --vps-hosts-file takes precedence. |
Inventory identityFileEnv variable | required | Local path to the SSH private key for that named host. The variable name is inventory-defined. |
ASSEMBLY_LINE_VPS_BACKUP_BUCKET | required in host Postgres mode | S3-compatible database-backup bucket. |
ASSEMBLY_LINE_VPS_BACKUP_REGION | required in host Postgres mode | Backup bucket region. |
ASSEMBLY_LINE_VPS_BACKUP_ACCESS_KEY_ID | required in host Postgres mode | Backup-only S3 access key. |
ASSEMBLY_LINE_VPS_BACKUP_SECRET_ACCESS_KEY | required in host Postgres mode | Backup-only S3 secret key. |
ASSEMBLY_LINE_VPS_BACKUP_ENDPOINT | provider default | Optional custom S3-compatible endpoint. |
ASSEMBLY_LINE_VPS_BACKUP_RETENTION_DAYS | 30 | Number of days retained by the daily S3-compatible backup job. |
ASSEMBLY_LINE_VPS_ALERT_WEBHOOK_URL | unset | Optional webhook receiving five-minute runtime, public readiness, Postgres, backup-verification, timer, and disk alerts. Checks still run and record failures in systemd/journald when unset. |
The vpsDeploy() options are:
| Option | Default | Effect |
|---|---|---|
host | required | Named host from the versioned inventory. |
domain | required | Primary public hostname. |
aliases | [] | Additional hostnames claimed and routed transactionally with the primary domain. |
expectedRegion | unset | Emits a latency warning when inventory reports a different provider region. |
hostsFile | inventory discovery | Explicit inventory path. |
resources: { cpus, memory, pids } | { cpus: 1, memory: "1g", pids: 256 } | Runtime container limits. |
database: { mode } | "external" | "external" uses DATABASE_URL; "host" provisions an isolated database and role in managed host Postgres. |
monitoring: { enabled, diskFreeMinimumMb } | { enabled: true, diskFreeMinimumMb: 5120 } | Installs the deployment health timer. A configured alert webhook receives failures; local checks do not depend on it. |
caddyImage | caddy:2.10.0-alpine | Explicit non-latest edge image. |
postgresImage | postgres:17.10-alpine | Explicit numeric-major Postgres image. An image mismatch requires state upgrade-postgres. |
awsCliImage | amazon/aws-cli:2.17.57 | Explicit non-latest backup client image. |
CLI overrides are --vps-host, --vps-domain, and --vps-hosts-file.
Lifecycle commands add deploy --prepare-only, deploy --activate,
deploy --rollback, and deploy --domains-only. Operational commands are
hosts bootstrap, state migrate-postgres, state upgrade-postgres,
secrets diff, and agent quiesce|resume|status.
Provider: E2B (@assemblyline-agents/e2b)
| Variable | Default | Effect |
|---|---|---|
ASSEMBLY_LINE_E2B_TIMEOUT_MS | SDK default | Sandbox lifetime timeout. |
ASSEMBLY_LINE_E2B_RETAIN_TIMEOUT_MS | SDK default | Retain/pause timeout for dirty sandboxes. |
ASSEMBLY_LINE_E2B_REQUEST_TIMEOUT_MS | SDK default | Per-request timeout. |
ASSEMBLY_LINE_E2B_PAUSE_KEEP_MEMORY | SDK default | Keep memory when pausing. |
ASSEMBLY_LINE_E2B_ALLOW_INTERNET_ACCESS | SDK default | Sandbox internet egress. |
sandbox/*.ts env arrays are global passthrough variables. Validation and
the Node runtime reject host/control-plane credentials such as database URLs,
Railway/Hetzner credentials, E2B control keys, R2 secret keys, Photon tokens,
admin tokens, and OTLP auth headers in this list. Supply capability
credentials through typed connections or the per-command shell(..., { env })
scope.
Provider: Modal (@assemblyline-agents/modal)
Preview — this surface may change without notice.
| Variable | Default | Effect |
|---|---|---|
ASSEMBLY_LINE_MODAL_TIMEOUT_MS | SDK default | Sandbox timeout. |
ASSEMBLY_LINE_MODAL_WAIT_READY | SDK default | Wait for the sandbox to be ready before use. |
Provider: Daytona (@assemblyline-agents/daytona)
| Variable | Default | Effect |
|---|---|---|
ASSEMBLY_LINE_DAYTONA_CREATE_TIMEOUT_SECONDS | SDK default | Sandbox creation timeout. |
ASSEMBLY_LINE_DAYTONA_LIFECYCLE_TIMEOUT_SECONDS | SDK default | Lifecycle operation timeout. |
ASSEMBLY_LINE_DAYTONA_AUTO_STOP_MINUTES | SDK default | Auto-stop interval. |
ASSEMBLY_LINE_DAYTONA_AUTO_ARCHIVE_MINUTES | SDK default | Auto-archive interval. |
ASSEMBLY_LINE_DAYTONA_AUTO_DELETE_MINUTES | SDK default | Auto-delete interval. |
ASSEMBLY_LINE_DAYTONA_EPHEMERAL | true | Only the literal string false disables ephemeral sandboxes. |
ASSEMBLY_LINE_DAYTONA_NETWORK_BLOCK_ALL | SDK default | Block all sandbox network egress. |
ASSEMBLY_LINE_DAYTONA_NETWORK_ALLOW_LIST | unset | Network allowlist. |
ASSEMBLY_LINE_DAYTONA_DOMAIN_ALLOW_LIST | unset | Domain allowlist. |
ASSEMBLY_LINE_ALLOW_LOCAL_SANDBOX_FALLBACK | off | true (exactly) allows local fallback when the Daytona client is absent (dev/test only). |
Provider: Microsoft Teams (@assemblyline-agents/teams)
| Variable | Default | Effect |
|---|---|---|
ASSEMBLY_LINE_TEAMS_ALLOWED_TENANTS | all tenants | Comma-separated tenant ID allowlist. |
ASSEMBLY_LINE_TEAMS_ALLOWED_SERVICE_URLS | all URLs | Comma-separated service-URL prefix allowlist. |
ASSEMBLY_LINE_TEAMS_OPENID_METADATA_URL | Bot Framework default | Override for the OpenID metadata URL used in JWT verification. |