Set Up Sentry Development Environment
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).
Step 1: Detect Current State
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.
Step 2: Install Prerequisites (macOS)
Xcode Command Line Tools
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.
Homebrew
which brew || /bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"
Docker Runtime — OrbStack or Colima
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.
Step 3: Install devenv
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 .
Shell Configuration
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.
Verify devenv Version
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
Step 4: Bootstrap (First Time Only)
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.
Step 5: Sync the Environment
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).
If direnv hangs
The .envrc runs Docker checks. If the Docker runtime isn't running, direnv will hang. Symptoms:
direnv: ([...]/direnv export zsh) is taking a while to execute. Use CTRL-C to give up.
Fix: Start the Docker runtime first:
-
OrbStack: Open OrbStack.app or open -a OrbStack
-
Colima: devenv colima start
Then direnv allow again.
Chicken-and-Egg Problem
direnv checks node version and sentry installation. On a fresh setup, these don't exist yet, so direnv will fail. This is normal. Bypass direnv and run devenv sync directly:
~/.local/share/sentry-devenv/bin/devenv sync
Or if devenv is on PATH:
devenv sync
After sync completes, direnv allow should succeed.
If devenv sync fails
Common causes:
-
Outdated devenv — devenv update or reinstall
-
Docker not running — start OrbStack/Colima first
-
Network issues — retry; some downloads are large
Run devenv doctor for automated diagnosis.
Step 6: Start Services
First: Start Docker Images
devservices up
⏱️ First run: 5-10 minutes. It pulls many Docker images (PostgreSQL, Redis, Kafka, ClickHouse, Snuba, Relay, etc.). This is a one-time cost. Tell the user:
This is downloading all the Docker images Sentry needs. It looks like a lot — that's normal. Subsequent starts take ~30 seconds.
Subsequent runs: ~30 seconds.
OrbStack Socket Issue
If devservices up or devservices serve fails with:
Make sure colima is running. Run devenv colima start.
...but the user is using OrbStack, the devservices.py command is checking for the Colima socket only. Check src/sentry/runner/commands/devservices.py :
grep -n "colima|docker.sock|orbstack" src/sentry/runner/commands/devservices.py
The _find_docker_socket() function needs to check multiple socket paths. On macOS it should try, in order:
-
~/.colima/default/docker.sock (Colima)
-
~/.orbstack/run/docker.sock (OrbStack)
-
/var/run/docker.sock (Docker Desktop / default)
If only Colima is checked, patch it to support all runtimes. Read ${CLAUDE_SKILL_ROOT}/references/orbstack-fix.md for the exact pattern.
Then: Seed the Database
If this is a first-time setup, the database needs seeding:
.venv/bin/sentry upgrade --noinput
This runs all Django migrations AND creates default data (organizations, roles, projects). Without this, the dev server will 500 on every page.
Do NOT just run sentry django migrate — that only runs migrations without seeding the required default data.
Create Superuser
.venv/bin/sentry createuser --superuser --email admin@sentry.io --password admin --no-input
Step 7: Start the Dev Server
devservices serve
Or directly:
.venv/bin/sentry devserver
What to Expect on Startup
Kafka topic warnings are normal. On first start, you'll see many lines like:
[WARNING] sentry.batching-kafka-consumer: Topic 'taskworker' or its partitions are not ready, retrying...
These settle down after 30-60 seconds as Kafka auto-creates topics. Don't panic.
Access the Dev Server
-
Login: admin@sentry.io / admin
Required: Sentry Cookie Sync Extension
Without this extension, the UI shows a blank white screen. Install it:
https://chromewebstore.google.com/detail/sentry-cookie-sync/kchlmkcdfohlmobgojmipoppgpedhijh
This syncs auth cookies between sentry.io and dev.sentry.localhost. It's not optional.
Day-to-Day Commands
After initial setup, the daily workflow is:
cd ~/Projects/sentry # (or wherever the repo lives) devservices up # start background services (~30s) devservices serve # start dev server
→ http://dev.sentry.localhost:8000
After pulling new code:
devenv sync # update dependencies + migrations (2-5 min)
Troubleshooting Decision Tree
Symptom Likely Cause Fix
direnv hangs Docker runtime not running Start OrbStack / Colima
devenv sync fails with version error Outdated devenv devenv update or reinstall
devservices up says "colima not running" Using OrbStack, script only checks Colima Patch devservices.py — see Step 6
Server 500s on every page DB not seeded .venv/bin/sentry upgrade --noinput
relation "sentry_organization" does not exist
Migrations not run .venv/bin/sentry upgrade --noinput
White/blank screen in browser Cookie Sync extension missing Install the Chrome extension
Kafka topic warnings on startup Normal first-boot behavior Wait 30-60 seconds
Port already in use Stale containers docker rm -f $(docker ps -aq) then retry
Everything is broken Nuclear option devservices purge && devenv sync && devservices up
DNS failures in Docker Colima DNS stale devenv doctor or devenv colima restart
For deeper troubleshooting, use the AL MCP if available (devinfra-mcp):
al_search_docs(query="<symptom keywords>") al_read_doc(path="devenv/troubleshooting.md", query="<specific issue>")