realm

Sandboxed Docker environments for git repos — safe playgrounds for AI coding agents.

My usage

> ls -al | grep Dockerfile
.rw-r--r--@ 2.2k yusuke  8 Feb 10:42 Dockerfile

# build my own image for sandbox
> docker build -t mydev

# run
> docker run -it mydev

# process your auth of claude
% claude
% exit

# save image for my auth action for claude
> docker commit <container_id> mydev:authorized

# put my dev image for realm in .zshrc
> export REALM_DEFAULT_IMAGE=mydev:authorized

# Then, you can use realm for claude conveniently
> realm new-quality-improvement

# you can immediately run claude
% claude

Why realm?

AI coding agents (Claude Code, Cursor, Copilot) are powerful — but letting them loose on your actual working tree is risky. Realm gives them a safe, isolated sandbox where they can go wild without consequences.

• Your code stays safe — only .git is mounted, host files are never modified
• AI agents can experiment freely — commit, branch, rewrite, break things — your working tree is untouched
• Persistent sessions — exit and resume where you left off, files are preserved
• Named sessions — run multiple experiments in parallel
• Bring your own toolchain — works with any Docker image

Quick Start

curl -fsSL https://raw.githubusercontent.com/yusukeshib/realm/main/install.sh | bash
realm my-feature --image ubuntu:latest -- bash
# You're now in an isolated container with full git access

Claude Code Integration

Realm is the ideal companion for Claude Code. Run Claude Code inside a realm session and let it make risky changes, experiment with branches, and run tests — all fully isolated from your host.

realm ai-experiment --image node:20 -- claude

Everything the agent does stays inside the container. When you're done, delete the session and it's gone.

Install

Quick install

curl -fsSL https://raw.githubusercontent.com/yusukeshib/realm/main/install.sh | bash

From crates.io

cargo install realm-cli

From source

cargo install --git https://github.com/yusukeshib/realm

Nix

nix run github:yusukeshib/realm

Binary download

Pre-built binaries are available on the GitHub Releases page.

Usage

realm                                               List all sessions (TUI)
realm <name> [options] [-- cmd...]                  Create or resume a session
realm <name> -d                                     Delete a session
realm upgrade                                       Upgrade to latest version

Create or resume a session

# Default: alpine/git image, sh shell, current directory
realm my-feature

# Specify a project directory (only used when creating)
realm my-feature --dir ~/projects/my-app

# Custom image with bash (only used when creating)
realm my-feature --image ubuntu:latest -- bash

# Custom mount path inside container (only used when creating)
realm my-feature --mount /src

# Environment variables (only used when creating)
realm my-feature -e KEY=VALUE -e ANOTHER_KEY

# If session exists, it resumes with original configuration
# If session doesn't exist, it creates a new one
realm my-feature

Sessions are automatically created if they don't exist. If a session already exists, create-time options like --image, --mount, --dir, and -e are ignored when resuming.

List sessions

realm

NAME                 PROJECT                        IMAGE                CREATED
----                 -------                        -----                -------
my-feature           /Users/you/projects/app        alpine/git           2026-02-07 12:00:00 UTC
test                 /Users/you/projects/other      ubuntu:latest        2026-02-07 12:30:00 UTC

Delete a session

realm my-feature -d

Options

Environment Variables

# Pass extra Docker flags
REALM_DOCKER_ARGS="--network host -v /data:/data:ro" realm my-session -c

How It Works

Realm mounts your repo's .git directory into a Docker container with a separate workspace. Your host working directory is never modified.

• .git-only mount — The container gets full git functionality (commit, branch, diff) without touching your working tree
• Isolated git index — Each container uses its own GIT_INDEX_FILE, so host staging is never leaked
• Persistent workspace — Files survive exit and realm <name> resume; cleaned up on realm <name> -d
• Automatic init — On first run, git reset --hard HEAD populates the working tree from the mounted .git
• Any image, any user — Works with root and non-root container images

License

MIT