polar-local-environment — Claude Code skill for Polar Docker
The polar-local-environment skill for Claude Code manages Polar’s local Docker setup, including stack operations, service debugging, and separate environments for multiple worktrees.
MIT ★ 1,216 updated 2026-10-24
/plugin marketplace add fcakyon/claude-codex-settings
/plugin install polar-skills@claude-settingsWhat polar-local-environment does
The skill describes Polar’s two-part setup: worktrees share infrastructure such as PostgreSQL, Redis, and MinIO, while each gets its own API, worker, and web stack. Use dev docker to start or stop services, inspect logs and ports, or run a command inside a service.
The current worktree’s instance is detected automatically, or you can pin it with dev docker set-instance N. API and web ports vary by instance. PostgreSQL and Redis have no host ports, so a connection to localhost:5432 will fail; reach the database through dev docker exec db ... instead.
For Claude Code previews, dev docker launch-json writes .claude/launch.json with the instance’s ports. Regenerate it after changing the instance, since Git ignores that file.
What it helps with
- Start or stop the Polar development stack
- Find the current worktree’s host ports
- Inspect logs when a service fails to start
- Run separate environments across worktrees
- Execute a command inside a service
Example prompts for the agent
- Start Polar locally and wait until the services are healthy.
- Show the ports for this worktree and prepare its Claude Code preview config.
- Check the
apilogs and help me diagnose why it will not start.
How to install polar-local-environment
1Plugin marketplace
/plugin marketplace add fcakyon/claude-codex-settings/plugin install polar-skills@claude-settingsThis installs the whole polar-skills plugin with all its skills
2Skills CLI (Vercel)
npx skills add fcakyon/claude-codex-settings --skill polar-local-environment -a claude-code3Manually: put the files in place
~/.claude/skills/polar-local-environment/SKILL.mdCopy the whole skill folder; for one project use .claude/skills/polar-local-environment/
1Skills CLI (Vercel)
npx skills add fcakyon/claude-codex-settings --skill polar-local-environment -a codex2Manually: put the files in place
.agents/skills/polar-local-environment/SKILL.mdFor all projects use ~/.agents/skills/
1Skills CLI (Vercel)
npx skills add fcakyon/claude-codex-settings --skill polar-local-environment -a cursor2Manually: put the files in place
.cursor/skills/polar-local-environment/SKILL.mdCursor also reads .agents/skills/ and .claude/skills/
1GitHub CLI
gh skill install fcakyon/claude-codex-settings plugins/polar-skills/skills/polar-local-environment2Manually: put the files in place
.github/skills/polar-local-environment/SKILL.md1Skills CLI (Vercel)
npx skills add fcakyon/claude-codex-settings --skill polar-local-environment -a gemini-cli2Platform CLI
gemini skills install https://github.com/fcakyon/claude-codex-settings --path plugins/polar-skills/skills/polar-local-environmentManually: put the files in place
.devin/skills/polar-local-environment/SKILL.mdThe legacy .windsurf/skills/ path still works
Claude.ai
Zip the folder and upload it in Settings → Capabilities → Skills
Step by step, with commands for each platform: How to install skills in Claude Code: five ways
Questions about polar-local-environment
How do I install polar-local-environment in Claude Code?
Add the marketplace with /plugin marketplace add fcakyon/claude-codex-settings, then install the skill with /plugin install polar-skills@claude-settings.
What does polar-local-environment do?
It guides dev docker operations for Polar’s local stack, including starting services, checking ports, viewing logs, and running commands inside containers.
Why can’t I reach PostgreSQL at localhost:5432?
PostgreSQL runs in shared infrastructure and does not publish a host port. Access it with dev docker exec db ....
Source text
SKILL.md · MIT
--- name: polar-local-environment description: "This skill should be used when setting up or managing Polar local development environment with Docker." license: MIT metadata: author: polar version: "1.1.0" --- # 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. The cross-worktree registry (`~/.config/polar/docker-instances.json`) 3. 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](rules/service-architecture.md) | Reference | Service details, ports, healthchecks | | [start-environment](rules/start-environment.md) | Operations | Starting the stack (flags, `--wait`, `--pull`) | | [stop-environment](rules/stop-environment.md) | Operations | Stopping and cleanup (app vs shared) | | [manage-instances](rules/manage-instances.md) | Operations | Parallel worktree instances | | [view-logs](rules/view-logs.md) | Debugging | Viewing service logs | | [shell-and-workflows](rules/shell-and-workflows.md) | Operations | Shell access and common dev workflows | | [troubleshooting](rules/troubleshooting.md) | Debugging | Common errors and fixes | | [payment-testing](rules/payment-testing.md) | Operations | Login codes, Stripe webhooks, backoffice |
© polar · MIT · fcakyon/claude-codex-settings