Agent workspaces

Set one up

1. Make it: parallex agent new reviewer --email reviewer@example.com --repo acme/api --allow github.com --allow api.anthropic.com, or New Agent Workspace in the app. Add --browser chrome for a Chrome of its own.
2. Add its signing key on GitHub: parallex agent key reviewer prints the public key. Add it as a Signing Key on the account whose verified email its commits use, and its commits show as Verified.
3. Give it a GitHub token: parallex agent github reviewer opens GitHub's new fine-grained token page with the name, owner, expiry and permissions filled in. Pick its repositories there (GitHub doesn't let a link choose them), generate the token and paste it. It goes to the agent's own gh config, not the keychain, and never to Parallex.
4. Run it: parallex agent run reviewer --in ~/code/api -- claude -p "review PR 12". It runs as the agent, through its network rules, after a snapshot.
5. See what it did with parallex agent report reviewer, and put it back with parallex agent rewind reviewer.

Sealed: a macOS sandbox for each run

With Sealed on (the default for new agents), parallex agent run starts the agent through macOS's own sandbox, with a profile Parallex writes for that run. It can read and write the folder you run it in and its own home, and read its signing key, the tools it needs (nvm, Claude Code, Bun, cargo, rustup, Go, pyenv, Volta, a Homebrew in your home) and any folder you grant it, read only or read and write. It can't read the rest of your home folder: your documents, other repositories, dotfiles, SSH keys, cloud and registry sign-ins. It can't read your keychain, Parallex's own folder, or other programs' temporary files, and it can't write anywhere else, your tools and apps included.

It can't open apps, read your clipboard, change settings, or signal or look at your other programs: macOS services are limited to a short allowlist, taken from Codex's own sandbox policy. Its network goes through its proxy or nowhere, because macOS refuses any other connection and name lookups, with one exception: a Local servers switch, on unless it's offline, lets it reach what's listening on your Mac, like a dev server or a database, without going through the proxy (so a local proxy there could fetch onward for it), and lets it start servers, which can be reached from your network unless your firewall blocks them. Turn it off when it doesn't need them.

A page it asks to open (to sign in, say) is never opened for it: your browser isn't behind its proxy and has your sign-ins. The run's terminal and its page in Parallex show the whole address, marked when it's outside its network rule, and opening it is your choice. Sign-ins that show a link or a code, like Claude Code's /login or codex login --device-auth, work that way.

• What it can reach: its page lists it plainly, with Grant Folder… for more and what the seal refused in its last run (from the system log, best effort). parallex agent show says the same, and parallex agent check --sealed runs a real sealed run on your Mac and tries each way out from inside it.
• Git: in the folder it works in, .git/hooks and .git/config stay read only, and it can't make a new repository there. Its own git runs with no hooks at all.
• Sign-ins: turning Sealed on copies the agent's own Claude Code sign-in from the keychain into a file in its home (macOS may ask once), so it stays signed in. If that's declined, sign it in once inside the seal.
• Codex and Claude Code: macOS's sandbox can't be nested, so inside the seal Codex runs its commands without a sandbox of its own and Claude Code's /sandbox is off. The seal around them is stricter about what can be read.
• Agents made before Sealed: their page offers to turn it on, once. Nothing changes until you say so.

What Sealed isn't

It isn't a VM. It runs as you on your Mac's kernel, so a bug in macOS's sandbox could let it out. Apple marks the sandbox tool deprecated: Parallex tries it before every sealed run, and if it stops working, the run is refused rather than run unsealed. It can read anything you grant it, and files outside your home that any program can (like /Applications). What it writes into your repository runs as you when you run it, so review its work before you run it.

What it has of its own

