hero_claude

Orchestration layer for managing Claude Code sessions in isolated Docker containers. Each session gets its own container with a sandboxed copy of the selected repositories, rsynced from the host code root. Sessions expose both a JSON-RPC API and an MCP endpoint, and are managed through a web admin UI.

How It Works

Browser / MCP client / JSON-RPC client
        |
        v
hero_proxy (TCP) ──► hero_claude_ui.sock ──► Admin UI (HTML dashboard)
                                   └──► /rpc proxy ──► hero_claude_server.sock
                                                                |
                                                                v
                                                      Session Orchestrator
                                                        |        |
                                                   Docker    Docker
                                                 container  container
                                                 session_1  session_2

Session lifecycle

create ──► CREATED ──► start ──► RUNNING ──► finish ──► COMPLETING ──► COMPLETED
                                    │
                                    └──► stop ──► STOPPED ──► start (resume)
                                    └──► destroy ──► DESTROYED

1. session.create — allocates a session ID, rsyncs the selected repos from $CODEROOT into $BUILDDIR/<session_id>/code/, and records metadata in session.json.
2. session.start — launches a Docker container with the sandboxed workspace mounted. The container runs Claude Code using the host's ~/.claude credentials (mounted read-only).
3. session.sync — re-rsyncs repos into the running session (for picking up upstream changes).
4. session.exec — runs a command inside the container.
5. session.finish — commits changes to a feature branch and opens a pull request.
6. session.stop / session.destroy — stop or permanently destroy the container.

Directory layout

$CODEROOT/               # read-only host source — never written to
├── hero_lib/
├── hero_embedder/
└── ...

$BUILDDIR/               # per-session sandboxes
└── <session_id>/
    ├── code/            # rsynced repos (writable copy)
    ├── state/
    │   ├── session.json # status, branch, repos, timestamps
    │   └── container_id
    └── logs/
        ├── rsync.log
        ├── claude.log
        └── container.log

Inside each container:

/workspace/
├── code/      # bind-mounted from $BUILDDIR/<session>/code
└── .claude/   # bind-mounted read-only from host $CLAUDE_CONFIG_DIR

---

Architecture

Crate	Type	Description
hero_claude_server	binary	JSON-RPC 2.0 API + MCP endpoint, session orchestration
hero_claude_sdk	library	Generated typed client via openrpc_client! macro
hero_claude_ui	binary	Admin dashboard, /rpc proxy to server
hero_claude	binary	CLI — registers and manages services via hero_proc
hero_claude_examples	examples	SDK usage examples and integration tests

Sockets

All communication uses Unix Domain Sockets (no TCP):

Service	Socket
server	~/hero/var/sockets/hero_claude_server.sock
UI	~/hero/var/sockets/hero_claude_ui.sock

hero_proxy exposes the UI externally over TCP and routes all traffic through these sockets.

Environment Variables

Variable	Required	Description
CODEROOT	yes	Path to host directory containing all repos
BUILDDIR	yes	Path where per-session sandboxes are created
CLAUDE_CONFIG_DIR	no	Claude credentials dir (default ~/.claude)
HERO_CLAUDE_IMAGE	no	Docker base image (default hero-claude-sandbox:latest)
DOCKER_RUNTIME	no	Container runtime: docker or nerdctl (default docker)

Quick Start

# Add ~/hero/bin to PATH (one-time)
export PATH="$HOME/hero/bin:$PATH"

# Build and install binaries
make install

# Set required environment variables
export CODEROOT=/path/to/your/repos
export BUILDDIR=/path/to/build/dir

# Start all services
make run

# Check status
hero_proc list

# View logs
make logs       # server logs
make logs-ui    # UI logs

# Stop all services
make stop

API

The server exposes a JSON-RPC 2.0 API. Full spec: crates/hero_claude_server/openrpc.json.

Method	Description
server.info	Server configuration and status
server.health	Health check
session.create	Create a session and rsync repos
session.start	Start the Docker container
session.stop	Stop the container (resumable)
session.finish	Commit changes, open PR, clean up
session.destroy	Permanently remove session
session.sync	Re-rsync repos into running session
session.list	List all sessions
session.info	Get session details
session.logs	Get session logs
session.exec	Run a command in the container
repo.list	List available repositories
repo.info	Get repository details
logs.get	Get aggregated operation logs
logs.clear	Clear logs

Development

make check      # fast compilation check
make lint       # clippy
make test       # unit tests
make test-all   # all tests including integration
make rundev     # start with debug logging (debug build)
make restart    # stop + start