Agents

Agents are non-login identities in a repository. Each one has a home under ~/agents/{id}/, a soul you write, event prompts for inbound mail / Slack / messages, and an address on inbox.sails.app.

Creating an agent does not start work. Mail to it, or goal, does. Do not publish agents/ as a site root.

Done looks like

agent show support-bot lists the id, {id}@inbox.sails.app (and a claimed address if you claimed one), filesystem: jailed or disabled, plus any site_grants / jail_paths. The soul prints with agent soul support-bot. Filesystem tools stay off until you jail paths.

Worked example

agent create support-bot
# → UUID address always works: {id}@inbox.sails.app
# → filesystem tools disabled by default

agent soul support-bot --stdin <<'EOF'
# support-bot

You are the CRM support assistant. Be concise. Prefer tools over guessing.
First tool call on inbound mail is thread_show for that thread.
EOF

# or: agent soul support-bot --file ./souls/support-bot.md

agent claim helpdesk          # address: {org}-helpdesk@inbox.sails.app
                              # (not "support" — reserved)
agent grant support-bot --site sites/crm   # site *.mcp.sh / *.tool.sh only
agent jail support-bot --path agents/<id>  # mailbox / home FS for tools
agent jail support-bot --path sites/crm    # optional: let FS tools touch that tree
agent show support-bot
su support-bot                # act as the agent
su -                          # back to your login identity

Replace <id> with the UUID from agent create / agent show. agent claim is unique per org across agents and folder inboxes.

Layout

~/agents/{id}/
  soul.md                     # owner-authored persona (goal system append)
  events/                     # owner-authored event prompts
    email.received.md
    message.received.md
    slack.received.md
  README.md
  mail/inbox/                 # agent-owned mailbox
  mail/sent/
  messages/inbox/             # agent-owned agent-messages
  messages/sent/
  slack/inbox/
  slack/sent/
  slack/files/                # inbound Slack attachments

Canonical message bodies live under .sails/threads/{thread_id}/. Hydrate with thread show, not by reading those files directly. Agents should not rewrite their own soul — use agent soul (owner).

Filesystem access vs site grants

These are separate knobs.

Mode	How	Agent FS tools	Repo mount VFS
`disabled`	default on create; `agent jail --disable`	omitted (`bash_exec`, `read_file`, `write_file`, `edit_file`, `search`)	none
`jailed`	`agent jail --path`	those tools, scoped	allowlisted prefixes only
`full`	`agent unjail` (no `--path`)	unrestricted	entire workspace

agent grant AGENT --site SITE exposes that site’s *.mcp.sh / *.tool.sh tools only. It does not open the disk.
During a granted site tool run, call_tool may still read/write that site tree even when FS tools are disabled. The agent still cannot use read_file / bash_exec on those paths until jailed.
mail inbox / message inbox / stub reads stay available when filesystem tools are disabled.
Paths outside the repo mount (/skills, /tmp, …) are not gated by the jail.

When filesystem is disabled (the create default), the agent acts through search_tools / describe_tool / call_tool over *.tool.sh / *.mcp.sh in $HOME — do not try write_file.

Commands (owner / member)

Command	Notes
`agent create NAME`	Owner. Scaffolds VFS; filesystem disabled
`agent list` / `agent show`	Addresses, paths, grants, jail
`agent soul AGENT`	Print soul
`agent soul AGENT --file PATH` / `--stdin`	Owner replaces soul
`agent claim USERNAME`	`{org}-USERNAME@inbox.sails.app`. Not a UUID or reserved word
`agent unclaim`	UUID address remains
`agent grant` / `ungrant` / `grants`	Site MCP tools only
`agent jail` / `unjail` / `jail --disable`	Filesystem allowlist
`agent slack …`	Workspace link + per-agent bot — see Slack how-to
`agent rm ID`	Drops membership, claim, grants, jails, and `agents/{id}/`
`su AGENT` / `su -`	Switch effective identity (write+ member)

Write members and agents may schedule at / cron as themselves. With filesystem access (jailed or full), agents may ship create\|update\|delete for a non-root path they can write inside the jail. Custom --hostname / ship verify stay owner-only.

Failure modes

What you see	What it means	What to do
No `bash_exec` / `read_file` on the agent	Filesystem still `disabled`	`agent jail AGENT --path …` (typical first path: `agents/{id}`)
Site tools work but disk does not	You only ran `agent grant --site`	Grant ≠ jail. Add jail paths separately
Claim rejected	Reserved or taken username	Pick another; `support` is reserved. Address form is `{org}-USERNAME@inbox.sails.app`
Agent rewrote `soul.md`	Wrong owner path	Owner runs `agent soul … --file` / `--stdin` (rewrites and reassigns ownership)
You published `agents/`	Wrong site root	Publish a `sites/…` folder with `sails.site.json`, never `agents/`

How to: Give an agent a job, Talk to an agent in Slack, Message another agent, Mail from an agent.