realm

Sandboxed Docker environments for git repos.

How it works

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

• .git-only mount — The container gets full git functionality (commit, branch, diff) without touching your working tree
• Session isolation — Each session works independently inside the container
• Host stays clean — After container exit, realm runs git reset to fix the host index

Install

From source (requires Rust toolchain)

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

From crates.io

cargo install realm-cli

Usage

realm                                               List all sessions
realm <name> [-- cmd...]                            Resume a session
realm <name> -c [options] [-- cmd...]               Create a new session
realm <name> -d                                     Delete a session
realm upgrade                                       Upgrade to latest version

Create a session

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

# Specify a project directory
realm my-feature -c --dir ~/projects/my-app

# Custom image with bash
realm my-feature -c --image ubuntu:latest -- bash

# Build from a Dockerfile
realm my-feature -c --dockerfile ./Dockerfile -- bash

# Custom mount path inside container
realm my-feature -c --mount /src

# -c flag works in any position
realm -c my-feature --image ubuntu:latest -- bash

Resume a session

realm my-feature

The container resumes with the same configuration from the original session.

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

This deletes the session metadata.

Options

Session Storage

Sessions are stored in ~/.realm/sessions/{name}/ with:

• project_dir — Absolute path to the git repo
• image — Docker image used
• mount_path — Container mount path
• created_at — Timestamp of session creation
• resumed_at — Timestamp of last resume (if applicable)
• dockerfile — Path to Dockerfile (if --dockerfile was used)
• command — Saved command args (if provided)

Environment Variables

Examples:

# Always use your custom Dockerfile
export REALM_DOCKERFILE=~/my-realm/Dockerfile

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

Security Model

License

MIT