From 8eb16431ba6c3a611ba1e7469ec43c726492bbb4 Mon Sep 17 00:00:00 2001 From: "dahyman91@gmail.com" Date: Mon, 23 Mar 2026 16:51:47 -0400 Subject: [PATCH] [dh] docs: update install command to use eval form --- coast-guard/src/generated/docs-manifest.json | 4 ++-- docs/GETTING_STARTED.md | 2 +- docs/README.md | 2 +- 3 files changed, 4 insertions(+), 4 deletions(-) diff --git a/coast-guard/src/generated/docs-manifest.json b/coast-guard/src/generated/docs-manifest.json index c1580b4..bf38c85 100644 --- a/coast-guard/src/generated/docs-manifest.json +++ b/coast-guard/src/generated/docs-manifest.json @@ -344,8 +344,8 @@ } ], "files": { - "README.md": "# Coasts Documentation\n\n```youtube\nMBGKSKau4sU\nPart of the [Coasts Video Course](learn-coasts-videos/README.md).\n```\n\n## Installing\n\n- `curl -fsSL https://coasts.dev/install | sh`\n- `coast daemon install`\n\n*If you decide not to run `coast daemon install`, you are responsible for starting the daemon manually with `coast daemon start` every single time.*\n\n## What Are Coasts?\n\nA Coast (**containerized host**) is a local development runtime. Coasts let you run multiple isolated environments for the same project on one machine.\n\nCoasts are especially useful for complex `docker-compose` stacks with many interdependent services, but they are equally effective for non-containerized local dev setups. Coasts support a wide range of [runtime configuration patterns](concepts_and_terminology/RUNTIMES_AND_SERVICES.md) so you can shape the ideal environment for multiple agents working in parallel.\n\nCoasts are built for local development, not as a hosted cloud service. Your environments run locally on your machine.\n\nThe Coasts project is free, local, MIT-licensed, agent-provider agnostic, and agent-harness agnostic software with no AI upsells.\n\nCoasts work with any agentic coding workflow that uses worktrees. No special harness-side configuration is required.\n\n## Why Coasts for Worktrees\n\nGit worktrees are excellent for isolating code changes, but they do not solve runtime isolation by themselves.\n\nWhen you run multiple worktrees in parallel, you quickly hit ergonomic problems:\n\n- [Port conflicts](concepts_and_terminology/PORTS.md) between services that expect the same host ports.\n- Per-worktree database and [volume setup](concepts_and_terminology/VOLUMES.md) that is tedious to manage.\n- Integration test environments that need custom runtime wiring per worktree.\n- The living hell of switching worktrees and rebuilding runtime context each time. See [Assign and Unassign](concepts_and_terminology/ASSIGN.md).\n\nIf Git is version control for your code, Coasts are like Git for your worktree runtimes.\n\nEach environment gets its own ports, so you can inspect any worktree runtime in parallel. When you [check out](concepts_and_terminology/CHECKOUT.md) a worktree runtime, Coasts remap that runtime to your project's canonical ports.\n\nCoasts abstract runtime configuration into a simple modular layer on top of worktrees, so each worktree can run with the isolation it needs without hand-maintaining complex per-worktree setup.\n\n## Requirements\n\n- macOS or Linux\n- Docker Desktop on macOS, or Docker Engine with the Compose plugin on Linux\n- A project using Git\n- Node.js\n- `socat` (`brew install socat` on macOS, `sudo apt install socat` on Ubuntu)\n\n```text\nLinux note: Dynamic ports work out of the box on Linux.\nIf you need canonical ports below `1024`, see the checkout docs for the required host configuration.\n```\n\n## Containerizing Agents?\n\nYou can containerize an agent with a Coast. That might sound like a great idea at first, but in many cases you do not actually need to run your coding agent inside a container.\n\nBecause Coasts share the [filesystem](concepts_and_terminology/FILESYSTEM.md) with your host machine through a shared volume mount, the easiest and most reliable workflow is to run the agent on your host and instruct it to execute runtime-heavy tasks (such as integration tests) inside the Coast instance using [`coast exec`](concepts_and_terminology/EXEC_AND_DOCKER.md).\n\nHowever, if you do want to run your agent in a container, Coasts absolutely support that via [Agent Shells](concepts_and_terminology/AGENT_SHELLS.md). You can build an incredibly intricate rig for this setup including [MCP server configuration](concepts_and_terminology/MCP_SERVERS.md), but it may not interoperate cleanly with the orchestration software that exists today. For most workflows, host-side agents are simpler and more reliable.\n\n## Coasts vs Dev Containers\n\nCoasts are not dev containers, and they are not the same thing.\n\nDev containers are generally designed for mounting an IDE into a single containerized development workspace. Coasts are headless and optimized as lightweight environments for parallel agent usage with worktrees — multiple isolated, worktree-aware runtime environments running side by side, with fast checkout switching and runtime isolation controls for each instance.\n\n## Demo Repo\n\nIf you want a small example project to try with Coasts, start with the [`coasts-demo` repository](https://github.com/coast-guard/coasts-demo).\n\n## Coasts Video Course\n\nIf you prefer video, the [Coasts Video Course](learn-coasts-videos/README.md) covers every core concept in under three minutes each.\n\n", - "GETTING_STARTED.md": "# Getting Started with Coasts\n\n```youtube\nJe921fgJ4RY\nPart of the [Coasts Video Course](learn-coasts-videos/README.md).\n```\n\n## Installing\n\n```bash\ncurl -fsSL https://coasts.dev/install | sh\ncoast daemon install\n```\n\n*If you decide not to run `coast daemon install`, you are responsible for starting the daemon manually with `coast daemon start` every single time.*\n\n## Requirements\n\n- macOS or Linux\n- Docker Desktop on macOS, or Docker Engine with the Compose plugin on Linux\n- A project using Git\n- Node.js\n- `socat` (`brew install socat` on macOS, `sudo apt install socat` on Ubuntu)\n\n```text\nLinux note: Dynamic ports work out of the box on Linux.\nIf you need canonical ports below `1024`, see the checkout docs for the required host configuration.\n```\n\n## Setting Up Coasts in a Project\n\nAdd a Coastfile to the root of your project. Make sure you are not on a worktree when installing.\n\n```text\nmy-project/\n├── Coastfile <-- this is what Coast reads\n├── docker-compose.yml\n├── Dockerfile\n├── src/\n│ └── ...\n└── ...\n```\n\nThe `Coastfile` points at your existing local development resources and adds Coasts-specific configuration — see the [Coastfiles documentation](coastfiles/README.md) for the full schema:\n\n```toml\n[coast]\nname = \"my-project\"\ncompose = \"./docker-compose.yml\"\n\n[ports]\nweb = 3000\ndb = 5432\n```\n\nA Coastfile is a lightweight TOML file that *typically* points to your existing `docker-compose.yml` (it also works with non-containerized local dev setups) and describes the modifications needed to run your project in parallel — port mappings, volume strategies, and secrets. Place it at your project root.\n\nThe fastest way to create a Coastfile for your project is to let your coding agent do it.\n\nThe Coasts CLI ships with a built-in prompt that teaches any AI agent the full Coastfile schema and CLI. Copy it into your agent's chat and it will analyze your project and generate a Coastfile.\n\n```prompt-copy\ninstallation_prompt.txt\n```\n\nYou can also get the same output from the CLI by running `coast installation-prompt`.\n\n## Your First Coast\n\nBefore starting your first Coast, bring down any running development environment. If you are using Docker Compose, run `docker-compose down`. If you have local dev servers running, stop them. Coasts manage their own ports and will conflict with anything already listening.\n\nOnce your Coastfile is ready:\n\n```bash\ncoast build\ncoast run dev-1\n```\n\nCheck that your instance is running:\n\n```bash\ncoast ls\n\n# NAME PROJECT STATUS BRANCH RUNTIME WORKTREE CO ROOT\n# dev-1 my-project running main dind - ~/dev/my-project\n```\n\nSee where your services are listening:\n\n```bash\ncoast ports dev-1\n\n# SERVICE CANONICAL DYNAMIC\n# ★ web 3000 62217\n# db 5432 55681\n```\n\nEach instance gets its own set of dynamic ports so multiple instances can run side by side. To map an instance back to your project's canonical ports, check it out:\n\n```bash\ncoast checkout dev-1\n```\n\nThis means the runtime is now checked out and your project's canonical ports (like `3000`, `5432`) will route to this Coast instance.\n\n```bash\ncoast ls\n\n# NAME PROJECT STATUS BRANCH RUNTIME WORKTREE CO ROOT\n# dev-1 my-project running main dind - ✓ ~/dev/my-project\n```\n\nTo bring up the Coastguard observability UI for your project:\n\n```bash\ncoast ui\n```\n\n## What's Next?\n\n- Set up a [skill for your host agent](SKILLS_FOR_HOST_AGENTS.md) so it knows how to interact with Coasts\n", + "README.md": "# Coasts Documentation\n\n```youtube\nMBGKSKau4sU\nPart of the [Coasts Video Course](learn-coasts-videos/README.md).\n```\n\n## Installing\n\n- `eval \"$(curl -fsSL https://coasts.dev/install)\"`\n- `coast daemon install`\n\n*If you decide not to run `coast daemon install`, you are responsible for starting the daemon manually with `coast daemon start` every single time.*\n\n## What Are Coasts?\n\nA Coast (**containerized host**) is a local development runtime. Coasts let you run multiple isolated environments for the same project on one machine.\n\nCoasts are especially useful for complex `docker-compose` stacks with many interdependent services, but they are equally effective for non-containerized local dev setups. Coasts support a wide range of [runtime configuration patterns](concepts_and_terminology/RUNTIMES_AND_SERVICES.md) so you can shape the ideal environment for multiple agents working in parallel.\n\nCoasts are built for local development, not as a hosted cloud service. Your environments run locally on your machine.\n\nThe Coasts project is free, local, MIT-licensed, agent-provider agnostic, and agent-harness agnostic software with no AI upsells.\n\nCoasts work with any agentic coding workflow that uses worktrees. No special harness-side configuration is required.\n\n## Why Coasts for Worktrees\n\nGit worktrees are excellent for isolating code changes, but they do not solve runtime isolation by themselves.\n\nWhen you run multiple worktrees in parallel, you quickly hit ergonomic problems:\n\n- [Port conflicts](concepts_and_terminology/PORTS.md) between services that expect the same host ports.\n- Per-worktree database and [volume setup](concepts_and_terminology/VOLUMES.md) that is tedious to manage.\n- Integration test environments that need custom runtime wiring per worktree.\n- The living hell of switching worktrees and rebuilding runtime context each time. See [Assign and Unassign](concepts_and_terminology/ASSIGN.md).\n\nIf Git is version control for your code, Coasts are like Git for your worktree runtimes.\n\nEach environment gets its own ports, so you can inspect any worktree runtime in parallel. When you [check out](concepts_and_terminology/CHECKOUT.md) a worktree runtime, Coasts remap that runtime to your project's canonical ports.\n\nCoasts abstract runtime configuration into a simple modular layer on top of worktrees, so each worktree can run with the isolation it needs without hand-maintaining complex per-worktree setup.\n\n## Requirements\n\n- macOS or Linux\n- Docker Desktop on macOS, or Docker Engine with the Compose plugin on Linux\n- A project using Git\n- Node.js\n- `socat` (`brew install socat` on macOS, `sudo apt install socat` on Ubuntu)\n\n```text\nLinux note: Dynamic ports work out of the box on Linux.\nIf you need canonical ports below `1024`, see the checkout docs for the required host configuration.\n```\n\n## Containerizing Agents?\n\nYou can containerize an agent with a Coast. That might sound like a great idea at first, but in many cases you do not actually need to run your coding agent inside a container.\n\nBecause Coasts share the [filesystem](concepts_and_terminology/FILESYSTEM.md) with your host machine through a shared volume mount, the easiest and most reliable workflow is to run the agent on your host and instruct it to execute runtime-heavy tasks (such as integration tests) inside the Coast instance using [`coast exec`](concepts_and_terminology/EXEC_AND_DOCKER.md).\n\nHowever, if you do want to run your agent in a container, Coasts absolutely support that via [Agent Shells](concepts_and_terminology/AGENT_SHELLS.md). You can build an incredibly intricate rig for this setup including [MCP server configuration](concepts_and_terminology/MCP_SERVERS.md), but it may not interoperate cleanly with the orchestration software that exists today. For most workflows, host-side agents are simpler and more reliable.\n\n## Coasts vs Dev Containers\n\nCoasts are not dev containers, and they are not the same thing.\n\nDev containers are generally designed for mounting an IDE into a single containerized development workspace. Coasts are headless and optimized as lightweight environments for parallel agent usage with worktrees — multiple isolated, worktree-aware runtime environments running side by side, with fast checkout switching and runtime isolation controls for each instance.\n\n## Demo Repo\n\nIf you want a small example project to try with Coasts, start with the [`coasts-demo` repository](https://github.com/coast-guard/coasts-demo).\n\n## Coasts Video Course\n\nIf you prefer video, the [Coasts Video Course](learn-coasts-videos/README.md) covers every core concept in under three minutes each.\n\n", + "GETTING_STARTED.md": "# Getting Started with Coasts\n\n```youtube\nJe921fgJ4RY\nPart of the [Coasts Video Course](learn-coasts-videos/README.md).\n```\n\n## Installing\n\n```bash\neval \"$(curl -fsSL https://coasts.dev/install)\"\ncoast daemon install\n```\n\n*If you decide not to run `coast daemon install`, you are responsible for starting the daemon manually with `coast daemon start` every single time.*\n\n## Requirements\n\n- macOS or Linux\n- Docker Desktop on macOS, or Docker Engine with the Compose plugin on Linux\n- A project using Git\n- Node.js\n- `socat` (`brew install socat` on macOS, `sudo apt install socat` on Ubuntu)\n\n```text\nLinux note: Dynamic ports work out of the box on Linux.\nIf you need canonical ports below `1024`, see the checkout docs for the required host configuration.\n```\n\n## Setting Up Coasts in a Project\n\nAdd a Coastfile to the root of your project. Make sure you are not on a worktree when installing.\n\n```text\nmy-project/\n├── Coastfile <-- this is what Coast reads\n├── docker-compose.yml\n├── Dockerfile\n├── src/\n│ └── ...\n└── ...\n```\n\nThe `Coastfile` points at your existing local development resources and adds Coasts-specific configuration — see the [Coastfiles documentation](coastfiles/README.md) for the full schema:\n\n```toml\n[coast]\nname = \"my-project\"\ncompose = \"./docker-compose.yml\"\n\n[ports]\nweb = 3000\ndb = 5432\n```\n\nA Coastfile is a lightweight TOML file that *typically* points to your existing `docker-compose.yml` (it also works with non-containerized local dev setups) and describes the modifications needed to run your project in parallel — port mappings, volume strategies, and secrets. Place it at your project root.\n\nThe fastest way to create a Coastfile for your project is to let your coding agent do it.\n\nThe Coasts CLI ships with a built-in prompt that teaches any AI agent the full Coastfile schema and CLI. Copy it into your agent's chat and it will analyze your project and generate a Coastfile.\n\n```prompt-copy\ninstallation_prompt.txt\n```\n\nYou can also get the same output from the CLI by running `coast installation-prompt`.\n\n## Your First Coast\n\nBefore starting your first Coast, bring down any running development environment. If you are using Docker Compose, run `docker-compose down`. If you have local dev servers running, stop them. Coasts manage their own ports and will conflict with anything already listening.\n\nOnce your Coastfile is ready:\n\n```bash\ncoast build\ncoast run dev-1\n```\n\nCheck that your instance is running:\n\n```bash\ncoast ls\n\n# NAME PROJECT STATUS BRANCH RUNTIME WORKTREE CO ROOT\n# dev-1 my-project running main dind - ~/dev/my-project\n```\n\nSee where your services are listening:\n\n```bash\ncoast ports dev-1\n\n# SERVICE CANONICAL DYNAMIC\n# ★ web 3000 62217\n# db 5432 55681\n```\n\nEach instance gets its own set of dynamic ports so multiple instances can run side by side. To map an instance back to your project's canonical ports, check it out:\n\n```bash\ncoast checkout dev-1\n```\n\nThis means the runtime is now checked out and your project's canonical ports (like `3000`, `5432`) will route to this Coast instance.\n\n```bash\ncoast ls\n\n# NAME PROJECT STATUS BRANCH RUNTIME WORKTREE CO ROOT\n# dev-1 my-project running main dind - ✓ ~/dev/my-project\n```\n\nTo bring up the Coastguard observability UI for your project:\n\n```bash\ncoast ui\n```\n\n## What's Next?\n\n- Set up a [skill for your host agent](SKILLS_FOR_HOST_AGENTS.md) so it knows how to interact with Coasts\n", "SKILLS_FOR_HOST_AGENTS.md": "# Skills for Host Agents\n\nIf you use AI coding agents on the host while your app runs inside Coasts, your\nagent usually needs two Coast-specific pieces of setup:\n\n1. an always-on Coast Runtime section in the harness's project instruction file\n or rule file\n2. a reusable Coast workflow skill such as `/coasts` when the harness supports\n project skills\n\nWithout the first piece, the agent edits files but forgets to use `coast exec`.\nWithout the second, every Coast assignment, log, and UI flow has to be\nre-explained in chat.\n\nThis guide keeps the setup concrete and Coast-specific: which file to create,\nwhat text goes in it, and how that changes by harness.\n\n## Why agents need this\n\nCoasts share the [filesystem](concepts_and_terminology/FILESYSTEM.md) between\nyour host machine and the Coast container. Your agent edits files on the host\nand the running services inside the Coast see the changes immediately. But the\nagent still needs to:\n\n1. discover which Coast instance matches the current checkout\n2. run tests, builds, and runtime commands inside that Coast\n3. read logs and service status from the Coast\n4. handle worktree assignment safely when no Coast is already attached\n\n## What goes where\n\n- `AGENTS.md`, `CLAUDE.md`, or `.cursor/rules/coast.md` — short Coast rules\n that should apply on every task, even if no skill is invoked\n- skill (`.agents/skills/...`, `.claude/skills/...`, or `.cursor/skills/...`)\n — the reusable Coast workflow itself, such as `/coasts`\n- command file (`.claude/commands/...` or `.cursor/commands/...`) — optional\n explicit entrypoint for harnesses that support it; one simple option is to\n have the command reuse the skill\n\nIf one repo uses more than one harness, keep the canonical Coast skill in one\nplace and expose it where needed. See\n[Multiple Harnesses](harnesses/MULTIPLE_HARNESSES.md).\n\n## 1. Always-on Coast Runtime rules\n\nAdd the following block to the harness's always-on project instruction file or\nrule file (`AGENTS.md`, `CLAUDE.md`, `.cursor/rules/coast.md`, or equivalent):\n\n```text-copy\n# Coast Runtime\n\nThis project uses Coasts — containerized runtimes for running services, tests,\nand other runtime commands. The filesystem is shared between the host and the\ncontainer, so file edits on either side are visible to both immediately.\n\n## Discovery\n\nBefore the first runtime command in a session, run:\n\n coast lookup\n\nThis prints the instance name, ports, and example commands. Use the instance\nname from the output for all subsequent commands.\n\n## What runs where\n\nThe filesystem is shared, so only use `coast exec` for things that need the\ncontainer runtime (databases, services, integration tests). Everything else\nruns directly on the host.\n\nUse `coast exec` for:\n- Tests that need running services (integration tests, API tests)\n- Service restarts or compose operations\n- Anything that talks to databases, caches, or other container services\n\nRun directly on the host:\n- Linting, typechecking, formatting\n- Git operations\n- Playwright and browser tests\n- Installing host-side dependencies (npm install, pip install)\n- File search, code generation, static analysis\n\nExample:\n\n coast exec -- sh -c \"cd && npm test\" # needs DB\n coast exec --service # service shell\n npm run lint # host is fine\n npx playwright test # host is fine\n\n## Runtime feedback\n\n coast ps \n coast logs --service \n coast logs --service --tail 50\n\n## Creating and assigning Coasts\n\nIf `coast lookup` returns no match, run `coast ls` to see what exists.\n\nIf an unassigned Coast is already running for this project, prefer assigning\nyour worktree to it rather than creating a new one:\n\n coast assign -w \n\nIf no Coast is running, ask the user before creating one — Coasts can be\nmemory intensive:\n\n coast run -w \n\nA project must be built before instances can be created. If `coast run` fails\nbecause no build exists, run `coast build` first.\n\n## Coastfile setup\n\nIf the project does not have a Coastfile yet, or if you need to modify the\nCoastfile, read the Coastfile docs first:\n\n coast docs --path coastfiles/README.md\n\n## When confused\n\nBefore guessing about Coast behavior, explore the docs:\n\n coast docs # list all doc pages\n coast docs --path concepts_and_terminology/RUN.md\n coast docs --path concepts_and_terminology/ASSIGN.md\n coast docs --path concepts_and_terminology/BUILDS.md\n coast search-docs \"your question here\" # semantic search\n\n## Troubleshooting\n\nIf you run into issues with harness configuration (e.g. worktrees not being\nfound, `coast lookup` not matching), read the troubleshooting section of the\nrelevant harness doc:\n\n coast docs --path harnesses/CLAUDE_CODE.md\n coast docs --path harnesses/CODEX.md\n coast docs --path harnesses/CONDUCTOR.md\n coast docs --path harnesses/CURSOR.md\n coast docs --path harnesses/T3_CODE.md\n coast docs --path harnesses/SHEP.md\n\n## Rules\n\n- Always run `coast lookup` before your first runtime command in a session.\n- Use `coast exec` only for things that need the container runtime.\n- Use `coast exec --service ` when you need to run inside an app/service container.\n- Run linting, typechecking, formatting, and git on the host directly.\n- Use `coast docs` or `coast search-docs` before guessing about Coast behavior.\n- Do not run services directly on the host when the project expects Coast.\n```\n\nThis block belongs in the always-on file because the rules should apply on\nevery task, not only when the agent explicitly enters a `/coasts` workflow.\n\n## 2. Reusable `/coasts` skill\n\nWhen the harness supports project skills, save the skill content as a\n`SKILL.md` in your skills directory. The full skill text is in\n[skills_prompt.txt](skills_prompt.txt) (if in CLI mode, use\n`coast skills-prompt`) — everything after the Coast Runtime block is the skill\ncontent, starting from the `---` frontmatter.\n\nIf you are using Codex or OpenAI-specific surfaces, you can optionally add\n`agents/openai.yaml` beside the skill for display metadata or invocation\npolicy. That metadata should live beside the skill, not replace it.\n\n## Harness quick start\n\n| Harness | Always-on file | Reusable Coast workflow | Notes |\n|---------|----------------|-------------------------|-------|\n| OpenAI Codex | `AGENTS.md` | `.agents/skills/coasts/SKILL.md` | No separate project command file to recommend for Coast docs. See [Codex](harnesses/CODEX.md). |\n| Claude Code | `CLAUDE.md` | `.claude/skills/coasts/SKILL.md` | `.claude/commands/coasts.md` is optional, but keep the logic in the skill. See [Claude Code](harnesses/CLAUDE_CODE.md). |\n| Cursor | `AGENTS.md` or `.cursor/rules/coast.md` | `.cursor/skills/coasts/SKILL.md` or shared `.agents/skills/coasts/SKILL.md` | `.cursor/commands/coasts.md` is optional. `.cursor/worktrees.json` is for Cursor worktree bootstrap, not Coast policy. See [Cursor](harnesses/CURSOR.md). |\n| Conductor | `CLAUDE.md` | Start with `CLAUDE.md`; use Conductor scripts and settings for Conductor-specific behavior | Do not assume full Claude Code project command behavior. If a new command does not appear, fully close and reopen Conductor. See [Conductor](harnesses/CONDUCTOR.md). |\n| T3 Code | `AGENTS.md` | `.agents/skills/coasts/SKILL.md` | This is the most limited harness surface here. Use the Codex-style layout and do not invent a T3-native command layer for Coast docs. See [T3 Code](harnesses/T3_CODE.md). |\n\n## Let the agent set itself up\n\nThe fastest way is to let the agent write the right files itself. Copy the\nprompt below into your agent's chat — it includes the Coast Runtime block, the\n`coasts` skill block, and harness-specific instructions for where each piece\nbelongs.\n\n```prompt-copy\nskills_prompt.txt\n```\n\nYou can also get the same output from the CLI by running `coast skills-prompt`.\n\n## Manual setup\n\n- **Codex:** put the Coast Runtime section in `AGENTS.md`, then put the\n reusable `coasts` skill in `.agents/skills/coasts/SKILL.md`.\n- **Claude Code:** put the Coast Runtime section in `CLAUDE.md`, then put the\n reusable `coasts` skill in `.claude/skills/coasts/SKILL.md`. Only add\n `.claude/commands/coasts.md` if you specifically want a command file.\n- **Cursor:** put the Coast Runtime section in `AGENTS.md` if you want the most\n portable instructions, or in `.cursor/rules/coast.md` if you want a\n Cursor-native project rule. Put the reusable `coasts` workflow in\n `.cursor/skills/coasts/SKILL.md` for a Cursor-only repo, or in\n `.agents/skills/coasts/SKILL.md` if the repo is shared with other harnesses.\n Only add `.cursor/commands/coasts.md` if you specifically want an explicit\n command file.\n- **Conductor:** put the Coast Runtime section in `CLAUDE.md`. Use Conductor\n Repository Settings scripts for Conductor-specific bootstrap or run behavior.\n If you add a command and it does not appear, fully close and reopen the app.\n- **T3 Code:** use the same layout as Codex: `AGENTS.md` plus\n `.agents/skills/coasts/SKILL.md`. Treat T3 Code as a thin Codex-style\n harness here, not as a separate Coast command surface.\n- **Multiple harnesses:** keep the canonical skill in\n `.agents/skills/coasts/SKILL.md`. Cursor can load that directly; expose it to\n Claude Code through `.claude/skills/coasts/` if needed.\n\n## Further reading\n\n- Read the [Harnesses guide](harnesses/README.md) for the per-harness matrix\n- Read [Multiple Harnesses](harnesses/MULTIPLE_HARNESSES.md) for the shared\n layout pattern\n- Read the [Coastfiles documentation](coastfiles/README.md) to learn the full\n configuration schema\n- Learn the [Coast CLI](concepts_and_terminology/CLI.md) commands for managing\n instances\n- Explore [Coastguard](concepts_and_terminology/COASTGUARD.md), the web UI for\n observing and controlling your Coasts\n", "doc_ordering.txt": "# Top-level\nREADME.md\nGETTING_STARTED.md\nSKILLS_FOR_HOST_AGENTS.md\n\n# Learn Coasts\nlearn-coasts-videos/README.md\nlearn-coasts-videos/coasts.md\nlearn-coasts-videos/ports.md\nlearn-coasts-videos/assign.md\nlearn-coasts-videos/checkout.md\nlearn-coasts-videos/volumes.md\nlearn-coasts-videos/secrets.md\nlearn-coasts-videos/getting-started.md\nlearn-coasts-videos/coast-ui.md\n\n# Harnesses\nharnesses/README.md\nharnesses/CODEX.md\nharnesses/CONDUCTOR.md\nharnesses/CLAUDE_CODE.md\nharnesses/CURSOR.md\nharnesses/T3_CODE.md\nharnesses/SHEP.md\nharnesses/MULTIPLE_HARNESSES.md\n\n# Concepts and Terminology\nconcepts_and_terminology/README.md\nconcepts_and_terminology/COASTS.md\nconcepts_and_terminology/RUN.md\nconcepts_and_terminology/REMOVE.md\nconcepts_and_terminology/FILESYSTEM.md\nconcepts_and_terminology/DAEMON.md\nconcepts_and_terminology/CLI.md\nconcepts_and_terminology/COASTGUARD.md\nconcepts_and_terminology/PORTS.md\nconcepts_and_terminology/PRIMARY_PORT_AND_DNS.md\nconcepts_and_terminology/ASSIGN.md\nconcepts_and_terminology/CHECKOUT.md\nconcepts_and_terminology/LOOKUP.md\nconcepts_and_terminology/VOLUMES.md\nconcepts_and_terminology/SHARED_SERVICES.md\nconcepts_and_terminology/SECRETS.md\nconcepts_and_terminology/BUILDS.md\nconcepts_and_terminology/COASTFILE_TYPES.md\nconcepts_and_terminology/RUNTIMES_AND_SERVICES.md\nconcepts_and_terminology/BARE_SERVICES.md\nconcepts_and_terminology/MIXED_SERVICE_TYPES.md\nconcepts_and_terminology/LOGS.md\nconcepts_and_terminology/EXEC_AND_DOCKER.md\nconcepts_and_terminology/AGENT_SHELLS.md\nconcepts_and_terminology/MCP_SERVERS.md\nconcepts_and_terminology/PERFORMANCE_OPTIMIZATIONS.md\nconcepts_and_terminology/TROUBLESHOOTING.md\n\n# Coastfiles\ncoastfiles/README.md\ncoastfiles/PROJECT.md\ncoastfiles/WORKTREE_DIR.md\ncoastfiles/PORTS.md\ncoastfiles/SHARED_SERVICES.md\ncoastfiles/SERVICES.md\ncoastfiles/SECRETS.md\ncoastfiles/VOLUMES.md\ncoastfiles/ASSIGN.md\ncoastfiles/INHERITANCE.md\ncoastfiles/AGENT_SHELL.md\ncoastfiles/MCP.md\n\n# Recipes\nrecipes/README.md\nrecipes/FULLSTACK_MONOREPO.md\n\n", "installation_prompt.txt": "You are installing Coasts into this project. Coast (containerized host) is a CLI tool that runs multiple isolated development environments on a single machine using Docker-in-Docker containers. Each environment gets its own ports, volumes, and runtime — ideal for parallel worktree workflows.\n\nYour job: analyze this project and generate a Coastfile (a TOML file named \"Coastfile\" at the project root).\n\n=== DOCUMENTATION ===\n\nCoast has built-in docs accessible from the CLI. Use these to understand the full Coastfile schema, volume strategies, assign behavior, and other configuration options before generating a Coastfile.\n\nBrowse the docs tree:\n\n coast docs\n\nThis prints the full docs tree. Start by reading the README files — they provide indexes to help you find the right documentation for each topic:\n\n coast docs --path README.md\n coast docs --path coastfiles/README.md\n coast docs --path concepts_and_terminology/README.md\n\nRead a specific doc:\n\n coast docs --path coastfiles/PROJECT.md\n coast docs --path coastfiles/VOLUMES.md\n\nSearch the docs (semantic search — describe what you're looking for in natural language):\n\n coast search-docs \"how do volume strategies work\"\n coast search-docs \"shared postgres across instances\"\n coast search-docs \"secret injection from environment variables\"\n\nUse the docs to make informed decisions about this project's Coastfile configuration. The coastfiles/ section covers every Coastfile directive in detail.\n\n=== COASTFILE SCHEMA (quick reference) ===\n\n[coast] — Required. Project metadata.\n\n name (string, required) Project identifier used in container/volume naming.\n compose (string, optional) Path to docker-compose.yml relative to the Coastfile.\n runtime (string, optional) \"dind\" (default), \"sysbox\", or \"podman\".\n root (string, optional) Project root override (relative or absolute).\n worktree_dir (string or array, optional) Directory or directories for git worktrees (default: \".worktrees\"). Accepts a single string or an array of strings. Auto-detected from existing worktrees at runtime.\n\n[coast.setup] — Optional. Customize the DinD container itself.\n\n packages (array of strings) Alpine packages to install (e.g. [\"nodejs\", \"npm\", \"git\"]).\n run (array of strings) Arbitrary commands to run during setup.\n\n[ports] — Required (at least one). Map of logical name to port number.\n These ports are forwarded to the host when the coast is checked out.\n\n Example:\n [ports]\n web = 3000\n api = 8080\n postgres = 5432\n\n[volumes.*] — Optional. Per-volume configuration.\n\n strategy \"isolated\" (default) or \"shared\"\n service Compose service name that owns this volume.\n mount Mount path inside the service container.\n snapshot_source (isolated only) Seed from an existing volume name.\n\n Example:\n [volumes.postgres_data]\n strategy = \"isolated\"\n service = \"db\"\n mount = \"/var/lib/postgresql/data\"\n\n[secrets.*] — Optional. Secret extraction and injection.\n\n extractor \"file\", \"env\", \"command\", or \"macos-keychain\"\n inject \"env:VAR_NAME\" or \"file:/path/in/container\"\n ttl Optional expiry (e.g. \"1h\", \"30m\").\n\n Extractor-specific params:\n file: path = \"./path/to/secret\"\n env: var = \"HOST_ENV_VAR\"\n command: run = \"echo secret-value\"\n macos-keychain: item = \"keychain-item-name\"\n\n Example:\n [secrets.db_password]\n extractor = \"env\"\n var = \"DB_PASSWORD\"\n inject = \"env:DATABASE_PASSWORD\"\n\n[inject] — Optional. Non-secret host file/env injection.\n\n env Array of host env var names to forward.\n files Array of host file paths to mount.\n\n Example:\n [inject]\n env = [\"NODE_ENV\", \"DEBUG\"]\n files = [\"~/.ssh/id_ed25519\", \"~/.gitconfig\"]\n\n[shared_services.*] — Optional. Services on the host Docker daemon shared across instances.\n\n image Docker image.\n ports Array of port numbers.\n volumes Array of volume mounts.\n env Inline table of environment variables.\n auto_create_db (bool) Create a per-instance database automatically.\n inject Inject connection string into coast containers.\n\n Example:\n [shared_services.postgres]\n image = \"postgres:16-alpine\"\n ports = [5432]\n volumes = [\"postgres_data:/var/lib/postgresql/data\"]\n env = { POSTGRES_USER = \"dev\", POSTGRES_PASSWORD = \"dev\", POSTGRES_DB = \"app\" }\n auto_create_db = true\n inject = \"env:DATABASE_URL\"\n\n[assign] — Optional. Controls what happens on branch switch (coast assign).\n\n default \"none\", \"restart\", or \"rebuild\"\n [assign.services] Per-service overrides.\n [assign.rebuild_triggers] Per-service file globs that trigger rebuild.\n\n Example:\n [assign]\n default = \"none\"\n [assign.services]\n api = \"restart\"\n worker = \"rebuild\"\n [assign.rebuild_triggers]\n worker = [\"Dockerfile\", \"package.json\"]\n\n[services.*] — Optional. Bare process services (no docker-compose needed).\n\n command Shell command to run.\n port Port number.\n restart \"on-failure\" or \"always\".\n\n Example:\n [services.web]\n command = \"node server.js\"\n port = 3000\n restart = \"on-failure\"\n\n=== EXAMPLE: Minimal (no compose) ===\n\n[coast]\nname = \"my-app\"\nruntime = \"dind\"\n\n[coast.setup]\npackages = [\"nodejs\", \"npm\"]\n\n[ports]\napp = 3000\n\n=== EXAMPLE: With docker-compose ===\n\n[coast]\nname = \"my-app\"\ncompose = \"./docker-compose.yml\"\nruntime = \"dind\"\n\n[ports]\napp = 3000\npostgres = 5432\nredis = 6379\n\n[volumes.postgres_data]\nstrategy = \"shared\"\nservice = \"db\"\nmount = \"/var/lib/postgresql/data\"\n\n[volumes.redis_data]\nstrategy = \"isolated\"\nservice = \"cache\"\nmount = \"/data\"\n\n[assign]\ndefault = \"none\"\n\n[assign.services]\napp = \"rebuild\"\n\n=== EXAMPLE: With secrets ===\n\n[coast]\nname = \"my-app\"\ncompose = \"./docker-compose.yml\"\nruntime = \"dind\"\n\n[ports]\napp = 3000\n\n[secrets.api_key]\nextractor = \"env\"\nvar = \"API_KEY\"\ninject = \"env:API_KEY\"\n\n[secrets.ssh_key]\nextractor = \"file\"\npath = \"~/.ssh/id_ed25519\"\ninject = \"file:/run/secrets/ssh_key\"\n\n=== KEY TRADEOFFS TO DISCUSS WITH THE USER ===\n\nBefore generating the Coastfile, ask the user about any ambiguous configuration choices. Here are the main ones:\n\nDatabase and infrastructure strategy — there are three options for services like postgres and redis:\n - Isolated volumes (default): each Coast instance gets its own copy of the data inside its DinD container. Instances cannot interfere with each other. Best when you want per-branch database state.\n - Shared volumes: all instances read and write the same volume inside their DinD containers. Saves disk space but concurrent writes from multiple instances can corrupt data.\n - Shared services: run the database on the host Docker daemon instead of inside each Coast. All instances connect to one shared server. Uses the least memory, supports auto_create_db for per-instance databases on a single postgres, and data outlives instance deletion. Best for large teams or memory-constrained machines.\n - If the project has a database, ask the user which approach they want. Explain the tradeoffs — isolated is safest, shared services is most memory-efficient.\n\nAssign strategy — what happens when switching a Coast between worktrees:\n - \"none\": do nothing (for services like postgres/redis that don't change between branches).\n - \"restart\": restart the container (for interpreted services that just need a process restart).\n - \"rebuild\": rebuild the Docker image and restart (for services where the branch change affects the Dockerfile or build dependencies).\n - If the project has multiple services, ask which ones need rebuilding vs restarting on branch switch.\n\n=== INSTRUCTIONS ===\n\n1. Look at this project's structure. If there is a docker-compose.yml, read it to identify services, ports, and volumes.\n2. Detect the existing git worktree directory. Run `git worktree list` to check if the project already has git worktrees set up.\n - If worktrees exist, examine their paths to determine the common parent directory (e.g., if worktrees are at `../.worktrees/feat-a` and `../.worktrees/feat-b`, the worktree_dir is `\"../.worktrees\"`).\n - Set `worktree_dir` in the Coastfile to match the detected directory.\n - If no worktrees exist, omit `worktree_dir` (Coast defaults to \".worktrees\"). Do NOT use \".coasts\" — that pollutes the project with a Coast-branded directory.\n3. Ask the user if they use any of these coding harnesses with this project:\n - **Claude Code** — worktrees at `.claude/worktrees`\n - **OpenAI Codex** — worktrees at `~/.codex/worktrees`\n - **Cursor** — worktrees at `~/.cursor/worktrees/` (where `` is the coast name from `[coast] name`)\n - **Conductor** — worktrees at `~/conductor/workspaces/`\n - **T3 Code** — worktrees at `~/.t3/worktrees/`\n For each harness the user selects, include its worktree directory in the `worktree_dir` array. Combine these with any directory detected in step 2. If the user selects none and no worktrees were detected in step 2, omit `worktree_dir` (Coast defaults to \".worktrees\").\n4. Read the relevant Coast docs (use `coast docs` and `coast search-docs`) to understand volume strategies, assign behavior, and any configuration options that apply to this project's stack.\n5. Ask the user about any ambiguous configuration choices (see tradeoffs above). Do not guess — explain the options and let them decide.\n6. Generate a Coastfile at the project root based on the project analysis and user input.\n7. If the project has no docker-compose.yml, use [services.*] for bare process definitions or [coast.setup] to install dependencies.\n8. Run `coast build`. If it fails, check the error and consult the docs (`coast search-docs \"\"`) to troubleshoot.\n9. Run `coast run dev-1`. If it fails, check the error and consult the docs.\n10. Run `coast ui` to open the Coastguard dashboard (this is for the user when you are done).\n", diff --git a/docs/GETTING_STARTED.md b/docs/GETTING_STARTED.md index 1c27bd3..3ab9b5a 100644 --- a/docs/GETTING_STARTED.md +++ b/docs/GETTING_STARTED.md @@ -8,7 +8,7 @@ Part of the [Coasts Video Course](learn-coasts-videos/README.md). ## Installing ```bash -curl -fsSL https://coasts.dev/install | sh +eval "$(curl -fsSL https://coasts.dev/install)" coast daemon install ``` diff --git a/docs/README.md b/docs/README.md index 5071977..4c407ef 100644 --- a/docs/README.md +++ b/docs/README.md @@ -7,7 +7,7 @@ Part of the [Coasts Video Course](learn-coasts-videos/README.md). ## Installing -- `curl -fsSL https://coasts.dev/install | sh` +- `eval "$(curl -fsSL https://coasts.dev/install)"` - `coast daemon install` *If you decide not to run `coast daemon install`, you are responsible for starting the daemon manually with `coast daemon start` every single time.*