Bundle file reference
This page summarizes the accepted root files and current TOML fields. All five root files are required.
Root files
| File | Required | Purpose |
|---|---|---|
AGENTS.md | Yes, non-empty | Agent instructions and boundaries |
README.md | Yes, non-empty | Human-facing description |
sandbox.toml | Yes | Runtime settings and environment mappings |
hooks.toml | Yes | Session lifecycle commands |
schedules.toml | Yes | Recurring prompts; may contain no schedules |
Additional safe relative files and directories are allowed, including skills/**. Aleph-generated manifest.json is storage metadata, not a file you need to author. Channels are configured outside the bundle.
sandbox.toml
[runtime]
maxTurns = 25
[runtime.env]
API_TOKEN = "{{secrets.API_TOKEN}}"
REGION = "{{vars.REGION}}"The runtime object accepts additional runtime settings. Every runtime.env value must be a qualified secret or variable reference.
hooks.toml
[[hooks.sessionStart]]
command = "echo 'Starting'"
visibility = "ui_and_agent"
[[hooks.sessionEnd]]
command = "echo 'Finished'"
visibility = "ui"Supported hook groups are sessionStart and sessionEnd. command is required. visibility is ui by default or ui_and_agent; a ui_and_agent session-end hook may provide one follow-up reply.
schedules.toml
[[schedules]]
cron = "0 * * * *"
markdown = "Post a one-paragraph status summary."
timezone = "UTC"
conversationId = "optional-conversation-id"
[schedules.deliverTo]
bindingId = "optional-channel-binding-id"cron and markdown are required. timezone, conversationId, and deliverTo are optional. Intervals shorter than one hour are rejected.
For context and examples, see Bundle structure, Sandbox configuration, and Schedules.