orb

Orb

A slim, pure-Go agent platform built by Ordalie as an SDK-first Go module and a single static CLI binary. It began as a port of Mario Zechner's MIT-licensed pi coding agent and keeps interop with released pi: wire protocols, compatibility formats and extension behavior follow the pi release pinned in UPSTREAM.lock, and every deliberate divergence is recorded in docs/DECISIONS.md. Native CLI state lives in SQLite, with Pi JSONL import/export and file-backed SDK defaults. The orb binary deliberately coexists with upstream's pi.

Install

curl -fsSL https://raw.githubusercontent.com/OrdalieTech/orb/main/scripts/install.sh | sh

This installs orb to ~/.local/bin after verifying the release checksum. Override the directory with ORB_INSTALL_DIR; alternatively, with Go ≥ 1.27.1:

go install github.com/OrdalieTech/orb/cmd/orb@latest

Update

Run orb update to install the latest verified release. Homebrew, Nix, and Snap installs stay package-manager-owned. Use --extensions, --models, or --all for the other update targets.

First session

export OPENAI_API_KEY=sk-...          # or ANTHROPIC_API_KEY, or run `orb login`
orb                                  # interactive TUI
orb -p "explain this repository"    # headless print mode

Sessions and global state live in ~/.orb/state/orb.db by default. On first launch, Orb migrates legacy state and preserves the original files; close older Orb and Bridge processes first. Use orb storage import <session.jsonl> and orb storage export <session-id> <output.jsonl> to exchange sessions with Pi. Native sessions have IDs rather than live JSONL paths. SDK defaults remain file-backed, and orb --pi-files ... provides explicit compatibility in a separate state root. See the storage guide and 0.8.0 upgrade notes.

orb --mode rpc retains the upstream RPC protocol; upstream's unmodified suite also passes through the explicit Pi-file entry point.

Connect devices with Bridge

Open Bridge from Settings or Ctrl+P, enable it, and choose Add device. Pair with an invitation or existing SSH access; SSH setup installs or updates remote Orb when needed, then conversation traffic uses Bridge over Tailcat. From the shell: orb bridge connect-ssh user@host. Pairing grants mutual conversation access. Bridge runs in the background until explicitly stopped; turning it off retains saved pairings. Recent foreign previews are read-only offline.

The current release controls attached conversations; a unified multi-Bridge Sessions page remains planned.

Deploy anywhere

Orb is a runtime you deploy, not a thin client of someone else's server: the same core runs on macOS and Linux, in containers, inside Go services and in a browser worker, and is being brought to Cloudflare Durable Objects, Celld cells, Windows, Android, iOS and WASI. Each deployment runs its own model calls, tools and sessions, and deployments reach each other as Bridge peers. docs/deployments.md lists every target with its status, capabilities, deploy command and Bridge role.

Embed the SDK

import "github.com/OrdalieTech/orb/agent"

result, err := agent.NewAgentSession(agent.AgentSessionOptions{})
if err != nil { log.Fatal(err) }
defer result.Session.Dispose()
result.Session.Prompt(context.Background(), "list the files here")

Thirteen runnable examples live in agent/examples, from a minimal session to custom tools, providers, and session runtimes — 01_minimal runs offline against the bundled faux provider.

Run an upstream extension

Orb executes many upstream TypeScript extensions unmodified through a local Node.js or Bun host. Fetch the pirate example from the pinned upstream revision and load it:

curl -fsSLO https://raw.githubusercontent.com/earendil-works/pi/a13d35a742c6ef8462812a28fbe1d8c8b7431c32/packages/coding-agent/examples/extensions/pirate.ts
orb --extension ./pirate.ts

Run /pirate in the TUI to exercise the extension.

In the last measured runs, 61 of upstream's 69 single-file examples ran as-is, 43 of the 44 most-downloaded Pi packages loaded, and of 30 popular packages installed by real Pi, Orb loaded 29 and 15 completed live tool or hook workflows. The harness and raw results are in conformance/extensions; the remaining runtime ceilings are listed in docs/DECISIONS.md. .orb/extensions/ in a trusted project and the global agent directory are discovered like upstream.

Plugins, permissions, and MCP

Orb's bundled plugins (tasks, websearch, subagents, permissions, memory) are off by default and configured through Settings or the CLI — including external CLIs as sub-agents, a fail-closed bash filesystem sandbox, and MCP servers. /plugins, /permissions, and /mcp open configuration windows in the TUI; orb plugins … and orb mcp … configure everything from the shell without a session. See docs/plugins.md for the full reference.

Provenance

Upstream pi is © Mario Zechner, MIT — Orb pins a released pi version in UPSTREAM.lock and regenerates its conformance goldens from that source (make fixtures-check). Orb is MIT too; see LICENSE, CONTRIBUTING.md, and SECURITY.md.

Every GitHub release includes a checksummed orb_<version>_source.tar.gz. To verify that source independently, download it with checksums.txt, run sha256sum -c checksums.txt, extract it, and run CGO_ENABLED=0 go build -buildvcs=false ./cmd/orb; release CI performs the same rebuild before publishing. The flag is required because a source archive intentionally contains no .git metadata.

Independent configuration

Orb uses ~/.orb/agent (ORB_AGENT_DIR) and project .orb; file-backed sessions can use ORB_SESSION_DIR. Runtime controls use ORB_* (ORB_OFFLINE, ORB_PACKAGE_DIR, ORB_SKIP_VERSION_CHECK, and TUI controls), not Pi’s environment. Native CLI state remains ~/.orb/state/orb.db, including existing conversations and credentials. Pi directories are not scanned, imported or rewritten automatically. --pi-files selects compatible file storage, not Pi’s default directory.

To reuse selected Pi resources, explicitly copy them into Orb’s directory or use an explicit resource path; leave the original files in place. Import selected JSONL sessions with orb storage import <path>, and native configuration with orb storage config import <document-name> <path>. Review copied settings for absolute Pi paths before enabling extensions. Do not copy Herdr’s managed Pi integration: Orb reports its own lifecycle and resume command, supported by Herdr 0.9.2 and later.