npm version License: MIT Node.js

Auto-managed dev/test/staging environments for Claude Code. Orbit watches what you're doing and switches your environment to match — no manual Docker commands, no config juggling.

$ /orbit status
 Project: my-api (node)
 Env: test
 Backend: Docker Sandbox (microVM)
 Network: deny-all
 Sidecars: postgres (running), redis (running)
 Recent:
 14:02 Switched to test (task: "run unit tests")
 14:01 Started sidecar postgres
 14:01 Started sidecar redis

• How It Works
• Features
• Install
• Quick Start
• Commands
• Sidecars
• Docker Sandbox Integration
• Sandbox Configuration
• Updating
• Contributing
• License

Orbit has two halves:

• MCP Server — background daemon that monitors your Claude Code tasks, classifies them by environment (using Haiku), and spins up the right Docker containers automatically.
• Skill — /orbit slash commands for when you want direct control.

When you start writing tests, Orbit moves you to an isolated test container. When you're back to coding, it drops you into local dev. No prompts, no switching.

• Ambient switching — moves between local dev and Docker-based test/staging based on your current task
• Lazy sidecars — declares PostgreSQL, Redis, etc. in config; starts them only when the environment needs them
• Clean-room testing — runs tests in disposable Docker containers for real isolation
• MicroVM sandboxes — uses Docker Sandboxes (hypervisor-backed) when available, falls back to hardened containers
• Network policies — per-project allow/deny lists control what containers can reach
• Multi-runtime — supports Node.js, Python, Go, and Rust projects

/plugin marketplace add shihwesley/shihwesley-plugins
/plugin install orbit@shihwesley-plugins

Restart Claude Code to load the MCP server and hooks.

npm install -g @shihwesley/orbit
orbit setup

Creates ~/.orbit/, initializes the database, and registers the MCP server.

• macOS (primary target)
• Node.js >= 20
• Docker Desktop (for test and staging environments)
• Claude Code CLI

# Navigate to your project
cd ~/my-cool-project
# Initialize — auto-detects project type, creates .orbit/config.json
/orbit init
# That's it. Orbit is now watching your tasks.
# To manually switch environments:
/orbit switch test

Orbit detects your project type (Node, Python, Go, Rust) and writes a .orbit/config.json with sensible defaults.

Declare dependencies in .orbit/config.json:

{
 "type": "node",
 "sidecars": ["postgres", "redis"]
}

Orbit lazy-loads these containers when you enter test or staging. They stop when you switch back to dev.

Orbit integrates with Docker Sandboxes — microVM-based isolation built for coding agents. Each sandbox gets its own kernel via a hypervisor, so agents can run arbitrary code without touching the host.

When you switch to test, Orbit:

1. Detects if Docker Sandboxes are available
2. Creates a microVM with only your project workspace mounted
3. Applies network policies from .orbit/config.json
4. Falls back to hardened containers (cap_drop ALL, read-only rootfs, no-new-privileges) on Linux or older Docker Desktop

Agents can docker build and docker run inside the sandbox — they hit an isolated Docker daemon, never the host.

Control network isolation per-project in .orbit/config.json:

{
 "type": "node",
 "sidecars": ["postgres"],
 "sandbox": {
 "network": {
 "mode": "allow",
 "allow": ["registry.npmjs.org", "github.com"]
 }
 }
}

Docker Sandboxes require Docker Desktop with sandbox support (macOS/Windows). Linux uses hardened containers automatically.

Plugin:

Updates arrive through the marketplace. Run /plugin marketplace update to check.

npm:

npm install -g @shihwesley/orbit@latest
orbit setup

Restart Claude Code after updating.

Bug reports and PRs welcome at github.com/shihwesley/Orbit.

For development:

git clone https://github.com/shihwesley/Orbit.git
cd Orbit/orbit-mcp
npm install
npm run dev

MIT