Set up and manage the Sentry development environment using devenv. Handles fresh setup, updating existing environments, starting dev services, and troubleshooting. Use when asked to "set up sentry", "setup dev environment", "get sentry running", "start dev server", "devenv setup", "devservices not working", "sentry won't start", or any development environment issue.
Walk the user through getting Sentry running locally. The full process from a bare machine takes 30-45 minutes — most of that is downloading dependencies and Docker images. Set expectations clearly at each step.
AL MCP: If the al MCP server is available, use al_search_docs and al_read_doc for detailed troubleshooting. The AL docs cover devenv, devservices, and common issues in depth. The AL server is part of the devinfra-mcp project — see that repo for setup instructions if the server isn't configured yet. The SSE endpoint is configured in .pi/mcp.json (pi) or .mcp.json / .cursor/mcp.json (Claude Code / Cursor).
Before doing anything, assess what's already installed. Run all of these:
# Check OS
uname -s && uname -m
# Check shell
echo $SHELL
# Check if devenv exists
which devenv 2>/dev/null || ls ~/.local/share/sentry-devenv/bin/devenv 2>/dev/null
# Check devenv version (outdated versions cause failures)
devenv --version 2>/dev/null || ~/.local/share/sentry-devenv/bin/devenv --version 2>/dev/null
# Check Docker runtime
docker context ls 2>/dev/null
docker info --format '{{.Name}}' 2>/dev/null
# Check OrbStack
which orbctl 2>/dev/null && orbctl status 2>/dev/null
# Check Colima
which colima 2>/dev/null && colima status 2>/dev/null
# Check direnv
which direnv 2>/dev/null
# Check if repo is already set up
ls .venv/bin/sentry 2>/dev/null && ls node_modules/.bin 2>/dev/null
Based on results, skip to the appropriate step. If everything is installed, jump to Step 6.
xcode-select -p 2>/dev/null || xcode-select --install
If not installed, the user must complete the interactive install dialog (~10 min). Wait for it.
which brew || /bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"
Ask the user which they prefer. Explain the tradeoffs:
| Runtime | Pros | Cons |
|---|---|---|
| Colima | Official Sentry recommendation, all scripts support it | Can have DNS issues on WiFi changes |
| OrbStack | Faster, lower resource usage, better UI | Some Sentry scripts assume Colima — may need workarounds |
If choosing OrbStack:
brew install --cask orbstack
Then start OrbStack from Applications. Verify: docker info
If choosing Colima:
Colima gets installed by devenv bootstrap — no separate step needed.
Important: Do NOT run Docker Desktop alongside either runtime — it causes conflicts.
# For external (non-Sentry-employee) contributors:
# export SENTRY_EXTERNAL_CONTRIBUTOR=1
curl -fsSL https://raw.githubusercontent.com/getsentry/devenv/main/install-devenv.sh | bash
This installs to ~/.local/share/sentry-devenv/bin/devenv.
The user's shell MUST have devenv on PATH and direnv hooked in. Check and fix:
# Check if already configured
grep -q "sentry-devenv" ~/.zshrc 2>/dev/null || grep -q "sentry-devenv" ~/.bashrc 2>/dev/null
If not configured, add to the appropriate shell config (~/.zshrc for zsh, ~/.bashrc for bash):
# devenv
export PATH="$HOME/.local/share/sentry-devenv/bin:$PATH"
# direnv
eval "$(direnv hook zsh)" # or: eval "$(direnv hook bash)"
Tell the user to restart their terminal (or source ~/.zshrc) after this change.
Minimum version changes frequently. If devenv is already installed, check it's not outdated:
devenv --version
If the version is old (e.g., < 1.22), upgrade:
devenv update
If devenv update itself fails because the version is too old, reinstall:
curl -fsSL https://raw.githubusercontent.com/getsentry/devenv/main/install-devenv.sh | bash
For a completely fresh setup, run bootstrap first:
devenv bootstrap
This is interactive (~5 min) — it prompts for SSH keys, coderoot directory, etc. It installs Homebrew, Colima, Docker CLI, and direnv.
After bootstrap completes, close and reopen the terminal.
This is the longest step. Tell the user:
This will take 10-20 minutes on first run. It installs Python, Node, all pip/npm dependencies, and runs database migrations. Subsequent syncs are much faster (2-5 min).
The .envrc runs Docker checks. If the Docker runtime isn't running, direnv will hang. Symptoms:
Control Philips Hue lights and scenes via the OpenHue CLI.