GRITZ

Runs coding agents (Claude Code, Codex, Cursor, GitHub Copilot) inside remote sandboxes.

• Self-hosted runners - Run agents on your own infrastructure inside Docker containers
• Third-party integrations - Interact with agents via GitHub and Jira events
• MCP server - Create and manage tasks from Claude Code, Cursor, or any MCP client

Install gritz cli:

mise run install

Download the pre-built binaries (if needed):

gritz download

Create an API key in the Web UI (https://gritz.dev/ui/keys/new) and copy the returned xat_… value into ~/.config/gritz/config.yaml:

token: xat_...

Create a workspaces.yaml file (see examples below):

vim ~/.config/gritz/workspaces.yaml

Start the local runner:

gritz runner

Create and monitor tasks via the Web UI.

Open: https://gritz.dev/

See examples/workspaces/ for workspace configuration examples:

• claude.yml - Claude Code
• codex.yml - OpenAI Codex
• cursor.yml - Cursor Agent
• copilot.yml - GitHub Copilot
• mcp-server.yml - MCP server configuration
• private-repo.yml - Cloning private repositories
• dummy.yml - Dummy agent for testing

See examples/runner/ for running the runner as a Docker Compose service with a pull-through registry cache.

View container logs:

gritz logs -f <taskid>

Set verbose: true on a workspace's agent to bypass the CLI output parser and log every raw line. Useful when the parser is hiding details (errors, intermediate output, tool-use payloads) you want to inspect via gritz logs.

agent:
  type: claude
  verbose: true

Get a shell to a task container:

gritz shell <taskid>

List task containers:

gritz containers

# Start server and postgres locally
docker compose up -d

# Run the FE
cd webui
pnpm install
pnpm run dev

The local server runs with --no-auth, but the runner still requires an API key. Create one in the local Web UI at http://localhost:5173/ui/keys/new, then start the runner:

gritz runner --server http://localhost:6464 -key <api-key>

mise run build      # Build main + prebuilt binaries (linux amd64/arm64)
mise run generate   # Generate protobuf code
go build            # Build main binary only

Agents can attach links to their tasks for external resources they create (PRs, Jira issues, etc.). Links created with subscribe=true act as subscriptions. When a new event occurs on the resource, the agent is automatically restarted to respond.