Bundle file reference

This page summarizes the accepted root files and current TOML fields. All six root files are required.

Root files#

Additional safe relative files and directories are allowed, including skills/** and optional connections.toml. Aleph-generated manifest.json is storage metadata, not a file you need to author. Channels are configured outside the bundle.

agent.toml#

model = "aleph-light"

Aleph Light prioritizes speed and efficiency. Aleph Pro provides deeper reasoning for complex, multi-step work and uses model = "aleph-pro". When model is omitted, Aleph Light is used. Both models consume the account's shared usage-credit balance according to their token usage.

connections.toml (optional)#

[[connections]]
id = "github"
required = true

Declares third-party apps the agent needs. Supported id values include github, slack, gmail, notion, and 100+ other Connect apps. When required = true, turns fail until the workspace authorizes that Connection. See Connections.

triggers.toml (optional)#

Declares Connection event subscriptions, their prompts, provider configuration, and portable logical channel targets. Runtime subscription IDs and mapped destinations are platform state, not bundle content. See Connected-app event triggers.

sandbox.toml#

[runtime.env]
API_TOKEN = "{{secrets.API_TOKEN}}"
REGION = "{{vars.REGION}}"

Every runtime.env value must be a qualified secret or variable reference. An empty sandbox.toml is valid when the agent needs no environment mappings.

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.