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]
maxTurns = 25

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

Runtime settings beyond env are passed through for the harness. 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.

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.