orbit

Agent Runtime for running Agent Images — load, execute, and manage AI agents from a local directory or git repository.

How It Works

Orbit follows a container-like model for AI agents. You package an agent as an image (a directory with a manifest, prompts, and workflows), then use Orbit to run it.

                ┌──────────────────────────────────────────┐
                │              orbit daemon                │
  orbitctl ────▶│                                          │
   or curl      │  Image ──▶ ReAct Loop ──▶ LLM (OpenAI)  │
                │              │     ▲                     │
                │        ┌─────▼─────┘                     │
                │        │  Tools  Memory                  │
                │        └────────────────                 │
                │  Scheduler ──▶ Cron triggers             │
                └──────────────────────────────────────────┘

1. Load — Orbit resolves an image reference (local path, name, or git URL) and reads the agent.toml manifest
2. Execute — A ReAct (Reason + Act) loop sends the agent's prompt to an OpenAI-compatible LLM, interprets tool calls, executes them, and feeds results back
3. Persist — Run state and logs are stored in SQLite; agent memory is available as a key-value store across runs
4. Schedule — Cron-based scheduler triggers agent runs on a recurring cadence

Agent Types

Orbit supports three agent types, set via type in the [agent] section of agent.toml:

Type	Description
interactive	One-shot run with timeout and step limits (default)
daemon	Long-running agent with no timeout/step limits and automatic restart on failure
cron	Scheduled agent triggered on a cron cadence

Agent Images

An agent image is a directory with an agent.toml manifest:

my-agent/
├── agent.toml           # Manifest (required)
├── prompts/
│   └── system.md        # System prompt
├── workflows/
│   └── main.json        # Workflow definition
├── schemas/
│   └── input.json       # Input validation (optional)
└── tools/
    └── manifest.json    # Custom tool definitions (optional)

Manifest (agent.toml)

Interactive agent (default)

api_version = "agent.image/v1"
kind = "AgentImage"

[metadata]
name = "my-agent"
version = "0.1.0"

[agent]
entrypoint = "workflows/main.json"
default_model = "gpt-4.1"
type = "interactive"

[capabilities]
tools = ["echo", "fetch_url", "web_search", "memory_put", "memory_get"]

[permissions]
network = true
filesystem = "read-only"
shell = false

[resources]
timeout_seconds = 180
memory = "512Mi"

[memory]
type = "kv"
persistence = "local"

Daemon (long-running) agent

api_version = "agent.image/v1"
kind = "AgentImage"

[metadata]
name = "my-daemon"
version = "0.1.0"

[agent]
entrypoint = "workflows/main.json"
default_model = "gpt-4.1"
type = "daemon"

[capabilities]
tools = ["fetch_url", "memory_put", "memory_get"]

[resources]
timeout_seconds = 0
max_steps = 0
restart_policy = "on_failure"
memory = "512Mi"

Set timeout_seconds = 0 and max_steps = 0 to remove all execution limits. The agent runs until it produces a final answer or is stopped manually.

restart_policy controls what happens when the agent exits:

Policy	Behavior
never	Do not restart (default)
on_failure	Restart only if the run failed
always	Restart after any exit (success or failure)

Restarts use exponential backoff (1s up to 60s).

Cron (scheduled) agent

api_version = "agent.image/v1"
kind = "AgentImage"

[metadata]
name = "my-cron-job"
version = "0.1.0"

[agent]
entrypoint = "workflows/main.json"
default_model = "gpt-4.1"
type = "cron"

[capabilities]
tools = ["web_search", "fetch_url"]

[resources]
timeout_seconds = 120
memory = "256Mi"

[schedule]
cron = "0 */6 * * *"
timezone = "Asia/Ho_Chi_Minh"
concurrency_policy = "forbid"

The [schedule] section configures cron behavior:

Field	Description
cron	Cron expression (e.g. "0 */6 * * *" = every 6 hours)
timezone	Optional IANA timezone (default: UTC)
concurrency_policy	forbid (skip if previous run is active), allow (run concurrently), replace (stop previous run first)

Manifest reference

Section	Purpose
metadata	Agent name and version
agent	Entrypoint workflow, default LLM model, agent type (interactive, daemon, cron)
capabilities	Which built-in tools the agent can use
permissions	Sandbox boundaries — network, filesystem, shell access
resources	Execution limits — timeout, step cap, restart policy
memory	Agent memory backend (key-value, local persistence)
schedule	Cron expression and concurrency policy (only for cron agents)

Image Resolution

When you pass an image_ref to the CLI or API, Orbit resolves it in order:

1. Git URL — cloned (shallow, --depth 1) to <images_dir>/.git-cache/ and updated on subsequent runs. Append @<rev> to pin a branch or tag.
   • github.com/org/repo
   • github.com/org/repo@v1.0
   • https://github.com/org/repo.git
   • git@github.com:org/repo.git@main
2. Absolute path — used as-is (/home/user/agents/my-agent)
3. Relative path — starts with ./ or ../, resolved from current directory
4. Name — looked up under images_dir (default ./data/images)

Built-in Tools

Tool	Description
echo	Returns the input as-is (useful for testing)
fetch_url	HTTP GET and return status + body
web_search	Web search via Brave Search API
memory_put	Store a key-value pair in agent memory
memory_get	Retrieve a value by key from agent memory

Agents declare which tools they use in capabilities.tools inside agent.toml. Only listed tools are available at runtime.

Install

cargo build --release

Binaries are written to target/release/:

• orbit — the daemon
• orbitctl — the control CLI

Quick Start

OPENAI_API_KEY=sk-... ./target/release/orbit serve

In another terminal:

# One-shot run
./target/release/orbitctl run my-agent --input '{"task": "Find top vector databases"}'

# Create a cron schedule
./target/release/orbitctl schedule my-cron-job --cron "0 */6 * * *" --input '{"task": "Daily digest"}'

# List schedules
./target/release/orbitctl schedules

# Manually trigger a schedule
./target/release/orbitctl trigger <schedule-id>

# Remove a schedule
./target/release/orbitctl unschedule <schedule-id>

License

Apache 2.0 — see LICENSE.