Skip to main content
skill CX Codex

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

Install into Claude Code · Plugin marketplace All methods and platforms ↓
/plugin marketplace add fcakyon/claude-codex-settings
/plugin install polar-skills@claude-settings
Open on GitHub

What 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 api logs 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-settings

This 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-code

3Manually: put the files in place

~/.claude/skills/polar-local-environment/SKILL.md

Copy the whole skill folder; for one project use .claude/skills/polar-local-environment/

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

Similar skills

All skills for DevOps and infrastructure →

From the same set113

The whole set →
email-design email-design — a skill for Claude Code and Codex that handles transactional email layout. Styles account confirmations, password resets and billing receipts to match your application branding. CX Codex +1 ★ 1,216repo stars commit-creator commit-creator reviews staged changes, plans a single commit or a logical series, and writes concise commit messages. Available for Claude Code and Codex. CX Codex ★ 1,216repo stars site-architecture The site-architecture skill for Claude Code and Codex plans or restructures site structure, including page hierarchy, navigation, URL patterns, breadcrumbs, and internal links. CX Codex +1 ★ 1,216repo stars derive-client derive-client records browser network traffic into a HAR archive and turns captured internal endpoints into a standalone API client or CLI script. CX Codex +1 ★ 1,216repo stars yolo-training yolo-training reads YOLO26 training curves and results.csv, diagnoses overfitting or poor mAP, and points to the cheapest fix first. CX Codex +1 ★ 1,216repo stars supabase-cli Equips coding agents to run Supabase CLI commands for local environments, schema migrations, edge function deployments, and TypeScript type generation. CX Codex +1 ★ 1,216repo stars payment-testing The payment-testing rule explains local checks for login, Stripe events, subscription renewals, refunds, and the backoffice. Use it when a payment flow behaves differently in your local stack. CX Codex +1 ★ 1,216repo stars troubleshooting troubleshooting — a rule covering common failures in a Dockerized Polar dev stack, from stuck ports to stale database connections. CX Codex +1 ★ 1,216repo stars

Project sponsors

Companies that keep this analytics open