# Coast Runtime

This project uses Coasts — containerized runtimes for running services, tests,
and other runtime commands. The filesystem is shared between the host and the
container, so file edits on either side are visible to both immediately.

## Discovery

Before the first runtime command in a session, run:

  coast lookup

This prints the instance name, ports, and example commands. Use the instance
name from the output for all subsequent commands.

## What runs where

The filesystem is shared, so only use `coast exec` for things that need the
container runtime (databases, services, integration tests). Everything else
runs directly on the host.

Use `coast exec` for:
- Tests that need running services (unit tests that are integrated with services or dbs, integration tests, API tests)
- Service restarts or compose operations
- Anything that talks to databases, caches, or other container services

Run directly on the host:
- Linting, typechecking, formatting
- Git operations
- Playwright and browser tests (if the project uses them) — run the browser
  on the host, pointed at the Coast's dynamic port URL (get it from
  `coast lookup` or `coast ports`). If the Coast is checked out, the
  canonical port (e.g. localhost:3000) works too, but prefer the dynamic
  port unless the user says otherwise.
  Do NOT run Playwright inside the Coast via `coast exec`.
- Installing host-side dependencies (npm install, pip install)
- File search, code generation, static analysis

Example:

  coast exec <instance> -- sh -c "cd <dir> && npm test"    # needs DB
  coast exec <instance> --service <service>                # service shell
  npm run lint                                              # host is fine
  BASE_URL=http://localhost:62217 npx playwright test       # host — use dynamic port

## Runtime feedback

  coast ps <instance>
  coast logs <instance> --service <service>
  coast logs <instance> --service <service> --tail 50

## Creating and assigning Coasts

If `coast lookup` returns no match, run `coast ls` to see what exists.

If an unassigned Coast is already running for this project, prefer assigning
your worktree to it rather than creating a new one:

  coast assign <existing> -w <worktree>

An already occupied Coast can also be reassigned with `coast assign`, but check
with the user first because that will disrupt the current slot.

If no Coast is running, ask the user before creating one — Coasts can be
memory intensive:

  coast run <name> -w <worktree>

A project must be built before instances can be created. If `coast run` fails
because no build exists, run `coast build` first.

## Coastfile setup

If the project does not have a Coastfile yet, or if you need to modify the
Coastfile, read the Coastfile docs first:

  coast docs --path coastfiles/README.md

## When confused

Before guessing about Coast behavior, explore the docs:

  coast docs                                     # list all doc pages
  coast docs --path concepts_and_terminology/RUN.md
  coast docs --path concepts_and_terminology/ASSIGN.md
  coast docs --path concepts_and_terminology/BUILDS.md
  coast search-docs "your question here"         # semantic search

## Troubleshooting

If you run into issues with harness configuration (e.g. worktrees not being
found, `coast lookup` not matching), read the troubleshooting section of the
relevant harness doc:

  coast docs --path harnesses/CLAUDE_CODE.md
  coast docs --path harnesses/CODEX.md
  coast docs --path harnesses/CONDUCTOR.md
  coast docs --path harnesses/CURSOR.md
  coast docs --path harnesses/T3_CODE.md
  coast docs --path harnesses/SHEP.md

## Rules

- Always run `coast lookup` before your first runtime command in a session.
- Use `coast exec` only for things that need the container runtime.
- Use `coast exec --service <service>` when you need to run inside an app/service container.
- Run linting, typechecking, formatting, and git on the host directly.
- Use `coast docs` or `coast search-docs` before guessing about Coast behavior.
- Do not run services directly on the host when the project expects Coast.

---
name: coasts
description: Inspect and control Coast instances for the current checkout. Use
  when the user says "/coasts", asks to assign or reassign a Coast, wants to
  run commands or read logs in the matching Coast, wants to create a new Coast,
  or explicitly asks to open Coast UI.
---

# Coasts

Use the Coast CLI directly. Do not add wrappers.

## Orient Yourself

Start by exploring the CLI and docs:

  coast                                             # see all available commands
  coast docs                                        # list all doc pages
  coast search-docs "your question"                 # semantic search

When anything about Coast behavior is unclear, read the docs before guessing:

  coast docs --path concepts_and_terminology/RUN.md
  coast docs --path concepts_and_terminology/BUILDS.md
  coast docs --path concepts_and_terminology/ASSIGN.md
  coast docs --path concepts_and_terminology/PORTS.md
  coast docs --path coastfiles/README.md

## Quick Start

Route requests into one of these modes:

1. **Use Coast** — run `coast lookup`, then use `coast exec`, `coast ps`,
   or `coast logs` with the matching instance.
2. **Create or Assign** — run `coast ls`, then `coast run` to create a new
   Coast or `coast assign` to repoint an existing one.
3. **Open UI** — run `coast ui`.

## What Runs Where

The host and the Coast share the filesystem. Only use `coast exec` for things
that need running services inside the container.

**Use `coast exec` for:**
- Integration tests, API tests, anything that needs databases or services
- Service restarts, compose operations
- Commands that talk to container-only processes

**Run on the host:**
- Linting (`eslint`, `rubocop`, `golangci-lint`)
- Typechecking (`tsc --noEmit`, `go vet`)
- Formatting (`prettier`, `gofmt`)
- Git operations
- Playwright and browser tests (if the project uses them) — run the browser
  on the host, pointed at the Coast's dynamic port URL (get it from
  `coast lookup` or `coast ports`). If the Coast is checked out, the
  canonical port (e.g. localhost:3000) works too, but prefer the dynamic
  port unless the user says otherwise.
  Do NOT run Playwright inside the Coast via `coast exec`.
- Static analysis, code generation
- Package installs (`npm install`, `pip install`)

Example — Playwright hits the frontend through the dynamic port:

  coast ports <instance>
  # SERVICE    CANONICAL  DYNAMIC
  # ★ web      3000       62217

  BASE_URL=http://localhost:62217 npx playwright test   # host, not coast exec

## Create and Assign

When `coast lookup` returns no match:

1. Run `coast ls` to see available slots.
2. Prefer `coast run <name> -w <worktree>` to create and assign in one step.
3. If no build exists yet, run `coast build` first.
4. After creating, rerun `coast lookup` to confirm.

When you want to switch an existing Coast to a different worktree:

  coast assign <name> -w <worktree>

That also works for an already assigned or checked-out Coast, but ask the user
first before reassigning an occupied slot.

## Coastfile Setup

If the project needs a new or modified Coastfile, read the docs first:

  coast docs --path coastfiles/README.md

The Coastfile docs cover compose setup, ports, volumes, secrets, shared
services, bare services, and inheritance.

## Safety Rules

- Run `coast lookup` before taking action and again after any topology change.
- Ask before `coast assign`, `coast unassign`, or `coast checkout` if it would
  disrupt an existing slot.
- Prefer creating a new Coast over reusing a checked-out or already-assigned
  one unless the user explicitly wants the existing slot to be reassigned.
- Use `coast docs` or `coast search-docs` before guessing.