Build with Opsora

Opsora is a multi-provider AI agent with a routing engine, MCP fleet, plugin system, and autonomous orchestration. This guide walks you through installation, configuration, and the HTTP API.

Quick start

Install the CLI, set one provider key, and route your first task in under a minute:

$ pip install opsora-cli
$ export NVIDIA_API_KEY=nvapi-...
$ opsora "explain this Python function"  

The router classifies the intent (analysis), picks a reasoning model from your available providers, streams a response, and logs the cost.

Install

From PyPI

pip install opsora-cli
opsora --version

From source

git clone https://github.com/opsora/opsora-cli.git
cd opsora-cli && pip install -e ".[dev]"

Providers

Opsora speaks OpenAI-compatible, AWS Converse, and Kimi protocols. Bring any combination of keys:

Set the priority order so the router knows which provider to try first:

export OPSORA_PROVIDER_ORDER=nvidia,tokenhub,deepseek,moonshot,meta

MCP servers

Edit ~/.opsora/mcp.json to wire external tools via the Model Context Protocol:

{
  "mcpServers": {
    "github":   {"command": "npx", "args": ["-y","@modelcontextprotocol/server-github"], "env": {"GITHUB_PERSONAL_ACCESS_TOKEN": "${GITHUB_MCP_TOKEN}"}},
    "supabase": {"command": "npx", "args": ["-y","@supabase/mcp-server"], "env": {"SUPABASE_ACCESS_TOKEN": "${SUPABASE_MCP_TOKEN}"}},
    "gmail":    {"command": "npx", "args": ["-y","@gmail-mcp/server"], "env": {"GMAIL_OAUTH_TOKEN": "${GMAIL_MCP_TOKEN}"}},
    "filesystem":{"command": "npx", "args": ["-y","@modelcontextprotocol/server-filesystem","/root"]},
    "sqlite":   {"command": "npx", "args": ["-y","@modelcontextprotocol/server-sqlite","/root/.opsora/memory.db"]}
  }
}

Connect them at runtime with /mcp-connect or let Opsora auto-connect on startup.

Environment

Secrets live in ~/.opsora_env (gitignored). Opsora loads this file before initializing providers and MCP servers.

POST /chat

POST /api/chat — proxy a prompt through the router.

curl -X POST https://opsora-agent.pages.dev/api/chat \
  -H "Content-Type: application/json" \
  -d '{"prompt":"refactor auth.py to use JWT","prefer_cost":true}'

Returns the chosen provider/model and the assistant reply.

GET /status

GET /api/status — live health of every provider and MCP server.

{
  "providers": {"nvidia": "ok", "tokenhub": "ok", "deepseek": "ok"},
  "mcp": {"github": "connected", "filesystem": "connected"}
}

GET /cost

GET /api/cost — aggregated spend, grouped by model.

POST /agent

POST /api/agent — kick off the autonomous agent on a multi-step task. Streams progress events.

Autonomous agent

Planner → reasoning model. Explorer → fast secondary model. Verifier → reasoning model. The agent decomposes your request into 2–8 subtasks, executes each in a ReAct loop, and verifies completion before reporting.

Sub-agent orchestrator

Spawn parallel sub-agents for research, file analysis, or boilerplate generation. Up to 3 concurrent by default; configurable via max_parallel.

Plugins

Drop a Python file in ~/.opsora/plugins/ that subclasses OpsoraPlugin. Opsora auto-discovers it at startup.

Skills

Skills are higher-level workflows (problem solver, code reviewer, deployer) that the agent can invoke. Register a skill by adding it to the skill registry and pointing at its description.

Deploy

The Opsora website (this site) is hosted on Cloudflare Pages with a Workers + D1 backend. To deploy your own instance:

Troubleshooting