Installation

Prerequisites

• Docker or Podman
• git

md uses Docker when both runtime commands are installed. It selects Podman automatically only when the docker command is not installed. Pass the global flag --runtime docker or --runtime podman before a command to select one explicitly. Use --runtime podman when a Podman compatibility shim provides the docker command.

Platform-specific notes

Platform	Recommendation
Linux	Docker Engine or Podman. Rootless Podman is supported.
macOS	Docker Desktop.
Windows	Docker Desktop with WSL2 backend. Run md from inside the WSL2 Linux distribution.

Docker Desktop alternatives haven't been tested. Please let us know if you run into issues.

Install

curl -fsSL https://caic.xyz/install.sh | bash

This installs both caic and md binaries to ~/.local/bin/.

Verify

md version

# Quick smoke test
md run -- echo "md works"

Install from source

Dependencies

• Go (recent version)
• Docker or Podman

Build and install

go install github.com/caic-xyz/md/cmd/md@latest

Recommended: Also install git-maruel for the git squash and git rb helpers.

Upgrading

curl -fsSL https://caic.xyz/install.sh | bash

Existing containers continue to work after upgrading. The container image is rebuilt on the next md start if the base image has changed.

To force a rebuild with the latest base image:

md prune    # remove unused md images and build caches from installed runtimes
md start    # will pull latest base and rebuild

Uninstalling

# Purge all md containers first
for name in $(md list --json | jq -r '.[].name'); do
  md purge "$name"
done

# Remove md-specialized-* images
md prune

# Remove binaries
rm ~/.local/bin/md ~/.local/bin/caic

Next steps

• Commands: full command reference
• Configuration: caches, environment variables
• Harnesses: agent-specific setup and persisted configuration
• Tailscale: remote access over your tailnet