Skip to main content
rule CX Codex

start-environment — Claude Code rule: what it does, how to install

start-environment teaches the assistant how to spin up local development containers via dev docker up, wait for healthchecks, and inspect ports.

Apache-2.0 ★ 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 start-environment does

The rule documents operations around dev docker up, which spins up shared infra and app containers. Containers start detached by default. The guide directs the assistant to pass --wait so commands block until /healthz succeeds and the web service responds, avoiding broken scripts during slow startup phases.

Flags like -b and --pull are specified for image rebuilds. Pulling fresh base images resolves cached layer problems, such as stale interpreters after updating .python-version. It also details the initial setup sequence, covering uv sync, pnpm install, database bootstrapping, and database migrations.

Because host ports are allocated per instance, assuming default ports breaks multi-instance setups; the rule instructs the assistant to read endpoints via dev docker ports or dev docker ports --json.

What it helps with

  • start local development containers and shared infra
  • block execution until app healthchecks pass
  • rebuild images and pull fresh bases after runtime updates
  • discover assigned host ports for active worktree instances

Example prompts for the agent

  • Start the local environment and wait until services are healthy
  • Rebuild docker images with fresh base layers and start in the background
  • Check which ports are assigned to this instance

How to install start-environment

1Plugin marketplace

/plugin marketplace add fcakyon/claude-codex-settings
/plugin install polar-skills@claude-settings

2Manually: put the files in place

.claude/rules/start-environment.md

The paths frontmatter field limits the files

Step by step, with commands for each platform: AGENTS.md vs CLAUDE.md: what they are and which one to use

Questions about start-environment

How to install start-environment in Claude Code?

Run /plugin marketplace add fcakyon/claude-codex-settings, then /plugin install polar-skills@claude-settings. You can also place the rule file directly at .claude/rules/start-environment.md.

What does start-environment do?

It provides instructions for Claude Code and Codex on managing local app stacks using dev docker up. It covers detached execution, log streaming, and troubleshooting stale base images.

Why should scripts use the --wait flag?

Containers return immediately in detached mode, but the app may still be running uv sync, pnpm install, or database migrations. The --wait flag guarantees that the API /healthz endpoint responds before subsequent steps run.

Source text

start-environment.md · Apache-2.0
---
title: Starting the Local Environment
category: Operations
tags: docker, start, development
---

# Starting the Local Environment

