Secure agent workstation

A coding agent runs shell commands and edits files on your machine. That is the point — and the risk. An agent with your full user privileges can, by mistake or through a poisoned instruction, delete files, exfiltrate secrets from your environment, or reach other machines on your LAN. Design-partner teams flagged this as an explicit concern; treat it as a setup prerequisite, not an afterthought.

The goal: an agent should not be able to damage the dev station or the local network. Defence in depth, cheapest first.

1. Run under a least-privilege local account

Don't run agents as your primary user or as an administrator.

• Create a dedicated, non-admin local account for agent work. It should own only the repos it needs and have no access to your personal files, SSH keys, or password manager.
• macOS/Linux: a standard (non-sudo) user. Keep agent repos under that user's home; don't grant passwordless sudo.
• Windows: a Standard (not Administrator) account, working inside WSL2 (see Windows setup).
• Scope credentials tightly: put only CONSTELLATION_API_KEY (and other per-project tokens) in that account's environment. Keep long-lived cloud credentials out of it.

2. Use your client's sandbox and permission modes

Every supported client can gate what runs without asking:

• Claude Code — keep the default permission prompts on; approve commands rather than enabling blanket auto-run. Use an allow/deny list in .claude/settings.json (or settings.local.json for personal overrides) to auto-allow known-safe read-only commands and deny destructive ones. Prefer the sandboxed execution mode where available.
• Cursor / Codex — enable their equivalent command-approval / restricted execution modes. Do not enable "run everything automatically" on a workstation that holds anything you cannot lose.
• Scope the MCP token — mint a short-lived API key for agent sessions and revoke it when done. Constellation keys are revocable immediately (a revoked key stops working within ~30 seconds). Never paste a token into a file; the starter kit reads it from CONSTELLATION_API_KEY.

3. Isolate with a devcontainer or VM

The strongest control is to not give the agent the host at all.

• Devcontainer (recommended default). The starter kit emits a .devcontainer/devcontainer.json that runs as the non-root node user, drops all Linux capabilities (--cap-drop=ALL), and sets no-new-privileges. The agent sees only the mounted repo and the tools you provision — not your home directory or your other projects. See Windows setup → devcontainer (the same path applies on macOS/Linux with Docker + the Dev Containers extension).
• VM. For higher assurance, run the agent in a disposable VM (or a cloud dev environment). Snapshot before a session; discard after.
• Restrict the network. An agent rarely needs your whole LAN. In a devcontainer or VM, limit egress to what it needs (your Git host, the package registry, and the Constellation MCP endpoint). Don't run agent sessions on a host that also has unauthenticated access to production systems or internal admin panels.

4. Operational hygiene

• Keep .mcp.json gitignored. The generator does this for you; don't commit it or the token.
• Review diffs before pushing. The agent proposes; you decide what merges. The task lifecycle keeps a human in the loop at the PR.
• Prefer per-project tokens over one all-powerful credential, so revoking one doesn't disrupt everything.
• Watch for the hosted path. Longer term, hosted/sandboxed agent execution removes the workstation from the trust boundary entirely; the queue-based assignable-agent runtime is the first step in that direction.

Checklist

• Agents run under a dedicated non-admin account (or a devcontainer/VM).
• Client permission prompts / sandbox mode are on; destructive commands are denied by default.
• The MCP token is short-lived, read from the environment, and revocable.
• Repo work is isolated from personal files, SSH keys, and production creds.
• Network egress from the agent environment is limited to what it needs.