• Git: commits as "reviewer (agent)", signed with an ed25519 SSH key kept in its own folder. Its git config holds nothing of yours, and its runs read only that file. Its one credential helper, for every host, gives the token in its own gh config and nothing else: none of your credential helpers.
• SSH: its git uses ssh with no config file, no SSH agent and no key files, so none of your Host aliases or SSH keys. GitHub's SSH addresses go over HTTPS with its own token. That's its git: a plain ssh, scp or rsync in a run can still use your SSH keys. Signing still works with its own key.
• GitHub: a fine-grained token limited to the repositories you picked, kept in its own gh config. Without one, its tools get a placeholder GitHub refuses, in GH_TOKEN and in its gh config for every host your gh knows, so they find it before they'd look in the keychain, and GitHub access is blocked. Your keychain itself is still readable by anything running as you, the agent included, if it tries.
• Claude Code and Codex: a config of its own (CLAUDE_CONFIG_DIR, CODEX_HOME): its own sign-in, history and settings, with your CLAUDE.md, skills and plugins shared if you like.
• A browser: optionally a Chrome of its own, outlined in the agents' red, signed in to nothing of yours.
• Shared: unsealed, everything else in your home, as with any workspace: it runs as you and can read your files and keychain if it tries. For a boundary, turn on Sealed. Either way it reads its own signing key, token and decoys (it has to, to use them). If you share your Claude setup with it, those shared files are yours: unsealed, what it changes there changes yours, and a rewind doesn't undo it; sealed, it can only read them.

Network rules, and their limits

Each agent is online, limited to some hosts (and their subdomains), or offline. Parallex keeps the rule with a proxy on your Mac, started for each run and given to its tools, with a password made for the run, through HTTP_PROXY, HTTPS_PROXY, ALL_PROXY and git's own setting. git, gh, curl, npm, pip, Claude Code and Codex keep to it, like other tools that use a proxy when told to, and connections it refuses are logged. A host that isn't a plain host name is refused, and a plain HTTP connection carries one request.

Unsealed, a program that ignores those variables can go around the proxy; sealed, macOS refuses any connection that doesn't go through it, except to what's listening on your Mac while Local servers is on. The agent's browser isn't covered. HTTPS isn't opened: the proxy sees which host is asked for, never what's sent.

Snapshots, reports and the kill switch

Before every run, Parallex takes an APFS snapshot of the agent's own state: its git and gh settings, sign-ins, and Claude Code and Codex config and history. Not your repositories: for those, the report lists the agent's commits, and git can undo them. Its GitHub token is never in a snapshot, so a rewind keeps the one it has. Rewinding refuses while the agent runs, never writes through a link, and keeps what it replaces. Deleting an agent removes its signing key, its token and its Claude Code sign-in for good; revoke the token and key on GitHub too. In a repository whose own git config holds a token (in a remote URL, say), the agent's git uses it there, as git does; parallex agent run warns when it sees one.

A run's report comes from the agent's own Claude Code transcripts and Codex sessions (the files they read and edited and the commands they ran), the hosts in its proxy log, and the git commits made in the folder it ran in. It lists those sources. It isn't a full audit of your Mac: a program can read files or reach the network without showing up in any of them, and the transcripts are the agent's own files, which it could change.

parallex agent pause --all, the menu bar or a shortcut you choose pauses the processes Parallex has seen an agent run start, including detached ones it saw, and cuts their network. Parallex records a run's processes a few times a second, with their start times, so a program that drops the run's tag (as Node, Bun and Python do for their children) is still caught; one started and detached between two looks can slip through, and so can apps opened through macOS (open, LaunchServices). While a run goes on, Parallex holds the pause itself, so deleting the pause file doesn't bring the network back; only a resume from outside the run does. A process of the agent's that pause never saw could still send one, so this guards against accidents, not a determined agent. The shortcut only pauses; resume from the menu bar or the command line. Optionally, decoy credentials in an agent's home flag any attempt to read or use them.

From Claude Code and Codex

Parallex's MCP server lets Claude Code, Codex and other MCP clients list workspaces, open a clean browser or a throwaway copy of an app, snapshot an agent, read a report, and ask who they're running as. Rewinding asks you first, in clients that support it. Add it with claude mcp add parallex -- parallex mcp, or in Codex's config.toml under [mcp_servers.parallex] with command = "parallex" and args = ["mcp"]. It redacts the secrets it recognises from its answers.

Inside an agent run, the MCP server keeps to that agent's network rule: a clean browser or a throwaway copy only when the agent is online, or a browser for an address on its allowed hosts, and neither goes through the agent's proxy. Reports from inside an agent are that agent's own.

Also