`dev docker up` starts shared infra (if it isn't already running) plus this
worktree's app stack. It **defaults to detached** (`-d` is on by default), so
plain `dev docker up` returns once containers are created.

## Basic commands

**Start in background (the default):**

```bash
dev docker up -d
```

**Start and block until app services are healthy:**

```bash
dev docker up -d --wait
```

`--wait` returns only once api answers `/healthz` and web responds. Prefer it in
scripts and tooling so "up finished" means "actually serving" rather than "the
container was created" — on first boot the app keeps compiling and migrating for
a while after the container starts.

**Start in the foreground and stream logs:**

```bash
dev docker up --no-detach
```

Shared infra still starts detached; only the app stack is attached, so Ctrl+C
stops the app stack.

**Start specific services:**

```bash
dev docker up -d api            # api (+ shared infra)
dev docker up -d web            # web (+ shared infra)
dev docker up -d api worker     # api and worker
```

## Options

| Flag              | Description                                          |
| ----------------- | ---------------------------------------------------- |
| `-d` / `--detach` | Detached / background (default)                      |
| `--no-detach`     | Foreground; stream app logs until you stop it        |
| `--wait`          | Block until app services are healthy (detached only) |
| `-b` / `--build`  | Rebuild images before starting                       |
| `--pull`          | Refresh base images before building (see below)      |
| `--monitoring`    | Include Prometheus and Grafana in shared infra       |
| `-i N`            | Target instance N explicitly (usually auto-detected) |

## Rebuilding with fresh bases

```bash
dev docker up -b --pull -d
```

`-b` rebuilds the images, and `--pull` refreshes the base images first. Use
`--pull` after a `.python-version` bump or when a rebuild alone still boots the
old interpreter — a cached `FROM` layer can otherwise pin you to a stale base.
See troubleshooting for the "No interpreter found for Python X" symptom.

## First-time startup

First run is slow because it does real work inside the containers:

1. Build the api/web images
2. `uv sync` (api/worker) and `pnpm install` (web) — several minutes
3. Bootstrap the per-instance DB and MinIO buckets
4. Run migrations and load seed data
5. Services become healthy

`dev docker up -d --wait` is the cleanest way to wait this out.

## Finding the URLs

Ports are per-instance, so don't assume 3000/8000. Ask:

```bash
dev docker ports          # human-readable
dev docker ports --json   # for tooling
```

For instance 0 the app is at http://localhost:3000 (web) and
http://localhost:8000 (api, docs at `/docs`). MinIO exposes ports 9000 (API)
and 9001 (console) on localhost; db and redis have no host port — reach them
with `dev docker exec <service> ...`.

© fcakyon · Apache-2.0 · fcakyon/claude-codex-settings

Similar IDE rules

All IDE rules for DevOps and infrastructure →
capture-environment pedrohcgs The capture-environment skill snapshots language and package versions, seeds and RNG kind into lockfiles so a rerun matches on another machine. Reach for it before releasing a replication package. CX Codex +1 ★ 1,729repo stars setup-development-environment davila7 setup-development-environment — a slash command that builds out a dev environment: runtimes, tooling, build setup, linters, configs. Handy when you spin up a project on a fresh machine. CX Codex +1 651installs test-environment-management proffesor-for-testing test-environment-management is a Claude Code skill for setting up test infrastructure and matching it to production. It covers environment setup, parity checks, and test infrastructure costs. CX Codex +1 117installs magento-local-environment-specialist maxnorm magento-local-environment-specialist walks the agent through a local Magento 2 setup: containers, PHP settings, database, cache, step debugging. Also covers breakage after a move to another machine. CX Codex +1 164installs devcontainer-setup trailofbits devcontainer-setup creates a sandboxed devcontainer with Claude Code, persistent volumes, and tooling for Python, Node, Rust, or Go. Helpful when setting up isolated development workspaces. CX Codex +1 5,800installs environment-setup akillness environment-setup — a skill for app configuration: which values belong in .env, what gets committed, how to validate required variables, and where secrets stop being your problem. CX Codex +1 354installs

From the same set113

The whole set →
list-performance-item-types list-performance-item-types is a Claude Code rule for lists with mixed layouts. It guides the agent to assign item types and keep unlike cells in separate recycling pools. CX Codex +1 ★ 1,216repo stars manage-instances manage-instances — a rule for running multiple isolated app stacks in separate worktrees, each with its own database, Redis index, and host ports. CX Codex +1 ★ 1,216repo stars test-audit The test-audit skill reviews new and changed tests, and helps spot duplicates or low-value checks. Use it when adding tests or auditing an existing suite. CX Codex +1 ★ 1,216repo stars webmcp-gen webmcp-gen turns a page workflow into a WebMCP tool and checks that the tool matches the behavior of the existing UI. CX Codex +1 ★ 1,216repo stars service-architecture The service-architecture rule maps Polar’s shared Docker infrastructure and per-worktree app stacks. Use it to understand service addresses, container dependencies, and network boundaries. CX Codex +1 ★ 1,216repo stars openship-config Inspects a repository and builds openship.json with only the overrides OpenShip needs. Use it before a first deploy or when openship config validate fails. CX Codex +1 ★ 1,216repo stars app-auth The app-auth skill for Claude Code structures and implements application authentication flows. It activates when handling social login, password recovery, account switching, or sign-in components. CX Codex +1 ★ 1,216repo stars gcloud-usage gcloud-usage is a Claude Code skill that guides Google Cloud log queries and analysis of metrics, traces, and alerts. It supports production debugging and GCP observability work. CX Codex +1 ★ 1,216repo stars

Project sponsors

Companies that keep this analytics open