Configuration Reference

This page is the single reference for agent-folder configuration shapes and every OPENEVE_* 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, harness, 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 @openeve/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.

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 the provider API key (for example openai/* needs OPENAI_API_KEY). openeve models lists the local catalog.
id	string	no	Stable logical agent identity. Keeps learned skills 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.
selfImprovement	object	no	Skill authoring config; see below.
dynamicSchedules	object	no	Runtime-created schedule 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 canonical primary engine; agent.ts has no harness: slot (declaring one fails validation with harness-not-configurable). Subagents may still declare harness: in subagents/<name>/agent.ts.

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.
dynamicSchedules	dynamic	true	Agent may create/manage schedules through ctx.scheduleManager.
dynamicSchedules	approval	false	Dynamic schedule 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 harness engine's own choice.
harness	AdapterDefinition?	Subagent harness. Compiler default is adapter("pi"); codex and claude-code are alternative engines, LiveKit is a voice capability that rides the same harness seam (not an engine), and any registered AgentHarness kind also works.
workspace	AdapterDefinition?	Sandbox/workspace adapter for the subagent (compiled with role sandbox).
connections	string[]?	Connection names the subagent may use.
engineConnection	string?	Connection that authenticates the external engine itself.

The compiler also records what the subagent inherits: skills, tools (declared tools plus defaultTools), and context (context: true).

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 package name that exports openeveProvider; it is stored as packageName on the definition. This is how third-party 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, connection, and subagent. See Authoring Adapters for the provider-package contract and Adapters for the built-in matrix.

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.

@openeve/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 example recentHistory: { maxMessages: 12 } or files: { includeManifest: true }.
• defineContext(policy) declares a custom ContextPolicy:

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.

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/, schedules/, triggers/, connections/, sandbox/, subagents/, instrumentation.ts. Anything else produces an unknown-top-level warning.

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, and a capability block with visibility (always/deferred/skill/hidden), execution (direct/sandbox/both), namespace, tags[], aliases[]. Visibility is inferred as always for defaultTools members and deferred otherwise unless declared.

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, defineGitHubChannel) 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.

schedules/*.ts

Must declare cron (at least 5 fields) and idempotencyKey (errors: missing-schedule-cron, invalid-schedule-cron, missing-schedule-idempotency). Optional: description, timezone, message, and trigger. A trigger must name a handler that matches a triggers/<handler>.ts file, and can carry a target ({ type: "skill" | "agent" | "playbook", ... }) and metadata.

triggers/*.ts

The filename is the handler name. defineTriggerHandler({ description?, prepare?(ctx), finalize?(ctx, result), metadata? }). Handlers are trusted app code invoked by the schedule dispatch lifecycle.

connections/*.ts

Protocol is inferred from the helper (defineMcpClientConnection -> mcp, defineOpenAPIConnection -> openapi, defineHttpApiConnection -> http, 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.

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.

instrumentation.ts

defineInstrumentation({ serviceName?, exporters?, recordInputs?, recordOutputs?, captureContent?, functionId?, metadata?, setup? }). If setup() returns a telemetry sink, the runtime uses it unless the host supplied telemetry directly.

Third-party 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 OPENEVE_* variable read by the packages in this repo. Boolean variables accept true/1 and false/0 unless noted. Provider-specific non-OPENEVE_ env (API keys, DATABASE_URL, SLACK_*, ...) is documented in Adapters and Runtime And Deployment.

Server and auth (@openeve/node)

Variable	Default	Effect
OPENEVE_ADMIN_TOKEN	unset	Bearer token for control-plane routes (/manifest, /routes, /runs*). Production boot fails without this or a host auth policy.
OPENEVE_ENABLE_API_RUNS	disabled	true/1 enables authenticated POST /runs in production (always on in dev mode).
OPENEVE_SCHEDULER_SECRET	unset	Shared secret for /openeve/scheduler/tick (Authorization: Bearer or x-openeve-scheduler-secret, compared constant-time). Unset means dev-mode-only tick.
OPENEVE_HTTP_MAX_BODY_BYTES	10485760 (10 MiB)	Max HTTP request body size before parsing.
OPENEVE_PUBLIC_URL	http://localhost	Public base URL; also the fallback for connection callbacks.
OPENEVE_CONNECTION_CALLBACK_BASE_URL	falls back to OPENEVE_PUBLIC_URL	Base URL for OAuth/connection authorization callbacks.

Concurrency and rate limiting

Variable	Default	Effect
OPENEVE_MAX_CONCURRENT_RUNS	unlimited (16 in production Node hosts when unset)	Max simultaneously executing brand-new runs; resumes never queue. Excess is rejected with RunCapacityError / HTTP 429.
OPENEVE_MAX_QUEUED_RUNS	0	Brand-new runs allowed to wait for a slot before rejection.
OPENEVE_INGRESS_RATE_LIMIT	off	Provider-channel token bucket as capacity/refillPerSecond (e.g. 60/10).
OPENEVE_RUNS_RATE_LIMIT	off	POST /runs token bucket in the same form.

Graceful shutdown

Variable	Default	Effect
OPENEVE_SHUTDOWN_TIMEOUT_MS	30000	Max wait for in-flight runs to drain during graceful shutdown.
OPENEVE_SIGNAL_HANDLERS	on	false/0 prevents listenNodeRuntime from installing SIGTERM/SIGINT graceful-shutdown handlers.

OTLP telemetry (@openeve/otlp)

Variable	Default	Effect
OPENEVE_OTLP_BATCH_MAX	sink default	Max spans batched before an OTLP flush.
OPENEVE_OTLP_FLUSH_MS	sink default	Flush interval for the OTLP sink.

Durability workers and recovery

Variable	Default	Effect
OPENEVE_DELIVERY_WORKER	on	false/0 disables the delivery queue worker.
OPENEVE_SANDBOX_SYNC_WORKER	on	false/0 disables the sandbox-sync worker.
OPENEVE_RUN_RECOVERY	on	false/0 disables boot recovery and the periodic orphan sweep.
OPENEVE_RUN_HEARTBEAT_MS	30000	How often executing runs bump updatedAt to stay out of the orphan sweep.
OPENEVE_RUN_RECOVERY_INTERVAL_MS	60000	Orphan sweep interval; runs are only candidates after max(5min, 4x heartbeat) staleness.

Delivery queue

Variable	Default	Effect
OPENEVE_DELIVERY_RETRY_ATTEMPTS	2	In-process send attempts before deferring to the durable queue.
OPENEVE_DELIVERY_RETRY_MIN_MS	250	Min backoff between in-process retries.
OPENEVE_DELIVERY_RETRY_MAX_MS	5000	Max backoff between in-process retries.
OPENEVE_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.
OPENEVE_DELIVERY_QUEUE_BATCH_SIZE	10	Deliveries leased per worker tick.
OPENEVE_DELIVERY_QUEUE_MAX_ATTEMPTS	5	Total attempts before a delivery goes terminally failed.
OPENEVE_DELIVERY_QUEUE_INTERVAL_MS	15000	Delivery worker tick interval.
OPENEVE_DELIVERY_FILE_MAX_COUNT	10 (max 100)	Max attachment files per delivery.
OPENEVE_DELIVERY_FILE_MAX_BYTES	52428800 (50 MiB)	Max bytes per delivery file.

Sandbox sync and hydration

Variable	Default	Effect
OPENEVE_SANDBOX_SYNC_INLINE	false	Run sandbox sync inline instead of through the background worker.
OPENEVE_SANDBOX_SYNC_LEASE_MS	300000	Lease duration for a claimed sync job.
OPENEVE_SANDBOX_SYNC_BATCH_SIZE	10	Sync jobs leased per worker tick.
OPENEVE_SANDBOX_SYNC_MAX_ATTEMPTS	5	Max attempts before a job is blocked for an operator.
OPENEVE_SANDBOX_SYNC_INTERVAL_MS	30000	Sandbox-sync worker tick interval.
OPENEVE_LEGACY_FULL_SANDBOX_HYDRATION	off	true/1 forces legacy full hydration instead of minimal per-path hydration.

Sandbox snapshots

Variable	Default	Effect
OPENEVE_SANDBOX_SNAPSHOT_MODE	unset (policy default never)	never, manual, on_failure, or always; overrides the declared snapshot policy.
OPENEVE_SANDBOX_SNAPSHOT_RETAIN_LAST	unset	Snapshots to retain (non-negative integer); only read when a mode is set.
OPENEVE_SANDBOX_SNAPSHOT_REASON	unset	Free-form snapshot reason label.

Model loop, memory, and logging

Variable	Default	Effect
OPENEVE_CHECKPOINT_EVERY_ITERATION	true	Persist the harness continuation checkpoint after every model iteration (bounds crash loss to one in-flight model call).
OPENEVE_TOOL_OUTPUT_MAX_CHARS	8000	Max serialized tool-output size handed back to the model before it becomes a { truncated, preview } object.
OPENEVE_MEMORY_EMBEDDINGS_ENABLED	on only when an embedding provider is configured	Enables embedding-backed semantic memory search.
OPENEVE_LOG_LEVEL	info	Structured log verbosity: debug, info, warn, or error.
OPENEVE_BASH_TOOL_MODE	enabled	Core bash tool policy: enabled, approval, or disabled.

Attachments and resource projection

Variable	Default	Effect
OPENEVE_ATTACHMENT_MAX_COUNT	20 (max 100)	Max inbound attachments per turn.
OPENEVE_ATTACHMENT_MAX_BYTES	52428800 (50 MiB)	Max bytes per attachment.
OPENEVE_ATTACHMENT_FETCH_TIMEOUT_MS	30000 (1s-120s)	Attachment download timeout.
OPENEVE_ZIP_MAX_FILES	500 (max 10000)	Max entries when expanding a ZIP attachment.
OPENEVE_ZIP_MAX_TOTAL_BYTES	104857600 (100 MiB)	Max total uncompressed ZIP bytes.
OPENEVE_RESOURCE_PROJECTION_MAX_FILES	8	Max resources projected into a sandbox per request.
OPENEVE_RESOURCE_PROJECTION_MAX_BYTES	262144 (256 KiB)	Max bytes per projected resource.
OPENEVE_RESOURCE_PROJECTION_ALLOWED_KINDS	all kinds	Comma-separated allowlist of projectable resource kinds.
OPENEVE_RESOURCE_PROJECTION_ALLOW_WRITABLE	false	Allow projecting writable resources.

Self-improvement, dynamic schedules, dynamic connections

Env overrides for the agent.ts blocks of the same names.

Variable	Default	Effect
OPENEVE_SKILLS_WRITABLE	true	Agent may author/edit its own skills.
OPENEVE_SKILLS_WRITE_APPROVAL	false	Skill writes require approval.
OPENEVE_SCHEDULES_DYNAMIC	true	Agent may create dynamic schedules.
OPENEVE_SCHEDULES_APPROVAL	false	Dynamic schedule changes require approval.
OPENEVE_CONNECTIONS_DYNAMIC	false	Agent may persist dynamic connections.
OPENEVE_CONNECTIONS_APPROVAL	true	Saving a dynamic connection requires approval.
OPENEVE_CONNECTIONS_ALLOWED_HOSTS	manifest allowedHosts or empty	Comma-separated dynamic-connection host allowlist.

Scheduler

Variable	Default	Effect
OPENEVE_SCHEDULER_ENABLED	on	false/0 disables the in-process scheduler loop.

Secrets and local store paths (@openeve/node)

Variable	Default	Effect
OPENEVE_CONNECTION_STORE_SECRET	unset	Encryption secret for file-backed connection credential stores. Must be at least 32 characters outside dev mode.
OPENEVE_SECRET	unset	Fallback for OPENEVE_CONNECTION_STORE_SECRET; the same 32-character minimum applies.
OPENEVE_CONNECTION_GRANTS_FILE	<artifactRoot>/connection-grants.enc.json	Encrypted connection-grant store path.
OPENEVE_CONNECTION_AUTH_SESSIONS_FILE	<artifactRoot>/connection-auth-sessions.enc.json	Encrypted authorization-session store path.
OPENEVE_CONNECTION_DEFINITIONS_FILE	<artifactRoot>/connection-definitions.json	Dynamic connection definition store path.
OPENEVE_SKILLS_FILE	<artifactRoot>/skills-store.json	Durable skill store path (file-backed state).
OPENEVE_SCHEDULES_FILE	<artifactRoot>/dynamic-schedules.json	Dynamic schedule store path (file-backed state).
OPENEVE_STATE_FILE	<artifactRoot>/runtime-state.json	File-backed runtime state path.
OPENEVE_BLOB_ROOT	<artifactRoot>/blobs	Local blob storage root.
OPENEVE_SANDBOX_ROOT	<artifactRoot>/sandbox	Local sandbox root.
OPENEVE_ALLOW_LOCAL_SANDBOX_IN_PRODUCTION	off	true (exactly) permits the unconfined local sandbox in production.

Build, deploy, and migrations (CLI and compiler)

Variable	Default	Effect
OPENEVE_ARTIFACT_PACKAGE_MODE	local	release makes build artifacts reference published @openeve/* versions instead of vendored workspace copies.
OPENEVE_DOCKER_IMAGE	openeve:<agentRevision[0:12]>	Docker deploy image tag (after --docker-image).
OPENEVE_MIGRATION_COMMAND	unset	Migration runner executable for hosted deploys (after --migration-command).

During a hosted deploy the CLI sets these in the migration process environment (they are outputs, not knobs): OPENEVE_ARTIFACT_ROOT, OPENEVE_AGENT_REVISION, OPENEVE_DEPLOY_ENV, OPENEVE_MIGRATION_FILES.

Provider: Postgres (@openeve/postgres)

Variable	Default	Effect
OPENEVE_POSTGRES_CONNECTION_ENV	DATABASE_URL	Name of the env var holding the connection string.
OPENEVE_POSTGRES_SSL_REJECT_UNAUTHORIZED	false	true enforces certificate verification when SSL is used.
OPENEVE_AUTO_MIGRATE	on	false (exactly) skips running OpenEve migrations at provider construction.

Provider: Docker (@openeve/docker)

Variable	Default	Effect
OPENEVE_DOCKER_NETWORK	none	Container network for sandbox containers.
OPENEVE_DOCKER_CPUS	unset	CPU limit passed to docker run.
OPENEVE_DOCKER_MEMORY	unset	Memory limit passed to docker run.
OPENEVE_DOCKER_PULL_POLICY	unset (Docker default)	never, missing, or always.
OPENEVE_DOCKER_COMMAND_TIMEOUT_MS	unset	Timeout for Docker CLI commands.

Provider: E2B (@openeve/e2b)

Variable	Default	Effect
OPENEVE_E2B_TIMEOUT_MS	SDK default	Sandbox lifetime timeout.
OPENEVE_E2B_RETAIN_TIMEOUT_MS	SDK default	Retain/pause timeout for dirty sandboxes.
OPENEVE_E2B_REQUEST_TIMEOUT_MS	SDK default	Per-request timeout.
OPENEVE_E2B_PAUSE_KEEP_MEMORY	SDK default	Keep memory when pausing.
OPENEVE_E2B_ALLOW_INTERNET_ACCESS	SDK default	Sandbox internet egress.

Provider: Modal (@openeve/modal)

Variable	Default	Effect
OPENEVE_MODAL_TIMEOUT_MS	SDK default	Sandbox timeout.
OPENEVE_MODAL_WAIT_READY	SDK default	Wait for the sandbox to be ready before use.

Provider: Daytona (@openeve/daytona)

Variable	Default	Effect
OPENEVE_DAYTONA_CREATE_TIMEOUT_SECONDS	SDK default	Sandbox creation timeout.
OPENEVE_DAYTONA_LIFECYCLE_TIMEOUT_SECONDS	SDK default	Lifecycle operation timeout.
OPENEVE_DAYTONA_AUTO_STOP_MINUTES	SDK default	Auto-stop interval.
OPENEVE_DAYTONA_AUTO_ARCHIVE_MINUTES	SDK default	Auto-archive interval.
OPENEVE_DAYTONA_AUTO_DELETE_MINUTES	SDK default	Auto-delete interval.
OPENEVE_DAYTONA_EPHEMERAL	true	Only the literal string false disables ephemeral sandboxes.
OPENEVE_DAYTONA_NETWORK_BLOCK_ALL	SDK default	Block all sandbox network egress.
OPENEVE_DAYTONA_NETWORK_ALLOW_LIST	unset	Network allowlist.
OPENEVE_DAYTONA_DOMAIN_ALLOW_LIST	unset	Domain allowlist.
OPENEVE_ALLOW_LOCAL_SANDBOX_FALLBACK	off	true (exactly) allows local fallback when the Daytona client is absent (dev/test only).

Provider: Microsoft Teams (@openeve/teams)

Variable	Default	Effect
OPENEVE_TEAMS_ALLOWED_TENANTS	all tenants	Comma-separated tenant ID allowlist.
OPENEVE_TEAMS_ALLOWED_SERVICE_URLS	all URLs	Comma-separated service-URL prefix allowlist.
OPENEVE_TEAMS_OPENID_METADATA_URL	Bot Framework default	Override for the OpenID metadata URL used in JWT verification.