SuperHQ

What is SuperHQ?

SuperHQ runs AI coding agents inside isolated “real sandboxes” so the agents can work in a controlled environment instead of directly on your local machine. It orchestrates Claude Code, OpenAI Codex, and custom agents, each inside its own microVM.

The core purpose is to help you safely execute agent-driven code changes: your project mounts into the sandbox (at /workspace), changes are captured in an overlay until you approve them, and you can inspect a unified diff review before anything touches local files.

Key Features

• Per-agent microVM isolation: Each of Claude Code, Codex, and custom agents runs in its own microVM, keeping the workspace contained.
• Full Linux userland via a Debian VM: The sandbox is described as a Debian VM with package tooling like apt, plus npm and pip, so the agent has what it needs to install and run dependencies.
• Mounted project workspace at /workspace: Your project is mounted into the sandbox; agent edits target this mounted path.
• Overlay changes with approval gate: Changes made in the VM remain in an overlay until you approve them in the review panel.
• Unified diff review before applying locally: You can see a unified diff of what the agent changed and choose what to keep or discard.
• Opt-in port forwarding: Ports can be forwarded from the sandbox to the host only when you enable it (useful for dev servers, databases, and APIs).
• Checkpoint and rewind: You can stop and checkpoint the VM state and later resume; you can also fork a checkpoint to create a fresh branch.

How to Use SuperHQ

1. Install SuperHQ on macOS using the provided Homebrew commands (brew tap superhq-ai/tap and brew install --cask superhq).
2. Create a new workspace for your project (the UI indicates workspace creation and quick switching via keyboard shortcuts).
3. Start an agent (the interface lists Claude Code, OpenAI Codex, and support for custom agents) to perform coding tasks inside the sandbox.
4. Review changes in the review panel: inspect the unified diff and approve or discard changes before they are applied to your local files.
5. Use supporting sandbox controls as needed: enable port forwarding only when you need access to a service running in the VM, and checkpoint if you want to pause/resume or fork a clean branch.

Use Cases

• Safe agent-driven refactors for a local repo: Run an agent to modify code in an isolated Debian VM, review the unified diff, and approve only the parts you want applied to your local project.
• Dependency-heavy tasks without polluting your machine: Let the agent install and run tools using the sandbox’s Debian userland (apt, npm, pip) rather than installing packages directly on your host.
• Debugging with temporary dev servers: Enable opt-in port forwarding to access services (for example, a dev server or API) running inside the sandbox while you inspect behavior.
• Iterative experiments with checkpointing: Checkpoint a workspace state, try an approach, then rewind or fork the checkpoint to spin up a new branch for a different direction.
• Running custom workflows with custom agents: Use the “custom agents” option when you have an agent setup beyond Claude Code or Codex, while still keeping execution inside per-agent microVM sandboxes.

FAQ

• What does SuperHQ isolate? Each agent run (Claude Code, Codex, or a custom agent) is executed in its own microVM sandbox.

• Where does my project live during agent runs? Your project is mounted into the sandbox at /workspace.

• How are changes applied to my local files? Agent edits are kept in an overlay until you approve them in the review panel. A unified diff is shown so you can keep or discard changes before anything touches local files.

• Can the sandbox expose services to my host? Yes, but port forwarding is opt-in, enabled only when you choose to expose ports from the sandbox to the host.

• How do checkpoints work? You can stop a workspace and checkpoint the full VM state, resume later in seconds, and fork a checkpoint to start a fresh branch.

Alternatives

• Local agent workflows (run agents directly on your machine): These are simpler but generally lack the described microVM isolation, approval gating, and sandbox overlay model.
• Containerized development environments (e.g., Docker-based agent setups): Containers can isolate dependencies and tooling, but the specific overlay-approval flow and microVM checkpoint/rewind behavior may differ.
• Remote sandbox or hosted code execution platforms: These can provide isolation, but workflows and where code changes are reviewed/applied can vary from SuperHQ’s local project mount at /workspace with unified diff approval.
• IDE-integrated AI coding assistants without sandboxing: They focus on in-editor coding assistance; they may not provide per-agent VM isolation, diff review before applying to local files, or opt-in port forwarding tied to a sandbox runtime.