--- name: orbit description: Operate and diagnose local development environments with the Orbit CLI. Use whenever a task involves installing or setting up Orbit for the first time, starting or stopping services or containers, checking environment status, switching or syncing environments, reading logs or traces, querying local infrastructure, publishing or resetting development databases, claiming callback tunnels, or troubleshooting an Orbit-managed workspace. --- # Orbit Use Orbit as the control plane for the local environment. Prefer its structured CLI over invoking Docker, databases, or service processes directly. ## Setup If `orbit` is not installed, identify the host platform and explain the matching official installer. A request that explicitly authorizes installing Orbit includes approval for the official Orbit CLI installer; otherwise get approval before running it. On macOS or Linux: ```bash curl -fsSL https://raw.githubusercontent.com/iml885203/orbit/main/scripts/install.sh | bash ``` On Windows PowerShell (Beta): ```powershell irm https://raw.githubusercontent.com/iml885203/orbit/main/scripts/install.ps1 | iex ``` Read the installer's reported `Installed:` path and verify the result with `orbit version --json`, invoking that exact binary path when needed. Agent shell calls may not preserve PATH changes; if a later call cannot find `orbit`, invoke the installed path or prefix that call with the path the installer reported. Do not install or update Docker, package managers, or project runtimes without the user's approval. Docker must be running when the selected environment declares containers; the public demo does. When the user explicitly authorized the Orbit plugin, install the official plugin for the current coding agent when that surface supports plugins. A newly installed plugin may load only in a new agent session: continue the current task with this skill, then mention the restart at handoff. Plugin activation is never a reason to stop onboarding. Claude Code: ```bash claude plugin marketplace add iml885203/orbit claude plugin install orbit@orbit ``` Codex CLI: ```bash codex plugin marketplace add iml885203/orbit codex plugin add orbit@orbit ``` Then pick the path that matches the user: - **They explicitly asked for the public demo** — work from a new empty directory with no ancestor `orbit.yaml`. Run `orbit inspect --json`, follow its exact non-destructive `orbit init --yes --json` action, and continue the core loop. Do not present the other setup paths unless the request is ambiguous. - **Their project already has `orbit.yaml`** — identify the application workflow the user expects to work, then enter the core loop. Orbit finds the nearest config from anywhere inside the project. A ready but incomplete resource selection is not proof that the existing file covers that workflow. - **They have a team environment repository** — `orbit init --yes --source --url [--env ]` configures a named source, syncs the repository, and selects an environment. - **Their real project has no `orbit.yaml`** — inspect its existing development setup first, then author the project-local config before the first Orbit inspect. Do not run the `setup_required` demo initialization action in this branch. Start a new config with `version: "3"` and only documented top-level fields; a project display name is not a top-level schema field. An explicit request to set up or run the project with Orbit authorizes the narrowest non-destructive, project-local `orbit.yaml` and support files needed for that goal: summarize the resources and checks, then continue without asking for a second approval. Ask before writing only when the user requested assessment or a plan rather than implementation. When the project uses another local orchestrator, migrate its resources directly instead of wrapping it as one opaque Orbit service, but preserve the existing orchestration path unless removal is explicitly requested. For an Aspire AppHost, read [references/aspire-migration.md](references/aspire-migration.md). - **They have neither a project nor an environment** — run `orbit inspect --json` and follow its exact setup action. The public demo is the fastest way to show what Orbit does. If a command reports that Orbit is not set up, follow its stated next step rather than guessing between these paths, except when the already-selected real-project branch is still authoring its first project-local config. ## Core loop For a setup or run request, first define the smallest representative evidence appropriate to the application: expected content for a web endpoint, observable output or a safe existing behavior for a worker or CLI, and an existing dependency-backed flow when one is part of the user's multi-service goal. A ready resource, open port, or HTTP 200 alone is not evidence. Do not invent a write solely to satisfy verification. 1. Run `orbit inspect --json` once to get readiness, environment/resource state, risks, and recommended actions. For a real project without `orbit.yaml`, first complete the project inspection and create the initial config described above, then run this step. 2. If blocked, follow the one applicable `recommended_actions` entry after checking its scope and `destructive` flag. Do not invent an intermediate diagnostic command. 3. Make the requested change with the narrowest lifecycle command. 4. Verify the intended resource selection is non-empty and ready with `orbit status --json`. 5. For setup or run onboarding, verify the applicable completion evidence below. When readiness or application evidence fails, use the structured status, recommended action, and narrowest relevant logs to fix one cause and retry. Continue while the next action is non-destructive and within the requested scope. Stop only for missing approval or credentials, an unavailable external prerequisite, a product decision, or a concrete required behavior Orbit cannot express. If the user names an instance, or the task runs beside another checkout or CI job, choose one instance name before the first inspect and pass `--instance ` to every targeted command. Never fall back to the default runtime midway through a workflow. JSON recommended actions already retain the active instance target. Use `--json` whenever the command supports it. Human output is not a stable parsing contract. `orbit up` starts the daemon when needed and safely applies pending config edits; do not manage the daemon preemptively. Orbit ships commands faster than this file can track it, so treat `orbit --help` as the current truth. Absence from `orbit --help` is not proof a command is unavailable: agent and advanced commands such as `inspect`, `history`, and `env apply` are intentionally hidden from contextual human help. Invoke them as documented. Read [references/workflows.md](references/workflows.md) for command selection and destructive-operation rules. Deeper references live in the repository's `docs/`: `agent-cli` (the `orbit.cli.v1` contract), `instances`, `configuration`, `troubleshooting`, `tracing`, `sql-workflow`, `architecture`. ## State changes - Use `orbit up --json` for the environment, or `orbit up --json` for one resource and its dependencies. - Use `orbit restart --json` and `orbit down --json` (or multiple resource names), `--group`, or `--infra` for targeted lifecycle changes; `up` and `down` use the same selection modes. - Use `orbit up --infra --json` only when the user explicitly wants containers without host services. - Use `orbit instance list --json` to discover named runtimes and their actual endpoints. Named-instance ports may differ from the declarations. - Use `orbit source sync [] --json` to refresh shared configuration and `orbit switch --json` to select it. With resources running, switch returns the stable `confirmation_required` error instead of acting; run the recommended `--yes` command only when the user intends to stop that stack. - Use `orbit env info --json` to learn how to reach the env's resources: ports and URLs carry `declared` vs `observed` provenance, and observed values are withheld when the daemon serves a different environment. Environment values need `--show-secrets`; key names are always listed. - After editing the active config, normal `orbit up --json` validates before interruption, restores resources that were running, then performs the requested startup selection. Use `orbit env apply --json` when the edit must apply without starting any resource that was already stopped. ## Diagnostics - Reuse the initial inspect snapshot; do not run inspect again inside the same recovery flow. - Use `orbit doctor --json` only when a recommended action asks for it or when runtime/setup checks need more detail. - Treat `dependency_readiness_ambiguous` as a configuration-authoring risk, not proof that startup failed. Tell the user which `health_check` path Orbit could not infer; do not invent a probe or edit project intent without scope. - When `config_invalid` includes a `did you mean` correction, preserve that exact field or value in the explanation. Apply it only when the task includes editing the environment; otherwise report the correction without mutating project intent. - Prefer `orbit logs --json` over reading process files directly; use `-f --json` only when an NDJSON stream is useful. - Use history and trace commands only when the task needs correlation or an audit trail; they are not startup prerequisites. - Treat the JSON envelope's final state and actions as authoritative rather than inferring success from exit code or transport state. ## Onboarding completion Before reporting a setup or run onboarding request as successful, require the evidence that applies to the user's project: - the intended Orbit resource selection is non-empty and ready; - a web endpoint returns the expected application content; - a worker or CLI produces its expected observable output or safe behavior; - an existing multi-service flow succeeds when it is part of the user's goal; - the inspected response, output, and relevant logs contain no framework or dependency error masked by successful transport state. Report the files changed, resource evidence, representative behavior evidence, any remaining limitation, and the one-line request the user can use next time. ## Safety - Ask before `orbit sqlserver reset` or `orbit sqlserver publish --allow-data-loss`; these may discard local data. - Treat `orbit switch` as destructive when resources are running: it stops them. Never pass `--yes` on the user's behalf without their intent. - Treat `orbit instance clean ` as destructive to that instance's local processes, state, containers, and volumes. Run it only when the user's task includes disposing of that instance. - Do not remove Docker volumes unless the user explicitly requests it. - Do not edit `~/.orbit/settings.json` directly; use `orbit settings`, `orbit init`, or `orbit source sync`. - Treat environment repositories as executable configuration. Inspect unfamiliar commands before starting them. - Do not expose logs, environment variables, repository paths, or tunnel traffic outside the user's stated scope.