OrbyNode

[](https://orbynode.docs.potenfyr.in) [](https://orbynode.docs.potenfyr.in) [](https://github.com/PotenFYR-Studios/OrbyNode/actions/workflows/ci.yml) [](LICENSE) [](https://potenfyr.in) [](https://discord.com/invite/zUaN2FPBec) [](https://github.com/PotenFYR-Studios/OrbyNode) [Docs](https://orbynode.docs.potenfyr.in) · [Getting started](/docs/getting-started.html) · [Architecture](/ARCHITECTURE.html) · [API](/docs/rest-api.html) · [Contributing](/CONTRIBUTING.md) · [Security](/SECURITY.html)

---

🚀 What is OrbyNode?

OrbyNode is the self-hosted control plane for coding agents. It runs persistent terminal agents, owns their PTYs, files, tasks, Git workflows, services and machine state in one daemon, and reconnects your browser without interrupting the work.

The browser and desktop shell are replaceable clients. The daemon is the runtime. Closing a client never kills an agent.

✨ Highlights

Capability	Why it matters
Persistent PTY runtime	Real terminals survive disconnects, UI restarts and network changes.
Realtime control plane	One authenticated multiplexed WebSocket with snapshots, replay and bounded queues.
Agent awareness	Detect Claude, Codex, Gemini, OpenCode and Hermes state, approvals and failures.
Files and Git	Inspect, edit and review changes without leaving the control plane.
Tasks and worktrees	Isolate agents per task and keep merge flows under review.
Services and previews	Discover local ports and proxy development previews safely.
Multi-user RBAC	Owner, admin, operator, developer and viewer roles with project membership.
Remote nodes	Pair machines with expiring secrets and aggregate agents across hosts.
Observability	Host, session, token/context and workflow signals with an Attention Center.
APIs and workflows	Versioned /api/v1, MCP-style tools, webhooks and configuration-driven orchestration.

⚡ Quick start

Requirements: Rust 1.85+, Bun 1.1+, Node 20+ for CI compatibility.

git clone https://github.com/PotenFYR-Studios/OrbyNode.git
cd OrbyNode
(cd web && bun install && bun run build)
cargo run --release -p orbynode-daemon

Open http://127.0.0.1:7676, complete first-run setup, and create the first Owner.

The daemon binds 127.0.0.1 by default. Non-loopback binding is opt-in and must be paired with authentication and HTTPS or a trusted overlay.

🧠 How it works

Browser / PWA / Tauri shell
          |
   HTTP(S) + WebSocket
          v
    OrbyNode daemon
    /      |      \
  PTYs   SQLite   Realtime bus
   |       |        |
 Agents  durable  snapshots,
 tasks   state    replay, events

1. The daemon creates and owns terminal PTYs.
2. Output is captured once and fanned out through bounded realtime channels.
3. REST handles commands; WebSocket state uses snapshots and event replay.
4. Projects, sessions, terminals, tasks, settings and audit data live in SQLite.
5. Clients reconnect, resume from a sequence, and resynchronize when replay is unavailable.

🧱 Architecture

Crate	Role
orbynode-core	Small shared configuration and path types.
orbynode-terminal	Real PTY lifecycle and bounded output fan-out.
orbynode-realtime	Event bus, sequences, replay, subscriptions and backpressure.
orbynode-database	SQLite with WAL, migrations and durable repositories.
orbynode-auth	Argon2id, sessions, throttling and RBAC primitives.
orbynode-agents	Agent detection and Attention Center.
orbynode-files	Root-contained files, Git and worktrees.
orbynode-services	Port discovery, service metadata and process snapshots.
orbynode-nodes	Remote-node identity, pairing, heartbeat and revocation.
orbynode-notifications	Browser events and generic webhooks.
orbynode-workflows	Configuration-driven pipeline execution.
orbynode-api	Axum routes, auth middleware, gateway and embedded UI.

The web client uses Vite + React + TypeScript + Bun + Magic UI. Next.js and other meta-frameworks are not used.

🛠️ Development

(cd web && bun install) # install frontend dependencies
cargo build             # build backend
scripts/check.sh        # run every required gate

Run the daemon with live frontend assets:

(cd web && bun run build)
ORBYNODE_STATIC_DIR=web/dist cargo run -p orbynode-daemon

📦 Releases

Automated release builds target Linux x86_64 and ARM64, macOS Intel and Apple Silicon, and Windows x86_64 and ARM64. Artifacts include locked daemon builds, SHA-256 checksums, SBOM inventory and Cosign signatures.

Local release subset:

scripts/release.sh <rust-target-triple>

See docs/v1-readiness.md for remaining clean-machine installer and upgrade gates.

📚 Documentation

• Getting started
• Architecture
• Operations
• Website
• REST API
• Realtime protocol
• Agents
• Workflows
• Remote nodes
• Notifications
• Security model
• Frontend
• Development
• Testing
• Contributing
• Troubleshooting
• Performance
• Release readiness
• Changelog
• ADRs

💬 Support

• Bugs, ideas and questions: GitHub Issues
• Documentation: https://orbynode.docs.potenfyr.in
• Community: Discord

🤝 Contributing

Contributions are welcome. Keep changes milestone-scoped, add ADRs for substantial architecture, and run the full check suite before opening a pull request.

🔐 Security

Terminal access is remote-code-execution capability. Do not open public issues for exploitable flaws; follow the confidential process in SECURITY.md.

📜 License

OrbyNode is distributed under Apache-2.0 with the Commons Clause. You may use, modify and build around it, but you may not sell the software itself as a paid product. See LICENSE.

This site is open source. Improve this page.