# orchagent

> orchagent is a deployment platform for AI agents. Deploy your agent code (Python or TypeScript), get cloud execution, scheduling, secrets, run history, cost tracking, and team workspaces out of the box. `orch publish` and it runs in the cloud — no servers, no DevOps.

## What orchagent Is

A managed cloud infrastructure platform purpose-built for AI agents. Think Railway or Render, but specifically for AI agent workloads with built-in LLM cost tracking, multi-agent orchestration, and sandboxed execution.

orchagent is NOT a marketplace. All agents are private by default. The platform focuses on deployment, execution, and operations.

## Who It's For

- **Developer teams** running automated agents (scheduled tasks, data pipelines, Discord bots)
- **AI builders** who use AI coding tools and want a CLI-first deploy workflow
- **Consultants/agencies** deploying agents for multiple clients via team workspaces
- **SaaS builders** embedding agent execution as a product feature via API

## Agent Types

orchagent supports four agent types, each with a different execution model:

| Type | What it does | Execution engine | Author writes code? |
|------|-------------|-----------------|-------------------|
| `prompt` | Single LLM call with your prompt template + schema | `direct_llm` | No |
| `tool` | Runs your code in a sandbox (reads JSON stdin, writes JSON stdout) | `code_runtime` | Yes |
| `agent` | LLM + tool-use loop managed by the platform, or your own code | `managed_loop` or `code_runtime` | Optional |
| `skill` | Knowledge module (SKILL.md) for AI coding assistants — not executable | None | N/A |

**Execution engine inference:** Set `runtime.command` in orchagent.json → `code_runtime`. Set `loop` → `managed_loop`. Neither → falls back to type default.

**Run modes:** `on_demand` (default, triggered per-request) or `always_on` (24/7 persistent process — Discord bots, listeners, pollers). Always-on requires `code_runtime`.

**Multi-provider support:** Managed loop agents support Anthropic (Claude), OpenAI, and Google Gemini. Specify via `supported_providers` in orchagent.json. Default is Anthropic when unspecified.

## Getting Started

Install the CLI:

```bash
npm install -g @orchagent/cli
```

Create and deploy an agent:

```bash
orch login
orch init my-agent
cd my-agent
# Edit orchagent.json, prompt.md, schema.json
orch publish
orch run my-org/my-agent
```

