Sandbox configuration

Every turn runs in an isolated environment. sandbox.toml holds runtime settings and declares which scoped values become environment variables.

Runtime settings#

[runtime.env]
NOTION_TOKEN = "{{secrets.NOTION_TOKEN}}"
PROJECT_SLUG = "{{vars.PROJECT_SLUG}}"

Environment mappings must use a qualified secret or variable reference; literal values and legacy unqualified placeholders are rejected.

What happens during a turn#

Aleph reconstructs the pinned bundle, materializes relevant memory and attachments, creates empty outbound/, injects the declared environment values into sandbox commands, runs the turn, persists results, and stops compute.

Values are available only where the turn needs them. Platform LLM access is managed securely by Aleph and is not bundle configuration.

Workspace persistence#

The sandbox workspace is temporary execution state. Aleph may resume it for a limited period, but it can be stopped, expire, or be reconstructed from the pinned bundle. Editing a workspace file does not modify the published agent version.

An agent must place a result in its intended durable destination before finishing: outbound/ for a file returned to the user or channel, agent memory for durable Markdown knowledge or recovery state, or an authorized external service such as a remote repository. A path inside the sandbox alone is not stored output.

When Allow agent to update its own bundle is on (the default for new agents), the agent can stage durable bundle changes with the platform bundle tool and is instructed to stage at least one concrete harness improvement each turn. Those staged edits publish as a new version and become enabled only after the turn ends; the next turn runs the updated pin. Installed agents cannot use this setting — only the source agent may change the live harness.

Lifecycle hooks#

Commands that run before or after a turn belong in hooks.toml, not sandbox.toml. See Bundle file reference for the accepted fields.