# orchagent

> AI agent deployment platform. Build agents, deploy to secure cloud sandboxes, run via CLI, API, or web UI. BYOK model - you bring your own LLM keys. Desktop command centre (orch-hq) with terminal, canvas, messages, and tasks.

## Overview

orchagent is a deployment platform where developers build, deploy, and run AI agents for their teams. Deploy your AI agent. Your team can use it.

**Key features:**
- Build agents in Python/JS or plain English (prompt-based)
- Deploy to secure E2B cloud sandboxes
- Run via CLI, HTTP API, or web UI
- orch-hq desktop app: visual command centre with terminal, agent canvas, messages, and tasks
- Agent messages: agents send briefings, alerts, and notifications to orch-hq
- Agent tasks: agents create tasks with due dates, priorities, and project tags
- Integrations: connect Sentry, Slack, and more — agents use the credentials
- Team workspaces with access control
- Run history, scheduling, and managed secrets
- Always-on services for long-running agents (Discord bots, workers)
- Free tier: 1000 calls/day
- BYOK: Bring your own LLM API keys
- Credit-based billing for platform usage

## Object Types

orchagent has four canonical types:

- **Prompt** (`type: "prompt"`) — Prompt template + schema → single LLM call (execution engine: `direct_llm`)
- **Tool** (`type: "tool"`) — Python or JavaScript code runs in a sandbox (execution engine: `code_runtime`)
- **Agent** (`type: "agent"`) — LLM tool-use loop with custom tools in a sandbox (execution engine: `managed_loop`, Anthropic only)
- **Skill** (`type: "skill"`) — Passive knowledge (markdown) that enhances other types. Not runnable.

Additional fields for executable types (prompt, tool, agent):
- `run_mode`: `on_demand` (default) or `always_on` (for services)
- `callable`: `true` (default) — other agents can call this agent as a dependency. Set `false` to opt out.

Legacy type values `code` and `agentic` are accepted as aliases for `tool` and `agent` respectively.

## orch-hq Desktop App

Mac desktop app — visual AI command centre. Terminal + Canvas tabs, Messages/Tasks/Activity right panels.

- **Terminal**: Built-in CLI (Claude Code). Primary interface — tell Claude what to build.
- **Canvas**: Visual map of deployed agents with dependency lines and workspace boundaries.
- **Messages panel**: Agents send messages via `message.send()` — briefings, alerts, notifications.
- **Tasks panel**: Agents create tasks via `task.create()` — grouped by urgency, checkbox to complete.
- **Activity feed**: Every agent run logged automatically — status, duration, cost, output.
- **Integrations**: Connect third-party services (Sentry live, Slack/Linear/GitHub planned).

## SDK Modules

The orchagent-sdk (`pip install orchagent-sdk` / `npm install orchagent-sdk`) provides:

- **AgentClient**: Call other agents from within your agent (orchestration)
- **storage**: Persistent shared state between agents (key-value)
- **message**: Send messages to orch-hq (`message.send(title, body, level=...)`)
- **task**: Create and manage tasks (`task.create()`, `task.list()`, `task.update()`, `task.complete()`)

## Docs

