Run coding agents in a sandbox, not on your machine.

AGRO gives AI coding agents a workspace you control. It packages a Docker sandbox and shared agent procedures. Run one or more coding harnesses side by side in one workspace, for example Claude Code, Codex, and Pi. AGRO supports every harness in the harness table below.

Develop on your laptop or a remote VM. Install tools and harnesses on demand, organize parallel changes in separate git worktrees, and use shared skills and evidence checks to guide the work.

Start with the quickstart below. See the documentation for more guidance.

📦 Quickstart

Try AGRO in GitHub Codespaces

AGRO runs one project in one Docker sandbox, and agro is the only front door. Host prerequisites: Docker (with the Compose plugin), Git, and Node.js ≥ 22.

1. Get agro

npm — you already have Node ≥ 22:

# Install globally
npm install -g @mifune/agro

# Or run without a global install
npx @mifune/agro --help

Use npx @mifune/agro in place of agro in later commands.

curl

# Install AGRO to ~/.local/bin; offers Node.js setup if needed
curl -fsSL https://github.com/mifunedev/agro/releases/latest/download/install.sh | bash

For a download-and-review alternative, see Installation.

Check the installed version, update AGRO, or see available commands:

# Check the installed version
agro --version

# Update AGRO
agro update

# Show available commands
agro --help

2. Create the sandbox

agro sandbox install docker runs from any directory and needs no project checkout.

Set up the sandbox, then enter it. For checkout and persistent home options, see Create the sandbox.

# Create a sandbox with the setup wizard
agro sandbox install docker

# Enter the sandbox; replace <name> with your sandbox name
agro shell <name>

--checkout and --home-mount bind different paths, so one command can carry both.

--repo is a deprecated alias for --checkout.

3. Install tools

Inside the sandbox, start with Herdr, the terminal workspace for your agents and development tools:

# Install and open Herdr
agro tool install herdr
herdr

Run the remaining commands in a Herdr pane. Install only the tools you need:

Tool	Purpose	Availability
herdr	Interactive terminal workspace	Install on demand
agent-browser	Browser automation	Install on demand
cloudflared	Public tunnels for local apps	Install on demand
microsandbox	MicroVM runtime CLI	Install on demand
tailscale	Private network connectivity	Install on demand
gh	GitHub CLI	Included
docker-cli	Docker client and Compose	Included

# List tools and check availability
agro tool list

# Install an optional tool
agro tool install <id>

GitHub (optional): authenticate before repository work that uses GitHub. Confirm that the status output shows your intended account.

# Sign in and configure Git credentials
gh auth login
gh auth setup-git

# Verify your account
gh auth status

See GitHub authentication for help.

4. Install a coding harness

Choose one harness to start. In a Herdr pane, install and authenticate it:

# List available harnesses
agro harness list

# Install Claude Code
agro harness install claude

# Sign in and verify authentication
claude auth login
claude auth status

# Start Claude Code
claude

Harness	ID	Availability
Claude Code	claude	Install on demand
Codex	codex	Install on demand
Pi	pi	Install on demand
Roder	roder	Install on demand
OpenCode	opencode	Install on demand
OpenClaw	openclaw	Install on demand
Grok Build	grok	Install on demand
Hermes	hermes	Install on demand
Muse Code	muse	Install on demand
Antigravity CLI	antigravity	Install on demand

Use agro harness install <id> to install any harness in the table. Follow the linked guides for authentication and launch commands. T3 Code requires an authenticated Claude Code, Codex, or OpenCode provider.

5. Track your harness changes (optional)

With your coding harness and GitHub CLI configured, ask the agent to create a repository for your harness changes. We recommend private visibility by default, with origin pointing to your repository:

Create a private GitHub repo for my harness changes and set it as origin.
Verify my account, exclude secrets and runtime files, and preserve existing work.
Confirm the repo name, files, and any remote replacement before creating or pushing.

Configure https://github.com/mifunedev/agro.git as upstream, preserving my origin.
Check shared history; if unrelated, use a separate checkout inside the sandbox.
Include only my selected changes, exclude private data, and confirm before pushing or opening a PR.

See the contributing guide for the full workflow.

6. Configure messaging (optional)

Run setup inside the sandbox from a Herdr pane. Use a separate Slack app and configuration for each gateway. We recommend opening another Herdr pane to attach to its tmux session; detach with Ctrl-b d to leave the gateway running.

Hermes

# Install Hermes and configure its provider
agro harness install hermes
hermes setup

# Generate the Slack app manifest and print its location
hermes slack manifest --agent-view --write

