Orbit ​

Build the product. Let agents run the environment.

Orbit is an agent-native local development orchestrator. It gives developers and coding agents one reliable interface to set up, run, inspect, and manage a project's entire local stack.

Official website · Try the demo · Use Orbit with your project · Install · Documentation · 繁體中文

Local setup should not live in a developer's head. Orbit turns one orbit.yaml into an executable environment contract shared by developers, CI, and coding agents.

• Encode the environment once: dependencies, commands, ports, and readiness live in one versioned definition instead of setup notes and tribal knowledge.
• Delegate with confidence: the stable JSON CLI gives agents observable state, structured errors, and safe next actions instead of brittle shell automation.
• Keep humans focused: Orbit coordinates host processes and containers and surfaces health, logs, ports, traces, and failures in one place.

Try Orbit ​

The demo needs Git, Docker, Python 3, and an installed Orbit CLI. Start by cloning it:

git clone https://github.com/iml885203/orbit-demo.git
cd orbit-demo

1. Give your agent the Orbit skill ​

Claude Code can install the version-matched plugin directly:

claude plugin marketplace add iml885203/orbit
claude plugin install orbit-agent@orbit

For Codex or another coding agent, include the Orbit skill in the prompt below. Source releases also include plugins/orbit-agent as a local plugin for Codex and Claude Code.

2. Delegate the environment ​

Open the cloned directory in your coding agent and send:

Use Orbit to inspect the prerequisites and current state of this project. Follow only non-destructive recommended actions needed to start the demo, bring up the environment, verify that every resource is ready, and open demo-shop. Stop and explain before any destructive action or whenever setup requires my input. If the Orbit plugin is unavailable, read the Orbit skill first.

The agent uses Orbit's structured state and errors to inspect, act, and verify instead of guessing how the stack works.

Prefer the CLI? ​

Run the same journey yourself:

orbit up
orbit status
orbit open demo-shop

The Orbit demo is a tiny storefront: three host APIs, live stock in a Redis container, and orders in SQLite. Buy a mug to see one request cross the whole graph, then use orbit down to stop it.

One file describes the environment ​

Save an orbit.yaml beside your code (runnable example):

version: "3"

containers:
  redis:
    image: redis:7.4-alpine
    ports:
      redis: "26379:6379"

services:
  app:
    kind: frontend
    command: python3 -m http.server "$PORT"
    ports:
      http: 28080
    depends_on: [redis]

The daily loop is four commands:

orbit up       # start everything in dependency order
orbit status   # see what is actually ready
orbit logs app # inspect application output
orbit down     # stop the environment

Orbit starts Redis before the host process, waits for real readiness instead of equating "process exists" with "ready", and injects the declared port as PORT. The default runtime keeps ports fixed: a conflict is reported with its owning process and the remedy. After editing orbit.yaml, run orbit up again: the new config is validated before anything is interrupted.

For parallel local checkouts or CI jobs, select a named instance. Named instances isolate daemon state, Docker resources, volumes, networks, and host ports while leaving the unnamed runtime backward compatible:

orbit up --instance checkout-a
orbit status --instance checkout-a --json
orbit instance list --json
orbit instance clean checkout-a

Declared host ports are preferences inside a named instance. Orbit persists the resolved ports for stable restarts and reports the actual endpoints in up, status, and instance list; callers do not need to coordinate ORBIT_HOME, ORBIT_NAMESPACE, ORBIT_DASHBOARD_PORT, or ORBIT_SOCKET. See Isolated runtime instances for targeting, isolation, port resolution, and cleanup semantics.

Use Orbit with your project walks this path and shows how to promote the proven file into a shared team environment. Every field is documented in Configuration.

Install ​

macOS or Linux with Homebrew:

brew install iml885203/tap/orbit

Windows with Scoop (Beta):

scoop bucket add iml885203 https://github.com/iml885203/scoop-bucket
scoop install orbit

Or use the direct verified installer on macOS and Linux:

curl -fsSL https://raw.githubusercontent.com/iml885203/orbit/main/scripts/install.sh | bash
export PATH="$HOME/.local/bin:$PATH"

Windows PowerShell (Beta):

irm https://raw.githubusercontent.com/iml885203/orbit/main/scripts/install.ps1 | iex

This installs the latest published preview release. Orbit installs only its own CLI—never a project's runtimes or dependencies; orbit doctor reports what the selected environment expects and the specific remedy. Upgrade, rollback, uninstall, and platform details are in Installation and development.

Using Orbit with an AI agent ​

Agents read state through the same CLI with --json; errors carry stable codes and executable recommended actions:

orbit inspect --json       # one runtime-readiness decision and safe next actions
orbit status --json        # selected environment and current resource states
orbit doctor --json        # host prerequisites and setup diagnostics
orbit env info --json   # ports, URLs, and credentials-by-reference for anything living beside the stack

The version-matched plugin used in the demo journey teaches agents to inspect state first, prefer --json, and confirm destructive operations. Without the plugin, point an agent to the skill and JSON contract.

Dashboard ​

orbit open opens the local dashboard: the dependency graph with service controls, environment preview and switching, logs, health diagnostics, traces, and request playback. It binds to loopback only.

Documentation ​

Core user documentation:

• Use Orbit with your project
• Why Orbit — design trade-offs and tool comparisons
• Configuration
• Environment sources
• Isolated runtime instances
• Using Orbit under an E2E test suite
• Tracing
• Troubleshooting
• Versioning and compatibility

Optional workflows, inactive unless the environment enables them:

• SQL Server Database Projects
• Tunnel claims

For adopters and contributors:

• Team adoption
• Architecture
• Development
• Agent CLI contract
• Contributing
• Documentation website maintenance

License ​

MIT. The binary embeds third-party dependencies; their licenses and attributions are listed in NOTICE.