About polar-local-environment
Local Environment Skill helps developers manage the Polar local development environment with the `dev docker` CLI. It explains the split between shared infrastructure and per-worktree app stacks, and documents instance ports, logs, and troubleshooting.
Key features
- 01Start, stop, and restart the local environment
- 02View instance ports and service status
- 03Manage parallel worktree instances
- 04View logs, enter containers, and run commands
- 05Understand app stacks versus shared infrastructure
Use cases
- 01Start local services or diagnose startup issues
- 02Run multiple isolated worktree environments in parallel
- 03Find a service's actual port and URL
- 04Clean up one instance or shared data
Install
Copy the command and run it in a terminal.
npx skills add https:/After installing, type/polar-local-environmentin Claude Code to confirm it loaded.
Bundled files
References and scripts installed along with SKILL.md.
rules/manage-instances.mdpayment-testing.mdservice-architecture.mdshell-and-workflows.mdstart-environment.mdstop-environment.mdtroubleshooting.mdview-logs.mdDetails
From the project READMELocal 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. Usedev 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:
POLAR_DOCKER_INSTANCEpinned indev/docker/.env.docker(dev docker set-instance N)- The cross-worktree registry (
~/.config/polar/docker-instances.json) - 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
| Task | Command |
|---|---|
| Start full stack (background) | dev docker up -d |
| Start and block until healthy | dev docker up -d --wait |
| Start in foreground (stream logs) | dev docker up --no-detach |
| Rebuild with fresh base images | dev docker up -b --pull -d |
| Show this instance's ports/URLs | dev docker ports (--json for tooling) |
| Write Claude Code preview config | dev docker launch-json |
| Stop app stack | dev docker down |
| Stop app and shared infra | dev docker down --all |
| Follow logs | dev docker logs -f [service] |
| Print logs and exit | dev docker logs --no-follow [service] |
| Status | dev docker ps |
| Restart a service | dev docker restart <service> |
| Shell into a service | dev docker shell <service> |
| One-off command in a service | dev docker exec <service> <cmd> |
| Reset this instance | dev docker cleanup -f |
| Wipe ALL shared data | dev docker cleanup --all -f |
| List every instance | dev docker list |
| With monitoring | dev docker up --monitoring -d |
Services
| Service | Project | Host port (instance 0 / N) | Notes |
|---|---|---|---|
| api | polar-app-<N> | 8000 / 8100+N | FastAPI; /healthz healthcheck |
| web | polar-app-<N> | 3000 / 3100+N | Next.js; healthchecked |
| worker | polar-app-<N> | none | Background jobs |
| db | polar-shared | none (exec) | PostgreSQL; DB polar_dev_<N> |
| redis | polar-shared | none (exec) | Redis DB index = N |
| minio | polar-shared | 9000, 9001 | S3; buckets polar-s3-<N>; console at 9001 |
| tinybird | polar-shared | none (exec) | Analytics |
| prometheus / grafana | polar-shared | none (exec) | --monitoring only |
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.
| Instance | API | Web |
|---|---|---|
| 0 | 8000 | 3000 |
| 1 | 8101 | 3101 |
| 2 | 8102 | 3102 |
| 5 | 8105 | 3105 |
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
| Rule | Category | Description |
|---|---|---|
| service-architecture | Reference | Service details, ports, healthchecks |
| start-environment | Operations | Starting the stack (flags, --wait, --pull) |
| stop-environment | Operations | Stopping and cleanup (app vs shared) |
| manage-instances | Operations | Parallel worktree instances |
| view-logs | Debugging | Viewing service logs |
| shell-and-workflows | Operations | Shell access and common dev workflows |
| troubleshooting | Debugging | Common errors and fixes |
| payment-testing | Operations | Login codes, Stripe webhooks, backoffice |