Run crab safely — docs

crab runs with your user's permissions. It can read, write and execute anything you can. Confirmation is a seatbelt against accidents, not a boundary against an adversary — and the docs say so rather than implying otherwise.

The trust model, stated plainly

What crab is: A program you started, with your uid, your environment, and your SSH keys.
What the gate does: Read-only operations pass; anything that writes, runs or touches the network asks first.
What the gate does not do: Distinguish a safe bash call from a destructive one. There is no policy language, no command allowlist, and no sandbox.
What the agent is: An untrusted planner. Model output — and the contents of any file or page it reads — can steer it.

How the gate is layered

Read-only passes through. read, glob, grep, and bash commands classified as read-only (ls, cat, git status) run without asking.
Everything else asks once per class, per session. write, edit, web_fetch, non-read-only bash, and every MCP tool call.
--yolo disables the prompts for that run; /yolo toggles it in session, and the footer shows yolo ON so you cannot forget.
--print auto-approves, because there is nobody at the keyboard to answer.

⚠ bash — run: rm -rf build
allow? [y]es/[n]o/[a]ll:

a approves that class for the rest of the session. Approvals are not written to disk.

Why there is no allowlist. Any policy built on command strings is trivially bypassed: bash -c, eval, $(...), writing a script and running it, find -exec. A gate that looks like security but isn't is worse than a gate honestly labelled as a seatbelt.

Isolation that actually works

How you run it	What is protected	Rough cost
Directly, as yourself	Nothing beyond your own permissions.	zero
Dedicated user account	Your other files and credentials.	one `useradd`
Container with only the repo mounted	Host files, host processes, host credentials.	a short Dockerfile
Container + no network	Also stops exfiltration and `web_fetch`.	install deps first

crab deliberately does not ship an OS sandbox. sandbox-exec is deprecated on macOS; landlock/seccomp on Linux is a second platform-specific implementation for a half-real sandbox with a large escape surface. Two code paths for a false sense of safety is the worst trade in the document — and the binary being a single file makes the container answer cheap.

Secrets

~/.crab/config.toml holds API keys in plain text, mode 0600. Keep it outside any directory you point the agent at.
Environment variables are inherited by bash calls. If a key is in your shell, the agent can read it with env.
Prefer scoped, short-lived keys. Rotate after a long --yolo session if you are unsure what ran.

Prompt injection

crab reads files and fetches URLs. Both can carry instructions. There is no classifier between a README and the model, so the realistic defences are procedural:

Point web_fetch at documentation, not at issue threads from strangers.
Read the trace after a run that touched unfamiliar input; tool lines show what was actually called.
Keep the working directory narrow, so a steered agent has less to reach.
Run without network in the container when the task does not need it.

MCP servers are code

Every server in [mcp.*] is a child process started with your permissions, and its tool descriptions are injected into the model's context. Treat installing one the way you treat installing a CLI: read what it does first. crab reports a server that fails to start, but it cannot audit what a working one does with the tools it is given.

Reporting

Security issues that are not already public should go to security@crabagent.ai rather than the issue tracker.

← PreviousTrace & metrics Next →Command reference