- [What is orchagent?](https://docs.orchagent.io): Platform overview
- [Quickstart](https://docs.orchagent.io/quickstart): Deploy your first agent in minutes
- [orch-hq Desktop App](https://docs.orchagent.io/orch-hq): Visual command centre with terminal, canvas, messages, and tasks
- [API Reference](https://docs.orchagent.io/using-agents/api-reference): Authentication, endpoints, errors
- [CLI Commands](https://docs.orchagent.io/using-agents/cli-commands): orch login, run, publish
- [Code Snippets](https://docs.orchagent.io/using-agents/code-snippets): curl, Python, JavaScript, TypeScript examples
- [Agent Messages](https://docs.orchagent.io/using-agents/messages): Send messages from agents to orch-hq
- [Agent Tasks](https://docs.orchagent.io/using-agents/tasks): Create and manage tasks from agents
- [Integrations](https://docs.orchagent.io/using-agents/integrations): Connect third-party services (Sentry, Slack, etc.)
- [Agent Types](https://docs.orchagent.io/building-agents/agent-types): The four types (prompt, tool, agent, skill) and execution engines
- [Manifest Format](https://docs.orchagent.io/building-agents/manifest-format): orchagent.json schema
- [Publishing](https://docs.orchagent.io/building-agents/publishing): Deploy your agent
- [Orchestration](https://docs.orchagent.io/building-agents/orchestration): Agent-to-agent calls
- [SDK Reference](https://docs.orchagent.io/building-agents/sdk): AgentClient, storage, message, and task modules
- [Guide: Multi-Agent Orchestration](https://docs.orchagent.io/guides/orchestration-walkthrough): Build a multi-agent pipeline
- [Guide: CI/CD Integration](https://docs.orchagent.io/guides/cicd): GitHub Actions workflow for agent deployment
- [Security](https://docs.orchagent.io/concepts/security): Sandbox isolation, network controls, secret management
- [BYOK](https://docs.orchagent.io/concepts/byok): Bring Your Own Key model
- [Scheduling](https://docs.orchagent.io/using-agents/scheduling): Cron schedules and webhooks
- [Services](https://docs.orchagent.io/using-agents/services): Always-on service deployment
- [Local vs Server](https://docs.orchagent.io/concepts/local-vs-server): orch run (cloud vs --local)
- [Rate Limits](https://docs.orchagent.io/concepts/rate-limits): Platform limits
- [Billing & Credits](https://docs.orchagent.io/concepts/billing): Platform credits and usage
- [Troubleshooting](https://docs.orchagent.io/troubleshooting): Common errors and solutions (auth, running, publishing, workspaces, services, LLM providers)

## API

- Base URL: https://api.orchagent.io
- Auth: Bearer token (API key from dashboard)
- OpenAPI spec: https://docs.orchagent.io/api-reference/openapi.json

## Quick Start

### Deploy an agent
```bash
npm install -g @orchagent/cli
orch login
orch init my-agent
cd my-agent
# Edit prompt.md and schema.json
orch publish
```

### Run an agent (cloud execution, default)
```bash
orch run yourorg/my-agent --data '{"text": "Your text here"}'
```

### Pull a published agent into a local project
```bash
orch pull acme/my-agent@v2 --output ./my-agent
```

### Fork a public agent into your workspace
```bash
orch fork orchagent/security-agent --workspace acme-corp
```

### Run locally (no account needed, --local flag)
```bash
npx @orchagent/cli run orchagent/summarizer --input '{"text": "Your text here"}'
```

### Send a message from an agent
```python
from orchagent import message
message.send("Daily Brief", "Here's what happened today...", level="info")
```

### Create a task from an agent
```python
from orchagent import task
task.create("Fix login bug", due_date="2026-03-20", project="StockSure", priority="high")
```

### API call
```bash
curl -X POST https://api.orchagent.io/acme/summarizer/v1/analyze \
  -H "Authorization: Bearer $ORCHAGENT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"text": "Your text here"}'
```

## Core Concepts

| Term | Definition |
|------|------------|
| Prompt | Prompt template + schema → single LLM call (`type: "prompt"`, engine: `direct_llm`) |
| Tool | Your Python/JS code runs in a sandbox (`type: "tool"`, engine: `code_runtime`) |
| Agent | LLM tool-use loop with custom tools in sandbox (`type: "agent"`, engine: `managed_loop`) |
| Skill | Passive knowledge (markdown) that enhances other types (`type: "skill"`) |
| run_mode | `on_demand` (default) or `always_on` (for persistent services) |
| callable | Whether other agents can call this agent as a dependency (default: `true`) |
| Orchestrator | An agent that calls other agents |
| Workspace | Team-scoped container for agents, members, and settings |
| BYOK | Bring Your Own Key - users provide their own LLM API keys |
| Version | Each publish creates a new version (v1, v2, v3...) |
| Schedule | Cron or webhook trigger that runs an agent automatically |
| Service | Always-on deployment of an agent (Discord bot, worker, listener) |
| Credits | Prepaid balance for platform usage |
| orch-hq | Mac desktop app — visual AI command centre |
| Message | Agent-to-user notification via `message.send()` |
| Task | Stateful work item created by agents via `task.create()` |
| Integration | Third-party service connection (credentials for agents) |

## Links

- Website: https://orchagent.io
- Dashboard: https://orchagent.io/dashboard
- API: https://api.orchagent.io
- Docs: https://docs.orchagent.io