local-environment

Local Environment Skill

Helps manage the Polar local development environment through the dev docker CLI. Use it to start, stop, debug, or reason about the local stack.

The two-part model

dev docker deliberately splits the stack so many worktrees can share one set of heavy infra:

• Shared infra — one copy per machine, Docker project polar-shared: postgres, redis, minio, tinybird, and optional prometheus/grafana. Postgres and redis publish no host ports; MinIO exposes 9000/9001 for browser uploads. Use dev docker exec <service> ... for services without host ports.
• Per-instance app stack — one per worktree, project polar-app-<N>: api, worker, web. Only api and web publish host ports, offset per instance so worktrees don't collide.

Knowing this prevents the most common confusion: there is no localhost:5432 for the database (it lives in the shared stack and is reached through dev docker exec db ...). MinIO does expose ports 9000/9001 for browser uploads and console access.

Instance auto-detection

dev docker auto-detects the instance for the current worktree, so -i is rarely needed. Priority:

1. POLAR_DOCKER_INSTANCE pinned in dev/docker/.env.docker (dev docker set-instance N)
2. CONDUCTOR_PORT env var → (port - 55000) / 10 + 1
3. The cross-worktree registry (~/.config/polar/docker-instances.json)
4. Otherwise the lowest free number, then registered

Run dev docker ports to see the resolved instance and its URLs (add --json for tooling). To wire this worktree into Claude Code's preview, run dev docker launch-json, which writes a per-instance .claude/launch.json with the correct ports (it's gitignored, so regenerate after set-instance).

When to use

• Start / stop / restart the local environment
• View logs or debug a service that won't come up
• Run several isolated worktree instances in parallel
• Understand the service architecture or find a service's real port
• Diagnose container or first-boot errors

Quick reference

Services

Discover the exact host ports for the current worktree with dev docker ports.

Instance port mapping

Only api and web get host ports: Port = Base + Instance (Base 8100 for api, 3100 for web) for instances 1–99. Instance 0 uses the legacy 8000 / 3000.

Everything else is per-instance but not on a host port: database polar_dev_<N>, redis DB index <N>, buckets polar-s3-<N> / polar-s3-public-<N>. Reach them via dev docker exec <service> or docker exec polar-shared-<service>-1.

Rules index