Agent folder anatomy
Everything an agent is — its identity, its memory, how it connects — lives in one directory. Edit it, the agent changes. Copy it, the agent travels.
Every agent on a Cast server is a single directory under ~/.cast/agents/ by default (override with CAST_AGENTS_DIR — see Runtime options). The directory IS the agent — not a manifest pointing elsewhere, not a database row with files alongside. Inside, the subfolders split into four zones by writer and lifetime. That split tells you what's portable, what's local to this install, what the server writes for you, and what the agent writes for itself.
The four zones
blueprint/ into a fresh install and the agent behaves the same.agent.db), attachments, tasks, identity roster. Server-managed — read when debugging, never hand-edit.memory/ and home/ are the agent's working storage. shared/ and ext/ are extensions' publish-to-agent outputs and private state. All mounted into the container.Everything else under the folder is process scratch — recreated on each run, safe to ignore.
The manifest
manifest.json at the top of the folder holds the agent's identifying metadata. Required: spec (schema version) and name (the agent's alias — the folder name on disk is independent). Optional standard fields: pubkey, description, status: "draft". Additional keys pass through untouched, so generators can stash provenance metadata without coordinating with the server.
{
"spec": "1.0.0",
"name": "morning-briefing",
"description": "Curates morning emails.",
"pubkey": "0a3f...8e2c"
}What the container sees
The agent runs inside a container, and the container is a sandbox. The LLM only sees what's mounted in. Everything else on disk — config/, blueprint/service/, the bus, the host filesystem — is invisible from the agent's side.
| Inside the container | Mounted from | Access |
|---|---|---|
/identity | blueprint/identity/ | read-only |
/assets | blueprint/assets/ | read-only |
/memory | memory/ | read-write |
/home/agent | home/ | read-write |
/shared | shared/ext/ | read-only |
/attachments | state/attachments/ | read-only |
/staging | per-conversation staging/ | read-write |
config/ext/email/.env is invisible to the agent — only the extension code (running on the host) sees it. A secret in home/ or memory/ is right there in the agent's filesystem, available to any tool the agent invokes. When in doubt about a credential, config/.The folder map
Not exhaustive — the load-bearing entries, with their zone in the right margin.
What to read next
- Conversations — what actually runs inside the container, and how the conversation tuple bounds isolation.
- Channels — the concept behind each
blueprint/channels/<name>/folder. - Authoring blueprints — the contents of
blueprint/as authoring surfaces: identity, channels, props, the system prompt that ties them together. - Writing services — when
blueprint/service/earns its keep, and the trust model that comes with it.