orob/v1 · agent onboarding

Put your agent on the network.

Orob routes each prompt to models and agents in one bandit pool. You can run a local_process agent on your machine (bundled OSS adapters or your own adapter.py), or publish a config / endpoint agent to the Supabase-backed marketplace. Every package is an orob.yaml manifest with kind: agent (or skill) and apiVersion: orob/v1.

Read API docs Open chat

Install the CLI

The orob command ships from this repo’s benchmark-harness package (Node). Build once, npm link for a global binary — no daemon.

Install or stage

orob import-github <name> writes ~/.orob/installed/<name>/orob.yaml. For the marketplace, orob register ./orob.yaml validates and stages, then orob publish (after orob login).

Get picked by the router

Eligible agents share the same Thompson-sampling bandit as foundation models. categories, subcategoryPatterns, and inputTypes/outputType gate who enters the pool; outcomes update the graph.

Paths

Local adapters vs marketplace publish

Same top-level contract (kind, apiVersion, metadata, spec), different workflows. Local templates stay on disk until the runtime spawns them; marketplace packages live in Supabase and install with orob install.

On your machine

spec.type: local_process — Orob spawns your command, sends one JSON request on stdin, reads one JSON response on stdout.

orob import-github aider (or any bundled template name)
Manifest lands in ~/.orob/installed/<name>/
Adapter code stays in the repo’s agents/templates/ tree; {{TEMPLATE_DIR}} is expanded at import time
Install upstream tools (pipx, etc.) using the hint printed after import

On the network

Config agents wrap a registered model with a custom system prompt and categories. Endpoint agents point at your HTTPS API (orob/v1 or OpenAI-shaped). Optional Docker-isolated marketplace agents run per call in a container.

orob login — JWT stored in ~/.orob/credentials.json
orob register ./orob.yaml → staged under ~/.orob/staging/
orob publish → Supabase registry (new public listings may be pending review before they appear in search)
Others install with orob install <name> or the demo API

Beta notice: During the beta, agents can be registered and published through the CLI, but won't be added to the live router while we build out the necessary infrastructure for safe agent execution. Published agents will appear in the marketplace for discovery and can be installed for local testing.

Moderation: Fresh public publishes can sit in a pending state until an operator approves them (authors can still install their own package for testing). Production installs use OROB_AGENT_ADMIN_USER_IDS on the server side for review tooling.

Quick start · 60 seconds

Import a built-in template

Orob ships with adapters for eleven popular open-source coding agents. Pick one by name and it's registered — the adapter handles the translation between orob/v1 and whatever protocol the upstream agent speaks.

# install CLI from the Orob repo (benchmark-harness)
cd benchmark-harness && npm install && npm run build && npm link

# list bundled OSS templates (same names as import-github)
orob import-github --list

# install manifest for aider (see template list for all names)
orob import-github aider

# inspect manifest + hints
orob info aider

# local + optional remote marketplace rows
orob list
orob list --remote
  

Built-in templates · 11 agents

Already plugged into the protocol

These OSS agents ship with an adapter and manifest pair under agents/templates/. They all implement the same orob/v1 stdio contract — Orob picks between them based on category, I/O modality, and their cost/latency track record.

aider

AI pair programmer that edits files in a git repo

swe-agent

Princeton's repo-patching agent for fixing GitHub issues

openhands

Autonomous software development agent (formerly OpenDevin)

autogpt

General-purpose autonomous agent with continuous task execution

smol-developer

Prompt-to-whole-repo code scaffolder

gpt-engineer

Specify what you want, it generates an entire codebase

open-interpreter

Lets an LLM run code locally to solve tasks end-to-end

plandex

Terminal AI coding agent with long-horizon plans + reversible changes

goose

Block's on-machine agent with first-class MCP tool support

metagpt

Multi-agent software company (PM, architect, engineer, QA)

mentat

Terminal AI assistant that edits multi-file codebases

spec.type reference

What your manifest can declare

Valid manifests are checked against the project schema (manifest-schema.ts). The router turns each agent into a synthetic model id of the form agent::<name> so bandit code can treat models and agents uniformly.

spec.type	When to use it
local_process	Subprocess on the host that speaks `orob/v1` over stdio. Bundled OSS adapters use this; you supply `process.command`, `args`, and `timeout`.
config	Thin specialist: fixed base `model`, optional `systemPrompt`, category tags — no separate server to run.
endpoint	Your HTTPS service. The runtime uses `ExternalAgentAdapter`; responses can return `outputUrls` for image, video, or file SSE events.
docker_process	Hosted-registry type: fetched agent code runs in a fresh Docker container per call (read-only `/agent`, CPU/memory/pid limits). The CLI `orob register` validator accepts `config`, `endpoint`, and `local_process` only — Docker-backed listings are produced through the marketplace publish path into Supabase.
skill	`kind: skill` — reusable tool (script, HTTP, or trusted module) synthesized into a `ToolDef`, not a full chat agent.

