Getting Started
Prerequisites
Section titled “Prerequisites”- Git — required for worktree support
- Docker
- An agent CLI account — Claude Code (Anthropic) or Codex (OpenAI)
Choose your binary
Section titled “Choose your binary”| I want to… | Download |
|---|---|
| Use the web dashboard | warden-desktop |
| Use the terminal UI | warden-tui |
| Integrate into my own app | warden |
Download the installer for your platform from the releases page. See Installation for platform-specific instructions.
Run it
Section titled “Run it”# Web dashboard — opens in your browser at 127.0.0.1:8090./warden-desktop
# Or TUI — opens in your terminal./warden-tui
# Headless server for developer integration./wardenThe container image is pulled automatically from ghcr.io/thesimonho/warden on first use.
Create your first project
Section titled “Create your first project”When creating a project, the first field is the agent type — choose between Claude Code and Codex. Each project is locked to one agent at creation time.
Fill in the project name and either a host path (local directory) or a clone URL (remote git repository), configure environment variables and other settings, then create. Warden pulls the container image (if needed) and starts the project. Remote projects clone the repository inside the container on first boot.
The Runtimes section lets you select language runtimes to install in the container (Python, Go, Rust, Ruby, Lua). Warden auto-detects which runtimes your project needs by scanning for marker files like go.mod or pyproject.toml. Node.js is always included (required for MCP servers). Each runtime also adds its package registry domains to the network allowlist when using restricted mode.
Authentication
Section titled “Authentication”Claude Code
Section titled “Claude Code”API key: Pass ANTHROPIC_API_KEY as an environment variable when creating the container.
Subscription login: Open the terminal and run claude — it prompts you to authenticate via browser. Authentication persists across restarts.
API key: Pass OPENAI_API_KEY as an environment variable when creating the container.
Subscription login: Authenticate on your host machine first by running codex login. Because Warden mounts ~/.codex into the container, the auth token is shared automatically — no need to authenticate again inside the container.
Agent config directories
Section titled “Agent config directories”Warden automatically mounts your host’s agent config directory into every container. This mount is required and cannot be removed — the agent needs it for authentication, session tracking, and configuration.
- Claude Code:
~/.claude(auth, skills, MCP plugins, settings) - Codex:
~/.codex(auth tokens, agent configuration)
The host path is editable if you want to point to a non-standard location.
Environment variables
Section titled “Environment variables”Any env var set at container creation is forwarded into the shell session — useful for GITHUB_TOKEN, GIT_AUTHOR_NAME, etc.
Next steps
Section titled “Next steps”Explore Warden’s feature set:
- Projects — container configuration, environment, mounts, and lifecycle
- Worktrees & Terminals — isolated workspaces with persistent terminal sessions
- Access — credential passthrough from host to container
- Network Isolation — control outbound traffic (full, restricted, or air-gapped)
- Cost & Budget — per-project spending limits and enforcement
- Audit Logging — event logging for monitoring and compliance
- Custom Images — bring your own image (Dockerfile, devcontainer feature, or fully custom)
- Integration Paths — embed Warden in your own application