The agent folder

Every file egin reads, and what each one does. Only agent.toml and instructions.md are needed.

my-agent/
  agent.toml               model and switches
  instructions.md          system prompt
  memory/*.md              appended to the system prompt
  skills/<name>/SKILL.md   loaded on demand with the skill tool
  tools/<name>.py          a tool: one script, any language, described by its header comments
  tools/<name>.json        optional: a full JSON schema for a tool, where the header can't express it
  middleware/pre_tool      runs on the host before every tool call
  connections/<name>.toml  MCP servers
  channels/<name>.toml     webhook, slack, telegram, discord, github, mcp
  hooks/<event>            runs on the host for each stored event; hooks/done can send the run on
  instrumentation/<name>.toml  where traces go (OTLP)
  subagents/<name>/        a nested agent folder
  schedules/<name>.toml    cron prompts
  profiles/<model>.toml    per-model switch defaults
  profiles/<model>.md      per-model instructions
  evals/<name>.toml        a prompt and a check
  evals/variants.toml      named sets of config overrides
  workspace/               the files the agent works on
  .egin/                   sessions and the file index

agent.toml

The model and the switches. Every switch has a default, so this file only holds what you change. See Configuration for the full list.

model = "kimi-k3.1-pro"
web = "client"
planning = true
memory_max = 6000
approval = "never"
network = []

instructions.md

The system prompt, as plain Markdown. egin appends the list of skills, the contents of memory/, and per-model instructions from profiles/<model>.md when they exist.

memory/

Every .md file here is appended to the system prompt. With memory_max set, the agent gets a memory tool that edits memory/notes.md, capped at that many bytes. Use it for facts that should carry across sessions.

workspace/

The files the agent works on: runbooks, a knowledge base, a repository. In a microVM it is mounted at /workspace; a cloud sandbox (E2B, Vercel, Daytona) gets a copy; with sandbox = "local" tools run in this folder itself.

.egin/

egin’s own state: the SQLite database of sessions and events, and the file index. Add it to .gitignore. Tool output too long for the conversation is saved in full under .egin/out/ in the sandbox’s working folder, where the agent can read it.

Precedence

Settings are merged in this order, later winning:

  1. Built-in defaults
  2. profiles/<model>.toml
  3. agent.toml
  4. --set key=value on the command line

Set profile = false in agent.toml to ignore the model’s profile.