- [Dashboard](https://orchagent.io/dashboard): Web UI for managing agents, viewing runs, and monitoring costs
- [Plans](https://orchagent.io/plans): Free tier available, Pro at $29/mo, Team at $99/mo

## Agent Configuration (orchagent.json)

The manifest file defines agent identity, runtime, and orchestration:

```json
{
  "name": "my-agent",
  "type": "agent",
  "description": "What this agent does",
  "supported_providers": ["anthropic", "openai"],
  "loop": { "max_turns": 25, "tools": ["web-search"] },
  "required_secrets": ["MY_API_KEY"],
  "default_skills": ["orchagent-public/orchagent-guide"]
}
```

**Required files for publishing:**
- `orchagent.json` — Agent manifest (required for all types)
- `prompt.md` — The prompt (required for prompt and agent types; the `"prompt"` field in orchagent.json is ignored)
- `schema.json` — Input/output schemas (optional; inline schema fields in orchagent.json are ignored)
- `Dockerfile` — Custom dependencies (optional, for tool/agent types)
- `SKILL.md` — Skill content with YAML frontmatter (for skill type only)

**Key manifest fields:** `type`, `run_mode`, `runtime.command`, `loop`, `supported_providers`, `default_models`, `timeout_seconds`, `required_secrets`, `callable`, `environment`, `bundle`, `manifest` (orchestration dependencies).

## CLI Commands

| Command | Description |
|---------|-------------|
| `orch login` | Authenticate via browser or API key |
| `orch init [name]` | Scaffold a new agent project (supports `--type`, `--template`, `--loop`, `--language`) |
| `orch publish` | Publish agent to the cloud (immutable versioning: v1, v2, v3...) |
| `orch run [org/agent]` | Execute agent in the cloud (or `--local` for local execution) |
| `orch agents` | List your agents (use `--all-versions` for version history) |
| `orch info [org/agent]` | Show agent details, version, and configuration |
| `orch logs` | View recent run history and execution logs (defaults to personal workspace if multiple exist; use `--workspace <slug>` for team workspaces) |
| `orch trace [run-id]` | View execution trace timeline (LLM calls, tool calls, decisions) |
| `orch dag [run-id]` | Visualize orchestration call graph |
| `orch replay [run-id]` | Re-execute a previous run with original snapshot |
| `orch test` | Run agent test fixtures from `tests/` directory |
| `orch dev` | Local development server with hot-reload (port 4900) |
| `orch schedule` | Manage cron and webhook schedules |
| `orch service` | Manage always-on services (deploy, logs, restart, delete) |
| `orch install [agent]` | Install agent as a sub-agent for Claude Code or Cursor |
| `orch skill install [skill]` | Install a skill to local AI tool directories |
| `orch pull [agent]` | Download agent source files locally |
| `orch fork [org/agent]` | Fork an agent into your workspace |
| `orch delete [agent]` | Delete an agent |
| `orch doctor` | Diagnose CLI and environment setup issues |
| `orch billing` | Open billing portal |

Templates available via `orch init --template`: `fan-out`, `pipeline`, `map-reduce`, `support-agent`, `discord`, `discord-js`, `github-weekly-summary`.

## API Reference

All API requests require authentication via `Authorization: Bearer {api_key}` header.

### Execution

| Method | Endpoint | Description |
|--------|----------|-------------|
| POST | `/{org}/{agent}/v{version}/run` | Execute an agent |
| POST | `/{org}/{agent}/v{version}/{endpoint}` | Execute agent with custom endpoint path |

### Agent Management

| Method | Endpoint | Description |
|--------|----------|-------------|
| GET | `/agents` | List agents in your org |
| POST | `/agents` | Create an agent |
| POST | `/agents/{id}/versions` | Publish a new version |
| GET | `/agents/{org}/{name}/{version}/tree` | View full dependency tree |
| GET | `/public/agents/{org}/{agent}/{version}` | Public agent metadata (no auth required) |

### Runs & Observability

| Method | Endpoint | Description |
|--------|----------|-------------|
| GET | `/workspaces/{id}/runs` | List runs (filterable by status, agent, date) |
| GET | `/workspaces/{id}/runs/{run_id}` | Run details with structured input/output |
| GET | `/workspaces/{id}/runs/{run_id}/trace` | Execution trace timeline |
| GET | `/workspaces/{id}/runs/{run_id}/logs` | Execution logs |

### Scheduling

| Method | Endpoint | Description |
|--------|----------|-------------|
| POST | `/workspaces/{id}/schedules` | Create a cron or webhook schedule |
| PATCH | `/workspaces/{id}/schedules/{sid}` | Update schedule |
| DELETE | `/workspaces/{id}/schedules/{sid}` | Delete schedule |
| POST | `/workspaces/{id}/schedules/{sid}/trigger` | Manually trigger a schedule |

### Always-On Services

| Method | Endpoint | Description |
|--------|----------|-------------|
| POST | `/workspaces/{id}/services` | Deploy an always-on service |
| GET | `/workspaces/{id}/services` | List services |
| POST | `/workspaces/{id}/services/{sid}/restart` | Restart a service |
| DELETE | `/workspaces/{id}/services/{sid}` | Delete a service |

### Secrets Vault

| Method | Endpoint | Description |
|--------|----------|-------------|
| GET | `/workspaces/{id}/secrets` | List secret names (values never exposed) |
| POST | `/workspaces/{id}/secrets` | Create or update a secret |
| DELETE | `/workspaces/{id}/secrets/{name}` | Delete a secret |

### Usage & Costs

| Method | Endpoint | Description |
|--------|----------|-------------|
| GET | `/usage` | Usage summary for current period |
| GET | `/usage/timeseries` | Usage over time |
| GET | `/usage/breakdown` | Per-agent usage breakdown |
| GET | `/costs/dashboard` | Cost dashboard with forecast |
| GET | `/costs/allocation` | Cost allocation by agent and provider |

### API Keys & Workspaces

| Method | Endpoint | Description |
|--------|----------|-------------|
| GET | `/api-keys` | List API keys |
| POST | `/api-keys` | Create a new API key |
| DELETE | `/api-keys/{id}` | Revoke an API key |
| GET | `/workspaces` | List workspaces |
| POST | `/workspaces` | Create a workspace |

### Error Codes

| Code | Meaning | Retryable |
|------|---------|-----------|
| 400 INVALID_INPUT | Request doesn't match schema | No |
| 401 UNAUTHORIZED | Invalid or missing API key | No |
| 403 FORBIDDEN | Caller lacks permission | No |
| 403 DEPENDENCY_NOT_ALLOWED | Agent not in caller's dependency list | No |
| 403 MAX_HOPS_EXCEEDED | Orchestration call depth exceeded | No |
| 404 NOT_FOUND | Agent or version doesn't exist | No |
| 429 RATE_LIMITED | Too many requests | Yes |
| 502 LLM_ERROR | Upstream LLM provider error | Yes |
| 504 TIMEOUT | Execution exceeded timeout | Yes |

## Pricing

BYOK (Bring Your Own Keys): You provide your own LLM API keys (OpenAI, Anthropic, Google Gemini). orchagent does not charge for LLM token usage — you pay your LLM provider directly.

### Free ($0/month)

- 50 tool / 5 agent executions per day
- 30s tool / 2 min agent timeout
- 2 cron schedules (hourly minimum interval)
- 10 secrets
- 3 agents, 5 skills
- Community support
- No run history, no always-on services, no workspaces

### Pro ($29/month)

- 500 tool / 50 agent executions per day
- 2 min tool / 5 min agent timeout
- 20 cron schedules (every-minute interval)
- 5 concurrent runs
- 50 secrets, 50 private agents
- 1 team workspace with run history and logs
- 2 always-on services included ($7/mo per extra service)
- Email support (24hr response)

### Team ($99/month)

- 2,000 tool / 200 agent executions per day
- 5 min tool and agent timeout
- 100 cron schedules (every-minute interval)
- 20 concurrent runs
- 200 secrets, unlimited private agents
- 5 team workspaces with roles
- 5 always-on services included ($7/mo per extra service)
- Priority support (4hr response)

### Enterprise (custom pricing)

- Custom execution limits and timeouts (up to 15 min)
- Unlimited schedules, secrets, agents, workspaces, and services
- SSO, audit logs, SLA guarantee
- Dedicated support

## Key Features

### Multi-Agent Orchestration

Agents can call other agents using the orchagent SDK (`AgentClient.call()`). Declare dependencies in `orchagent.json` under a `manifest` key. The platform handles service key injection, cost attribution through the call chain, cycle detection, and call depth enforcement (`max_hops`).

SDKs available: Python (`pip install orchagent-sdk`) and JavaScript (`npm install orchagent-sdk`).

### Scheduling

Cron schedules for recurring execution (hourly on free, per-minute on paid tiers). Webhook schedules for event-driven triggers (unique URL per schedule). Both support manual triggering via CLI or API.

### Always-On Services

Deploy agents as 24/7 persistent services — Discord bots, Slack listeners, data pipeline monitors. Requires `run_mode: "always_on"` and `runtime.command` in orchagent.json. Managed via `orch service deploy/logs/restart/delete`.

### LLM Cost Tracking

Automatic per-agent, per-run cost tracking for Anthropic, OpenAI, and Gemini — no instrumentation required. Includes cost forecasting, allocation breakdown, cache efficiency metrics, and budget alerts. Available in the web dashboard.

### Sandboxed Execution

Every run gets a fresh, isolated E2B sandbox. Agent code cannot affect infrastructure or other agents. Custom Docker environments supported via `Dockerfile` in your agent bundle (published with `orch publish --docker`). Predefined environments available: `python-ml`, `python-ffmpeg`, `python-image`, `python-scraping`.

### Secrets Vault

Per-workspace encrypted secrets injected as environment variables at runtime. Declare required secrets in orchagent.json via `required_secrets`. Manage via `orch secret create/list/delete` or the web dashboard.

### Immutable Versioning

Each `orch publish` creates an immutable version (v1, v2, v3...). Callers can pin to a specific version or use `latest`. Previous versions remain accessible for rollback via `orch pull` + republish.

### Skills

Knowledge modules (SKILL.md files) that enhance AI coding assistants like Claude Code and Cursor. Install with `orch skill install org/skill-name`. Skills are injected into agent prompts at runtime via `default_skills` in orchagent.json.

### GitHub Import

Connect a GitHub repo to automatically import and sync agents. The GitHub App detects `orchagent.json` files and syncs on push to your default branch.

## Authentication

- **CLI login:** `orch login` opens a browser for OAuth, or use `orch login --key` for API key auth
- **API keys:** Created in the web dashboard or via API. Pass as `Authorization: Bearer {key}`
- **Environment variable:** Set `ORCHAGENT_API_KEY` for non-interactive use (CI/CD, scripts)
- **Agent-to-agent:** The platform auto-injects `ORCHAGENT_SERVICE_KEY` for agents with declared dependencies

## Example Agents

- [security-review](https://orchagent.io/agents/orchagent-public/security-review): Comprehensive security scanning combining secret detection and dependency auditing
- [code-stats](https://orchagent.io/agents/orchagent-public/code-stats): Analyze codebase structure, languages, and complexity metrics
- [leak-finder](https://orchagent.io/agents/orchagent-public/leak-finder): Scan repositories for exposed secrets and credentials

Install the orchagent-guide skill for comprehensive platform documentation:

```bash
orch skill install orchagent-public/orchagent-guide
```

## Configuration

**Config file:** `~/.orchagent/config.json`

**Environment variables (override config):**
- `ORCHAGENT_API_KEY` — API key (recommended for CI/CD)
- `ORCHAGENT_API_URL` — API base URL (default: `https://api.orchagent.io`)
- `ORCHAGENT_DEFAULT_ORG` — Default org for agent lookups

**Resolution order:** CLI flags > environment variables > named profile (`--profile`) > config file > defaults.

## Contact

- [Support](mailto:support@orchagent.io): Email support
- [Dashboard](https://orchagent.io/dashboard): Web UI
- [Docs](https://docs.orchagent.io): Documentation site