Related projects: Orbit App · Orbit Nest.

Orbit is a TypeScript agent framework for building agent applications. It provides model and tool execution, persistent conversations, and Run lifecycle management for desktop agents, messaging agents, and automated workflows. The included orbit CLI and local web GUI use the same reusable framework.

Orbit means “orbit.” Just as a satellite fulfills its role along an orbit, agents move work forward in line with people's goals. The name expresses the idea of creating that path. See the logo and name for the selected artwork and the original Japanese wording.

0.8 is an evolving application-development release. Orbit supplies the runtime; your application supplies channel integrations, scheduling, memory policy, authentication and notification delivery. See capabilities and boundaries.

Install

Requires Node.js 20.19 or newer and npm. The library uses native ESM and runs in a trusted Node.js process, not a browser renderer.

Version 0.8.1 is available from npm and the v0.8.1 source tag. To use the source checkout, follow Development.

As an application dependency:

npm install --save-exact @cybergarage/orbit@0.8.1

Or as a command-line application:

npm install --global @cybergarage/orbit@0.8.1
orbit --help

Build your first agent

Start with the persistent agent example. It runs against the npm package, includes an API-key-free demo, and demonstrates:

• creating, saving and resuming conversations;
• starting a Run and waiting for its actual result;
• presenting operation previews and replying to approvals;
• requesting cancellation and closing owned resources;
• switching from a deterministic demo adapter to a real model.

For an existing application, use OrbitApplicationService as the main integration boundary and import it from @cybergarage/orbit. Follow the example's setup and lifetime handling: persistent storage must be initialized, Run admission is not completion, and the host must handle approvals and close its resources after execution settles.

Use the application guide for conversation routing, request deduplication, reconnects, background triggers and extension points. Use GUI Integration for the service and event APIs.

Try the CLI and local GUI

Configure a tool-capable model through workspace settings, or select your provider/model explicitly. For example, set OPENAI_API_KEY through your environment, then replace YOUR_MODEL with an available model:

orbit exec --provider openai --model YOUR_MODEL --openai-api-key-env OPENAI_API_KEY "Describe this workspace"

exec uses an ephemeral Session. Persistent interactive and GUI sessions first need storage initialization. On a fresh installation, with all Orbit writers stopped, restarters disabled and exclusive control of the storage:

orbit storage initialize --writers-stopped --restarters-disabled --exclusive-storage-control
orbit gui --provider openai --model YOUR_MODEL --openai-api-key-env OPENAI_API_KEY

Open the exact loopback URL printed by orbit gui; it includes a startup token. For existing or interrupted storage, follow Session Storage instead of assuming a new installation. Writes, commands and MCP operations normally require approval. Noninteractive exec cannot answer those prompts. See Managed Execution before changing execution policy.

Documentation

I want to…	Start here
Build an application from scratch	Agent application guide and runnable example
Use the CLI	CLI Reference
Integrate a desktop/web frontend	GUI Integration
Configure models, tools and MCP	Settings and Tools
Understand approval, budgets and failures	Managed Execution
Operate persistent data	Sessions, Storage and Logs
Add explicit Skills or context budgets	Skills and Compaction
Understand versions and planned milestones	Versioning
Contribute or publish a release	Development
Evaluate local coding with Ollama and Docker	Coding E2E evaluation and results
Explore implementation and design evidence	Documentation map and Architecture

Licensed under Apache-2.0.