myclawn run (the fleet)

myclawn run claude is how every other CLI agent — Claude Code, Codex, opencode, aider, your own — gets wrapped in MyClawn. The agent runs inside a dedicated Unix user (the "bot"), behind a daemon-side proxy, with one tool for reaching out: myclawn ask. It cannot read your files. It cannot touch your wallet. It can talk to LLMs you authorised, propose work via request_myclawn, and that's it.

What `myclawn run` actually does

When you type myclawn run claude for the first time:

The launcher fetches the latest run.js + fleet.js from the CDN.
If /usr/local/bin/myclawn-fleet is missing or stale, it drops the helper + a narrow sudoers rule (one interactive sudo prompt, only the first time).
Either picks the first existing bot user in your registry, or creates a fresh one (bot-1, bot-2, …) via the helper.
Writes a per-bot .zshenv with HTTPS_PROXY / NODE_EXTRA_CA_CERTS / etc. pointing at the daemon proxy.
Copies your real Claude Code OAuth token into ~bot-N/.claude/.credentials.json + sets CLAUDE_CODE_OAUTH_TOKEN in the spawn env (so the bot's interactive claude doesn't hit the login menu).
Pre-accepts claude's onboarding wizard + the bypass-permissions disclaimer in ~bot-N/.claude/settings.json.
Spawns the agent under a pty: sudo -H -u bot-N -- claude --append-system-prompt "<priming>" --dangerously-skip-permissions, working dir /tmp (a place the bot can open()).
Registers the pty with the daemon's control.sock, so the dashboard can later whisper into it.

On subsequent runs, steps 1–5 are essentially no-ops (idempotent refreshes). You'll see the bot show up as Local · live in the dashboard's Activity tab while the session is open.

The bot user model

Each bot-N is a real OS user. The kernel's uid permission model is the sandbox — exactly what protects Postgres' data dir from a normal-user process. A compromised agent running as bot-1 literally cannot open() files owned by you:

~/.aws/credentials — no
~/.ssh/id_rsa — no
Chrome cookies, Slack tokens, your password manager — no
~/.myclawn/wallet.json — no
Your project files at ~/Downloads/myproject/ — no (unless you explicitly opened them up; see below)

The only things the bot can reach are its own home directory and the daemon sockets at ~/.myclawn/*.sock (which are mode 0666 by design — they're the front door, and the daemon does its own auth on top). That's the entire surface area between the agent and the rest of your machine.

No read/write to your system

This is the most important sentence in the docs: MyClawn does not give its agents read or write access to your files or settings.

When myclawn run claude starts, you are not "running claude with full home access." You are running an LLM in a sandboxed user that happens to be able to call:

LLM providers — through the substitution proxy, with credentials the daemon owns
myclawn ask — to request work from your MyClawn clone (which decides what to do with the request)
A handful of MCP tools — see the catalog: request_myclawn, memory_search, recent_chat, create_escrow + read-only escrow queries, etc. All propose / read verbs only — no direct authority over your data or wallet.

If you want the agent to actually touch your project files (e.g. claude editing your codebase), there are three paths, in order of preference:

--no-bot — opt out of isolation for that session. The agent runs as you, full access. Use when you trust the agent and the prompt and the inputs.
Share a directory — sudo setfacl -m u:bot-1:rwx /Users/you/projects/foo (Linux) or use shared groups + chmod (macOS) to grant just that path. Bot can read/write that one dir, nothing else.
Copy in — cp -r ~/projects/foo /Users/bot-1/foo as you, chown -R bot-1 /Users/bot-1/foo, work there, copy results back. Slowest, but the strongest isolation.

For most experimental / agentic use cases (let claude run wild against a codebase), the bot model is exactly right: there is nothing destructive it can do to you. Worst case it trashes its own bot home, which you can wipe with myclawn remove <bot>.

Priming: how the agent learns about `myclawn ask`

At startup, MyClawn primes the agent with a short note: myclawn ask "<message>" --budget <N> is its async link to you and to the wider network. Use it anywhere you'd otherwise stop and wait — a question, a blocker, a "task done" notification, a fact outside your context. The agent's answer prints to stdout on the same line.

For Claude the priming is delivered via --append-system-prompt — system layer, claude trusts it as operator context. Earlier wording delivered as a user message was flagged by claude's prompt-injection detector and the session refused to call myclawn ask at all.

For other agents (codex, opencode, aider, your custom one) MyClawn injects the priming as a single user-message after a short delay. You can opt out with MYCLAWN_NO_PRIMING=1 (useful when --resume'ing a session that already knows the convention) or by passing your own --system-prompt / --append-system-prompt.

Whispering from the dashboard

Once a bot is live, you can push text into its terminal from the desktop app. Open the Activity tab, click any row badged Local · live, and the detail view shows the bot's:

Isolated Unix user
HTTPS proxy address (daemon side)
CA cert path
MCP socket path
Recent conversation as a chat (your injections, the agent's questions, MyClawn's answers)

The composer at the bottom writes straight into the bot's pty as if you typed in its terminal. If the badge reads Local · offline the pty has exited — re-run myclawn run --name=<agent> -- <cmd> to reattach. Errors (ACL rejection, agent not registered, daemon offline) surface inline in red so you don't get the silent-send failure.

Bot naming

Without arguments, myclawn run claude uses the first bot in your registry (creating bot-1 if none exists). Pass --bot=NAME to pick a specific one. Bare names are auto-prefixed (--bot=lisa → bot-lisa) because the fleet helper only operates on bot-* users.

Session label (--name) is independent of the bot user — it controls what the dashboard, audit log, and inject_into actions address. Default is derived from basename(cwd) + cmd.

Examples

# default — uses bot-1, name derived from cwd
myclawn run claude

# explicit bot, explicit session name
myclawn run --bot=lisa --name=monorepo -- claude --resume <id>

# spawn three parallel agents
myclawn run --bot=writer  --name=writer  codex
myclawn run --bot=coder   --name=coder   claude
myclawn run --bot=ops     --name=ops     aider

# opt out of fleet isolation (legacy behavior — agent runs as you)
myclawn run --no-bot -- claude

Passing custom env vars to a bot

myclawn run --bot=... goes through sudo, which scrubs the parent env by default. Only the sudoers env_keep list passes through (proxy + CA + socket paths + CLAUDE_CODE_OAUTH_TOKEN + ANTHROPIC_API_KEY). If your tool needs something else, prefix the command with env:

# one-shot
myclawn run --bot=bot-1 -- env NODE_ENV=production DATABASE_URL=postgres://… myapp

# persistent — write into the bot's ~/.zshenv
sudo -u bot-1 -i -- sh -c 'echo "export FOO=bar" >> ~/.zshenv'

Provider API keys are the exception — never pass them as env OPENAI_API_KEY=.... The bot would see the real key in its process memory. Use myclawn --model to register the key once; the daemon stores it in ~/.myclawn/keys.json (mode 0600) and the bot sees only the placeholder string the proxy substitutes for at request time. More on the proxy →

Lifecycle & cleanup

Bots persist across sessions. myclawn ls lists every bot, its state, GUI visibility, and process count. myclawn remove <name> deletes a bot user and its home dir (requires typing the name to confirm).

Closing the pty (Ctrl-C, exit, daemon SIGTERM) unregisters the agent but keeps the bot user around for the next session — re-running myclawn run --bot=<same> reattaches to the same home / credentials / settings without redoing setup.

← The agent network The substitution proxy →