supermu / security
Agents act with real authority.
We design like that's dangerous — because it is.
supermu supervises AI agents that run real commands on your machine. That power is the product, so its security model is a first-class part of the architecture — designed up front, written down in public decision records, and stated honestly, including the parts that aren't solved yet.
“Claiming isolation we do not have is worse than a precise boundary.”— from supermu's threat-model decision record
The baseline: local-first is a security posture
Everything — your sessions, history, workspaces, and state — lives on your machine in a local database. There is no supermu cloud, no account to breach, and no telemetry leaving your computer. The attack surface starts at the size of your own machine, not ours.
Your AI subscriptions stay where they are, too: supermu supervises the real Claude Code or Codex process using the login you already have. Your provider credentials never pass through us.
- ✓All state local, in SQLite — nothing synced anywhere
- ✓No cloud service, no supermu account, no telemetry
- ✓Local control only via a Unix socket, guarded by your OS user
- ✓Provider logins stay in the provider's own CLI
How the runtime restrains agents
The threat we take most seriously isn't a network attacker — it's a confused or prompt-injected agent acting with your own authority. The runtime is built around that assumption.
Default-deny permissions
One permission engine decides every action from who is asking, what they're targeting, and what they want to do. Agents get least privilege by default: they can work in their own session and raise attention, but acting on other sessions, spawning, or scheduling requires an explicit grant.
Identity is proven, not asserted
Local callers are identified by OS-verified peer credentials on the control socket, not by whatever name they claim. Agent sessions are bound to per-session tokens, so one session can't impersonate another. Every allow-or-deny decision is auditable.
Observed content is untrusted
Prompt injection is the top risk of agentic work: an agent reads a log line, a filename, or another session's output, and treats it as instructions. When one session observes another, supermu delivers that content explicitly framed as untrusted, with terminal control sequences stripped.
Observing and acting are separate powers
An agent that can watch other sessions can't also send them input unless you explicitly grant that combination. Watch-and-report is the default; watch-and-act is a decision you make.
Runaway control that loses nothing
Budgets and schedules cap how much an agent can do unattended, and the default response to a runaway session is pause, not kill — you inspect and decide with everything intact. These are supervisory controls for cost and attention, and we deliberately never present them as a security boundary.
An OS-level sandbox, per session
For sessions that warrant real containment, the runtime can launch them inside an OS-level sandbox (sandbox-exec on macOS, container or low-privilege user on Linux) with a profile you choose. This is the only mechanism we call containment — everything above it is control, not isolation.
Client apps and remote access
The Mac and iPhone apps are views into your runtime, not copies of it. The rules below govern every client, on every platform, from the first release.
No unauthenticated listener
Locally, the runtime is reachable only through a Unix socket protected by your OS user account. The network transport for remote clients is gated entirely behind device pairing — there is nothing to connect to anonymously, and the intended deployment keeps it inside your private VPN, never on the public internet.
Every device is explicitly approved
A new client pairing shows up as an approval in your workspace, the same way agent questions do. Until you approve it, it can do nothing. Each device holds its own keypair and must prove possession of its key when it connects.
Per-device capabilities
Devices don't all get the same power. Your phone can be allowed to read sessions, pause work, and approve or deny requests — without being able to open new shells — unless you decide otherwise.
Revocation that actually revokes
Revoking a device severs its live connections immediately, not just its next login. And because clients are stateless renderers, a lost or revoked device holds no session data of its own — your work and history live only in the runtime on your machine.
Using supermu securely
The runtime restrains what agents can do through supermu. What keeps you safe overall is the combination of those controls and how you run things. Six habits that matter most:
Keep the runtime private
Run supermu on your own machine and reach it remotely only over your own VPN (WireGuard, Tailscale). Don't expose it to the public internet — it isn't designed to be a public service.
Keep the agent CLIs' own guardrails on
supermu supervises Claude Code, Codex, and friends — it doesn't replace their permission systems. Their approval modes are your first line of defence; blanket auto-approve defeats them.
Treat approvals as decisions
The attention system exists so you approve less often but mean it more. If you find yourself rubber-stamping, tighten what agents can do instead of approving faster.
Scope what agents can reach
An agent session runs with your user's authority. Give long-running agent work its own narrowly-scoped credentials — a deploy key rather than your personal SSH key — and keep production secrets out of inherited environment variables.
Sandbox the risky work
Unattended, scheduled, or experiment-heavy sessions are the ones to run inside a sandbox profile. Interactive sessions you're watching need it less; agents acting alone at 3am need it most.
Assume anything an agent reads can influence it
Fetched pages, dependency install output, commit messages from strangers — all of it is potential instruction to a model. supermu frames cross-session content as untrusted, but the same skepticism applies to everything else in an agent's world.
What we don't claim
Security pages usually stop at the reassuring part. These are the boundaries as they actually stand — so your decisions are based on what's true, not what sounds good:
- —Sessions run as your user by default. Unless you opt a session into a sandbox, permissions restrain the runtime's control API — they do not contain a process that already has your account.
- —supermu is single-user by design. It has no multi-tenant isolation and shouldn't be shared between people who don't trust each other completely.
- —Sandbox profiles are yours to choose. The runtime provides the mechanism, but a correct profile depends on the workload, so we don't pretend a default profile would protect every case.
- —Remote connection integrity currently rests on your VPN plus per-device authentication at connect time; per-request signing is planned hardening, not a shipped feature.
- —Credential hygiene (per-agent keys, secret brokering, redaction of secrets from observed output) is a stated direction landing in phases — not all of it exists today.
Found something?
If you believe you've found a security issue in supermu or its clients, we want to hear about it before anyone else does. Email security@supermu.app and we'll respond promptly.