Coasts Documentation

coast-service is a remote control plane for Coast. It runs on a remote machine and manages Docker-in-Docker (DinD) containers on behalf of a local coast-daemon. The daemon communicates with coast-service over an SSH tunnel, allowing users to manage remote environments without changing their local workflow.

coast-service is an Axum-based HTTP server that mirrors local daemon operations such as build, run, assign, exec, ps, logs, stop, start, rm, secrets, and service restarts. It manages its own SQLite state, Docker containers, and dynamic port allocation.

The coast ssg CLI (also aliased as coast shared-service-group) is used to manage Shared Service Groups (SSG). Every subcommand interacts with a local daemon via a Unix socket.

Most commands automatically determine the project context by reading the [coast].name from the Coastfile in the current directory. You can override this using the --working-dir <dir> flag. The only exception is coast ssg ls, which works across all projects known to the daemon.

All commands support a global --silent / -s flag to suppress progress output and only print summaries or errors.

Coastguard provides a visual surface to monitor and manage your Coast environment. Key capabilities include:

• Project Monitoring: View projects, instances, statuses, branches, and checkout states.
• Service Management: Inspect port mappings and jump directly into services.
• Observability: View logs, runtime statistics, and inspect data.
• Resource Inspection: Browse builds, image artifacts, volumes, and secrets metadata.
• Documentation: Navigate project documentation directly within the app.

The Coast CLI (coast) is the primary command-line interface for interacting with Coasts. It is designed to be minimalist: it parses your command, sends the request to the coastd daemon, and returns structured results to your terminal.

Use the CLI for:

• Operational workflows: Building, running, assigning, and managing ports/checkouts.
• Automation: Writing scripts, CI/CD tasks, and agent-based workflows.
• Documentation: Searching and retrieving project documentation.

# Typical operational commands
coast build
coast run dev-1
coast assign dev-1 --worktree feature/oauth
coast ports dev-1
coast checkout dev-1

coast-ssg is a library crate that provides a Singleton Shared Service Group (SSG) runtime. It runs infrastructure services inside a single Docker-in-Docker (DinD) container so that multiple Coast projects can share them without port collisions.

Key Architectural Details:

• Dependencies: coast-daemon depends on this crate. coast-cli routes commands via coast ssg <verb> through the daemon.
• Remote Access: coast-service does not depend on this crate. Remote coasts access the local SSG using the SharedServicePortForward protocol combined with reverse SSH tunnels. The local daemon handles rewriting the tunnel's local side from a canonical port to the SSG dynamic port.
• Status: Currently in Phase 0 (scaffolding only).

A Coastfile is a TOML configuration file located at the root of your project. It defines how Coast builds and runs isolated development environments, including which services to run, which ports to forward, how to manage data (volumes), and how to handle secrets.

Key Characteristics:

• Naming: Must be named Coastfile (capital C, no extension). You can use Coastfile.toml for editor syntax highlighting.
• Variants: You can create typed variants like Coastfile.light or Coastfile.snap that inherit from the base file.
• Optionality: Coastfiles are optional; you can build environments using CLI flags like --name and --compose with coast build.

coast-service is the remote control plane for a Remote Coast. It is an Axum-based HTTP server listening on port 31420 on the remote machine.

Key Responsibilities:

• Lifecycle Management: Mirrors daemon operations like build, run, assign, exec, ps, logs, stop, start, and rm.
• Resource Management: Manages its own SQLite state database, Docker containers (DinD), dynamic port allocation, build artifacts, and image cache.
• Security: Manages an encrypted keystore for secrets.

Security Note: coast-service is designed to be accessed exclusively via the SSH tunnel created by the local daemon; it should never be exposed to the public internet.

A Coast is a self-contained runtime for your project. It operates as a single instance running inside a Docker-in-Docker container. A single Coast can host multiple services simultaneously, such as a web server, database, and cache (e.g., web, postgres, and redis).

Key characteristics:

• Isolation: Each Coast is isolated, allowing you to run multiple instances of the same project in parallel.
• Dynamic Port Mapping: Every Coast exposes its services via dynamic ports on the host machine to prevent conflicts.
• Worktree Assignment: Coasts are typically assigned to specific worktrees, which prevents port and volume collisions when running multiple versions of a project.

Remote Coasts use a three-hop dynamic port chain. This allows multiple instances of the same project to run on a single remote machine without port conflicts, as every layer uses dynamic allocation.

The Chain Flow:

1. localhost:3000 (The canonical port you use via coast checkout and socat)
2. localhost:{local_dynamic} (Allocated by the local daemon port manager)
3. remote:{remote_dynamic} (Allocated by the remote coast-service port manager via SSH -L)
4. DinD container :3000 (The canonical port where your application is actually listening)