Overview
Swarm Security
Swarm is designed around local control and explicit approval. The runtime keeps provider credentials on the machine or host running swarmd, gates tool execution through permissions, and separates what an agent is allowed to do from how that agent is selected.
Security model
Swarm keeps control local and asks before higher-risk actions run.
local runtimeThe launcher, daemon, terminal UI, Desktop, and mobile web surfaces all connect to the same swarmd runtime you run.explicit approvalsHigher-risk tool calls pause for permission unless your policy says otherwise. Critical actions keep user-in-the-loop approval even when permission bypass is active.least privilegeSaved agents can be read-only or read/write, can have narrowed tool scopes, and can be reserved for primary, delegated subagent, or background use.Swarm is not a hosted agent that requires you to put every project and credential into a third-party workspace. You decide where the runtime runs and which providers, tools, workspaces, and hosts it can reach.
Credentials
Provider credentials are local runtime secrets.
Swarm uses /auth to connect provider credentials to the local runtime. Model catalog metadata is public metadata; it does not replace provider auth and does not contain your API keys or OAuth tokens.
secret storeSaved provider credentials are written to the local secret Pebble store at /var/lib/swarmd/swarmd-secrets.pebble, or inside an explicit --data-dir when one is configured.encrypted at restCredential records are sealed with XChaCha20-Poly1305 before they are written to local storage.provider authSupported providers are managed through /auth. Add only the credentials you intend Swarm to use.Permissions
Tool execution resolves to allow, ask, or deny.
read pathRead/search/list operations are low-risk defaults so agents can inspect the workspace before proposing changes.mutating pathWriting files, running shell commands, changing saved agents, launching subagents, or leaving plan mode follow the active execution contract and permission policy.policy rulesUse /permissions to review, allow, ask, deny, explain, reset, or temporarily bypass tool prompts.Bypass mode is a local trust switch, not a full removal of guardrails. Saved deny rules, built-in hard denies, subagent launch approval, plan-exit approval, and mutating agent-management approval still apply.
Agent boundaries
Agent mode and execution permission are separate controls.
modePrimary, subagent, and background describe how a saved profile is selected and used.executionRead-only, read/write, and plan-enabled behavior describe what the profile can attempt during a run.tool scopeEach agent can inherit policy, use a preset, or explicitly allow and deny tools. Prefer the smallest scope that fits the job.Example: a security research subagent can be read-only with search/list/read access, while a primary implementation agent can be plan-enabled and read/write. Both are saved agents, but they do not need the same authority.
Workspaces and hosts
Workspace and host boundaries define what Swarm can touch.
workspace rootsFile tools are scoped to the workspace roots available to the current run. Add directories deliberately; do not give agents broad filesystem access by habit.local containersContainers are the convenient isolation path when a job should run away from your main runtime. The built-in flow still mounts selected workspace paths and links the child back to the parent Swarm, so use a custom hardened container or VM for maximum isolation.managed hostsRemote Linux hosts extend the same runtime model. Treat each host as a machine you control and keep its credentials, access, and networking policy explicit.Limits
Swarm security controls reduce risk; they do not make agent work risk-free.
Agents still operate on real projects, real credentials, and real machines when you give them access. Review approvals, keep credentials narrow, use read-only agents for investigation, isolate risky work in containers or worktrees, and inspect changes before shipping them.