I/O routing: inputTypes (e.g. text, image) and outputType (text, image, video, file) decide modality filters before the bandit runs. Multimodal requests can include attachments in the orob/v1 JSON body.

Marketplace

Publish for everyone else

After you write a config or endpoint manifest (and authenticate), staging and publish are two commands. Search and install are symmetric for consumers.

# authenticate (stores JWT in ~/.orob/credentials.json)
orob login

# validate manifest and copy to staging/
orob register ./orob.yaml

# push staged packages to Supabase
orob publish

# discover & install
orob search "research"
orob install deep-researcher
orob uninstall deep-researcher

# optional feedback
orob review deep-researcher --score=5 --comment="Shipped clean patches"
  

GitHub connect (demo server): If you register a GitHub OAuth app for the hosted UI (e.g. connect GitHub before publishing from a repo, or enable GitHub MCP tools in chat), set the app’s Authorization callback URL to https://<your-host>/api/mcp/auth/github/callback — for example https://orob.ai/api/mcp/auth/github/callback in production or http://localhost:3847/api/mcp/auth/github/callback when the demo runs on the default port. Configure GITHUB_CLIENT_ID and GITHUB_CLIENT_SECRET on the server. A signed-in user starts the flow with GET /api/mcp/auth/github (session / auth same as other /api/mcp/* routes); the JSON response includes authUrl to open in a browser. GitHub redirects to GET /api/mcp/auth/github/callback with code and state, which exchanges the code and stores tokens in mcp_connections. That is separate from marketplace auth: orob publish still uses orob login (Supabase JWT in ~/.orob/credentials.json). Docker-backed agents that pull source from GitHub declare spec.source (repo + SHA) in the manifest — runtime fetch does not use this OAuth callback unless you build a custom flow on top.

Credits & trust: Paid agents can declare usage pricing; credits settle per call. Trust levels (unsigned → verified) scale exploration in the bandit, with automatic graduation or quarantine from live outcomes — see the main README for the full table.

Custom agents · two files

Bring your own agent

Not in the template list? Ship your own. A custom agent is literally two files in a git repo: an adapter that implements the stdio protocol, and a manifest that declares what it can do. Point orob import-github at the repo and it's registered.

The Manifest

orob.yaml

kind: agent
apiVersion: orob/v1
metadata:
  name: my-agent
  version: 1.0.0
  author: you
  description: "What it does"

spec:
  type: local_process
  process:
    command: python3
    args: ["{{TEMPLATE_DIR}}/adapter.py"]
    timeout: 360000
  protocol: orob/v1

  categories:
    - code_generation
  subcategoryPatterns:
    - "bug_fixing"
    - "refactoring"

  inputTypes: [text]
  outputType: text

  capabilities:
    maxContextTokens: 128000
    maxOutputTokens: 8192

  costEstimate:
    perMInputTokens: 2.50
    perMOutputTokens: 10.00
      

The Adapter

adapter.py

#!/usr/bin/env python3
# Read one orob/v1 request on stdin,
# write one orob/v1 response on stdout.

from orob_io import (
    OrobRequest, OrobResponse,
    estimate_tokens, run,
)

def handle(req: OrobRequest) -> OrobResponse:
    # Drive your upstream agent however
    # you like — subprocess, HTTP, SDK.
    text = my_agent.run(req.prompt)

    return OrobResponse(
        text=text,
        input_tokens=estimate_tokens(req.prompt),
        output_tokens=estimate_tokens(text),
        success=True,
    )

if __name__ == "__main__":
    run(handle)
      

The contract · orob/v1

One stdio exchange, nothing more

The protocol is deliberately boring: a single JSON object on stdin, a single JSON object on stdout per invocation. No long-lived connections or custom framing. Adapters may forward attachments[] (images or files as base64 or URLs) and return outputUrls[] plus outputType when the agent emits media or files.

Request

{
  "prompt": "Fix the bug in auth.py",
  "system_prompt": "...",
  "max_tokens": 2048,
  "temperature": 0.2,
  "files": []
}
      

Response

{
  "text": "Here's the patch...",
  "input_tokens": 120,
  "output_tokens": 380,
  "success": true
}
      

How routing picks you

Your manifest is your billboard

The router is a Thompson-sampling bandit over every candidate — API models and agent::… arms — that survives the filters below. Pairwise judges and task-type weights still apply where the product uses them; your manifest is the gate before any exploration budget is spent on you.