Setup DevBLOCK

Developer-first error tracking and performance monitoring

The instruction file, verbatim from the audited commit — this is the text the model reads, and the surface the audit's instruction layer examines. Quoted here so you can judge it without cloning anything.

---
name: setup-dev
description: Set up and manage the Sentry development environment using devenv. Handles fresh setup, updating existing environments, starting dev services, resetting the database, per-worktree environment setup (each worktree needs its own devenv sync/.venv), 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", "reset the database", "new worktree venv/devenv setup", or any development environment issue.
---

# 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](https://github.com/getsentry/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:

```bash
# 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

```bash
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

```bash
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:**

```bash
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

```bash
# 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:

```bash
# 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):

```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:

```bash
devenv --version
```

If the version is old (e.g., < 1.22), upgrade:

```bash
devenv update
```

If `devenv update` itself fails because the version is too old, reinstall:

```bash
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:

```bash
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:**

```bash
~/.local/share/sentry-devenv/bin/dev

BLOCKgrade D · trust 69/100 Do not install this without reading the findings. The audit found something that could harm you or your machine.

What the source does

Filesystem

none-observed

Network

none-observed

Shell

none-observed

Dependencies

pinned

Secrets in source

none-found

Findings (5)

.venv/bin/sentry createuser --superuser --email [email protected] --password admin --no-input

.claude/skills

api-docs/.node-version

curl -fsSL https://raw.githubusercontent.com/getsentry/devenv/main/install-devenv.sh | bash

curl -fsSL https://raw.githubusercontent.com/getsentry/devenv/main/install-devenv.sh | bash

Gates applied: critical_finding, no_behavioural_pass, undeclared_transfer.