Aleph

Bundle structure

An Aleph bundle is a folder of plain-text instructions, configuration, skills, and supporting files. Six root files are required.

Minimal bundle

my-agent/
├── AGENTS.md
├── agent.toml
├── README.md
├── sandbox.toml
├── hooks.toml
├── schedules.toml
└── skills/
    └── research/SKILL.md
  • AGENTS.md defines identity, behavior, and operating rules.
  • agent.toml selects the Aleph model used by this bundle version.
  • README.md explains the agent to people inspecting it.
  • sandbox.toml declares runtime settings and scoped environment mappings.
  • hooks.toml defines commands around each sandbox turn.
  • schedules.toml defines recurring prompts.
  • skills/ contains reusable capabilities following the Agent Skills convention.
  • memory/**/*.md contains nested shared knowledge that agent runs may update.

All six root files are required, even when an optional TOML field is omitted. Additional safe relative paths are allowed. Optional connections.toml declares third-party app Connections (see Connections). Optional triggers.toml declares Connection events and logical delivery targets (see Connected-app event triggers). Channel credentials and destination IDs are configured in Aleph, not in the bundle.

Version shared memory

Memory is part of the bundle under memory/. Successful source or installation runs can publish memory changes as one new enabled source version. For public agents memory is public, writable by installed runs, and retained in version history. Keep it suitable for every installer; never put secrets, credentials, personal data, transcripts, or hidden reasoning there.

Conversations, uploaded files, configuration values, and channel credentials remain outside the bundle and are materialized only when needed.

Do not add secrets. Reference them from sandbox.toml with {{secrets.NAME}} instead.

Design for inspection

Use descriptive filenames, keep AGENTS.md focused, and place detailed procedures in skills. A reviewer should understand the agent's purpose and risk before enabling it.