Open Slack Apps, choose Create New App → From an app manifest, and paste the generated JSON. Review its permissions, then install the app to your workspace. Collect the bot token (xoxb-) and an app-level token (xapp-) with connections:write scope.

# Enter the Slack tokens and configure access rules
hermes gateway setup

# Start the Hermes gateway and check its status
agro gateway hermes
agro gateway status

# Attach read-only from a Herdr pane; detach with Ctrl-b d
tmux attach -r -t client-slack-hermes

Send the bot a message and confirm a reply. See the Hermes Slack setup guide and gateway documentation.

Pi

In Slack Apps, create an app From an app manifest using Pi's manifest. It configures Socket Mode, events, and admin commands. Review permissions, install the app, and collect its own xapp- (connections:write) and xoxb- tokens.

# Install Pi, then use /login in Pi and exit back to the shell
agro harness install pi
pi

# Save Pi's Slack tokens using hidden input prompts
cd /home/sandbox/harness
agro secret set PI_SLACK_APP_TOKEN
agro secret set PI_SLACK_BOT_TOKEN

# Start the Pi bridge and check its status
agro gateway pi
agro gateway status

# Attach read-only from a Herdr pane; detach with Ctrl-b d
tmux attach -r -t client-slack-pi

Message the bot and complete the trust challenge shown in the bridge. See the Pi Slack setup guide for token locations and access configuration.

7. Open the sandbox in VS Code (optional)

For a sandbox running on your local machine:

1. Install VS Code's Dev Containers extension.
2. On the host, run agro sandbox list. Confirm the status of your sandbox.
3. Open the Command Palette (Ctrl+Shift+P / Cmd+Shift+P).
4. Run Dev Containers: Attach to Running Container, then pick your sandbox.
5. With File → Open Folder, open /home/sandbox/harness, the ~/harness folder of the sandbox user.

Use Attach to Running Container, not Reopen in Container.

Complete the sandbox setup on your remote host first. Then, from VS Code on your local machine:

1. Install the Remote - SSH extension alongside Dev Containers.
2. Run Remote-SSH: Connect to Host and connect to your Docker host using user@host.
3. In the SSH-connected window, run Dev Containers: Attach to Running Container and select the sandbox on that host.
4. With File → Open Folder, open /home/sandbox/harness (~/harness for the sandbox user).

Connect over SSH to the host, not directly to the container. See the connection guide for more options.

8. Ask your agent to clone a project

From your agent session in ~/harness, ask:

Clone <owner>/<repo> into projects.

Example agent response after a successful clone:

Cloned <owner>/<repo> to ~/harness/projects/<owner>/<repo>. The clone is a separate repository with its own history and remote.

Then ask for an isolated workspace:

Create a worktree in <owner>/<repo> for issue #123.

Example agent response:

Created branch task/123-my-change and a worktree at ~/harness/projects/<owner>/<repo>/.worktrees/task/123-my-change.

Worktrees share the project's Git history but keep separate checked-out files. Each parallel agent gets its own branch and worktree, so agents do not overwrite each other's work. The agent manages these folders; you do not need to configure them manually.

After the pull request merges, ask:

Clean up the merged worktree for issue #123 in <owner>/<repo>.
Keep any uncommitted work.

📚 Table of Contents

Browse the documentation or jump to a topic below.

Topic	Documentation
Getting started	Quickstart · Installation
Sandbox setup	Create a sandbox · VS Code and SSH
Daily operation	Lifecycle commands, stopping, and cleanup
Terminal workspace	Herdr
Coding harnesses	Harness overview and setup guides
Configuration	Settings and secrets
Agent procedures	Shared skills and hooks · Directory layout
Integrations	GitHub · Slack · Langfuse

🤝 Contributing & community

Contributions, bug reports, and feedback are welcome.

Contributing guide · GitHub issues · GitHub Discussions

📄 License

Apache License 2.0 — copyright Ryan Eggleston, d/b/a Mifune Dev (mifune.dev). Prior MIT releases remain available under MIT; this change governs new code and future releases and does not revoke past grants.

Apache-2.0 covers the runtime, the agro CLI, container definitions, and the harness spec. The Mifune Console, the provisioning and fleet-management control plane, and billing / enterprise policy / RBAC / hosted operations are proprietary — see the license section.

Trademarks

Apache-2.0 §6 grants no permission to use the Mifune or AGRO names, logos, or trade dress (reasonable, customary use in describing the origin of the work is fine). Fork it, modify it, sell it — just don't present your fork as Mifune.

---

Documentation