Getting Started

Prerequisites

Container Runtime

You need a container runtime on your machine. Either Docker or Podman will work.

Docker

Platform	Install
macOS	Docker Desktop for Mac
Windows	Docker Desktop for Windows (WSL2 backend)
Linux	Docker Engine or Docker Desktop for Linux

Verify it’s working:

docker --version
docker compose version

Podman

Platform	Install
macOS	Podman Desktop for Mac
Windows	Podman Desktop for Windows
Linux	Podman + Podman Compose

Verify it’s working:

podman --version
podman-compose version

Linux only

Podman on Linux runs containers directly (no VM). Ensure the Podman socket is active so podman-compose can connect:

systemctl --user enable --now podman.socket

System Resources

Resource	Minimum	Recommended
Disk	5 GB	10 GB+
RAM	8 GB allocated to container runtime	12 GB+
CPU	2 cores	4+ cores

Docker

Adjust resource limits in Docker Desktop → Settings → Resources.

Podman

On macOS/Windows, adjust resource limits in Podman Desktop → Settings → Resources, or via the CLI:

podman machine set --cpus 4 --memory 12288
podman machine stop && podman machine start

On Linux, containers share host resources directly — no resource configuration is needed.

1. Set Up

Create a folder and download the compose file:

mkdir devcontainer && cd devcontainer
curl -fsSLO https://raw.githubusercontent.com/f5xc-salesdemos/devcontainer/main/docker-compose.yml

2. Add Your Auth Credentials (Optional)

Create a .env file in the same folder to pre-configure Claude Code. Choose one of the following options:

Option A: Claude Max (OAuth)

CLAUDE_CODE_OAUTH_TOKEN=sk-ant-oat01-your-token-here

Option B: LiteLLM or Anthropic-compatible proxy

If you have a LiteLLM instance or other Anthropic-compatible proxy, set these two variables:

LITELLM_BASE_URL=https://your-litellm-endpoint.example.com
LITELLM_API_KEY=your-api-key

Set the domain only — the container derives provider-specific URL suffixes automatically (e.g. /anthropic for Claude Code, /api/v1 for OpenCode).

Auto-populate from local credentials

If you have git and gh configured on your host, you can populate most .env values automatically. Start by copying the template:

cp .env.example .env

Then run whichever commands match your setup:

# Git identity
echo "GIT_AUTHOR_EMAIL=$(git config user.email)" >> .env
echo "GIT_AUTHOR_NAME=\"$(git config user.name)\"" >> .env

# Timezone
echo "TZ=$(readlink /etc/localtime | sed 's|.*/zoneinfo/||')" >> .env

# GitHub CLI token (requires: gh auth login)
echo "GH_TOKEN=$(gh auth token)" >> .env

# SSH key (if you use SSH for git)
echo "SSH_PRIVATE_KEY=$(base64 < ~/.ssh/id_ed25519)" >> .env

Then edit .env to add your OAuth token or LiteLLM proxy settings (see options above).

AI assistants

The .env.example file contains @auto-detect markers on every variable that can be populated from local tools. AI assistants like Claude Code can scan for these markers and run the associated commands to build a complete .env automatically.

3. Start

Docker

docker compose up -d

Podman

podman-compose pull && podman-compose up -d

The first run pulls the pre-built image from ghcr.io (~1 min depending on your connection). Subsequent starts use the cached image and take seconds.

4. Connect

Docker

docker compose exec dev zsh

Podman

podman-compose exec dev zsh

5. Verify

# AI tools
claude --version
opencode --version
codex --version
aider --version
pi --version

# Languages
node --version
python3 --version
go version

# Cloud CLIs
aws --version
az --version
terraform --version

Test the AI connection:

claude -p "Say hello"

6. Your First Project

cd /workspace
git clone https://github.com/your-org/your-project.git
cd your-project
claude

7. Remote Display (noVNC)

The container includes a virtual display for watching AI agents control a browser. Open http://localhost:6080/vnc.html to connect. See Remote Display (noVNC) for details.

8. Browser Automation (Chrome DevTools MCP)

Claude Code can navigate web pages, take screenshots, and inspect the DOM using the built-in Chrome DevTools MCP server. No setup needed — it works automatically in headless mode. See Chrome DevTools MCP for details.

9. Stopping and Restarting

Docker

# Stop (preserves data)
docker compose down

# Start again
docker compose up -d

# Destroy everything and start fresh
docker compose down -v
docker compose up -d

Podman

# Stop (preserves data)
podman-compose down

# Start again (pull ensures latest image)
podman-compose pull && podman-compose up -d

# Destroy everything and start fresh
podman-compose down -v
podman-compose pull && podman-compose up -d

Your code in /workspace and home directory persist across restarts. See Configuration — Data Persistence for details.

---

For local builds and Dockerfile customization, see Local Development. For VS Code integration, see VS Code. For remote display options, see Remote Display (noVNC).