Orbit — Autonomous Execution System for macOS
Orbit is a local-first, deterministic execution agent runtime for macOS. It translates natural-language intent into auditable, permission-gated tool execution — all without leaving your machine.
Intent → Plan → Permission → Execute → Observe → Adapt
⸻
Why Orbit
Existing agent frameworks often rely on remote services or cloud infrastructure. Orbit runs natively on macOS as a local background runtime — the agent executes on your machine, operates on your machine, and maintains full local control over state and execution.
- Local-first — execution, memory, and state remain on your machine
- Auditable — every action is logged and traceable through the event system
- Permission-gated — nothing executes without explicit or pre-approved consent
- Deterministic — execution follows a strict intent → plan → step pipeline
⸻
Features
- Background execution runtime — persistent agent process with job scheduling and crash recovery
- Menu bar controller — quick access to agent state, conversations, and execution history
- Tool execution system — 30+ built-in tools: files, shell, browser, Git, clipboard, screenshots, and more
- Agent orchestration — ReAct loop with planning, self-correction, and multi-step execution
- Workflow engine — template-driven workflows with variable substitution and DAG-based execution
- Plugin system — Swift-based plugins with sandboxed runtime, auto-restart, and timeout enforcement
- Memory system — hybrid semantic + FTS5 search, conversation summarization, user profile extraction
- Research & browser tools — web research, screenshot analysis, and screen understanding
- MCP server — Model Context Protocol socket for external AI tool integration
- Multi-agent teams — decomposition of goals across specialized sub-agents
- LLM provider fallback — chained providers with automatic failover
- Graceful degradation — resilience to provider failures, plugin crashes, and database issues
⸻
Requirements
- macOS 14 (Sonoma) or later
- Xcode 16+ or Swift 5.9+ toolchain
- An API key for at least one LLM provider (OpenAI, Anthropic, or local via Ollama/LM Studio)
⸻
Getting Started
swift build swift run Orbit
On first launch, Orbit creates an empty conversation. Type a message to begin.
Orbit depends only on GRDB.swift for SQLite persistence. All other functionality is built on system frameworks.
⸻
LLM Provider Configuration
export OPENAI_API_KEY="sk-..."
export ANTHROPIC_API_KEY="sk-ant-..."
API keys and model settings can also be managed through the settings panel (Cmd+,). Keys are stored in the system Keychain.
⸻
Architecture
┌─────────────────────────────────────────────────────┐ │ UI Layer │ │ SwiftUI (MenuBar, OverlayPanel, ConversationView) │ └──────────────────────┬──────────────────────────────┘ │ intent ▼ ┌─────────────────────────────────────────────────────┐ │ UXOrchestrator │ │ State machine: idle → interpreting → planning → │ │ executing → completed / failed / cancelled │ └──────────────────────┬──────────────────────────────┘ │ execution story ▼ ┌─────────────────────────────────────────────────────┐ │ ExecutionKernel │ │ Intent → Plan → PermissionGate → Tools │ │ ReAct loop, self-correction, retry logic │ └──────────────┬───────────────────┬──────────────────┘ │ │ ▼ ▼ ┌─────────────────────────┐ ┌─────────────────────────┐ │ PermissionGate │ │ Tool Registry │ │ Explicit approval for │ │ 30+ built-in tools │ │ sensitive operations │ │ Plugin-hosted tools │ └─────────────────────────┘ └─────────────────────────┘ │ ▼ ┌─────────────────────────────────────────────────────┐ │ OrbitBackgroundRuntime │ │ Persistent agent process, job scheduler, event bus │ │ Memory store, conversation management, workspace │ └─────────────────────────────────────────────────────┘
⸻
Key components
Component Responsibility UXOrchestrator UI state machine; manages execution lifecycle ExecutionKernel Intent-to-plan pipeline, ReAct execution loop PermissionGate Approves or blocks sensitive tool execution ToolRegistry Routes tool calls to implementations OrbitBackgroundRuntime Persistent process, scheduling, state management MemoryStore Hybrid semantic + FTS5 conversation memory
⸻
Safety Model
Safety is a core design constraint in Orbit. The system ensures that no action occurs without explicit control and visibility.
- Permission gate — every sensitive tool call requires explicit approval or allowlisting
- Tool sandboxing — system commands are validated against controlled execution rules
- Plugin sandbox — plugins run in isolated macOS sandbox environments
- No silent execution — actions cannot be executed without explicit intent flow
- Full audit trail — every execution step is recorded in the event system
- Keychain storage — API keys and OAuth tokens are stored in macOS Keychain
⸻
Testing
swift test
The test suite includes 208 tests covering core systems including:
- Agent orchestration
- Memory system
- Execution kernel
- Workflow engine
- Browser tools
- Plugin system
- Core services and utilities
Tests run automatically via GitHub Actions on pushes and pull requests targeting main and release branches.
⸻
Extensibility
Tool Protocol
Implement the Tool protocol to add new capabilities:
struct MyTool: Tool { var name: String { "my_tool" } var parameters: [ToolParameter] { ... } func execute(input: ToolInput, context: ExecutionContext) async throws -> ToolOutput { ... } }
Register it with:
ToolRegistry.register(MyTool())
⸻
Plugin Architecture
Plugins are standalone Swift packages loaded at runtime. They execute in sandboxed processes with:
- Restricted filesystem access
- Timeout enforcement
- Auto-restart on failure
- Controlled permission scopes
⸻
MCP Compatibility
Orbit exposes a Model Context Protocol server over a Unix socket, allowing external MCP-compatible clients to discover and invoke Orbit tools.
⸻
Project Structure
Sources/ Orbit/ Agent/ Core/ Design/ Discovery/ Execution/ Generation/ Integrations/ Jobs/ Kernel/ LLM/ Memory/ Models/ Monitoring/ OAuth/ Plugins/ Research/ Services/ Templates/ Tools/ UX/ Views/ Visual/ OrbitApp/ Tests/
⸻
Roadmap
- Multi-job scheduling and concurrent agent execution
- Long-running background agents with checkpoint-based recovery
- Distributed execution nodes with shared event log replication
- Improved crash recovery and execution resume system
⸻
License
Orbit is licensed under the GNU Affero General Public License v3.0 (AGPL-3.0).
This ensures Orbit remains open and transparent, even when used as part of networked or hosted systems.
You are free to use, modify, and distribute this software under the terms of the AGPL-3.0 license.
If you deploy Orbit (or a modified version) as a network-accessible service (API, agent runtime, or hosted system), you must also provide the corresponding source code, including any modifications.
Full license text: https://www.gnu.org/licenses/agpl-3.0.en.html