Local vs Server Execution

orchagent offers three ways to use agents:

Command	Purpose	Where It Runs
`orch run`	Execute agent now	Cloud (E2B sandbox) by default
`orch run --local`	Execute agent now	Your machine
`orch dev`	HTTP dev server with hot-reload	Your machine
`orch install`	Export for AI tools	Creates local files
`orch service deploy`	Deploy always-on service	Cloud (Cloud Run)

Quick Comparison: Cloud vs Local

	Cloud (`orch run`, default)	Local (`orch run --local`)
Primary users	Apps in production	Power users, devs exploring
Interface	CLI or HTTP API	CLI
Where code runs	E2B sandboxes (ephemeral)	Your machine
Account required	Yes (free)	No
LLM keys	From your account	From your environment
Rate limits	1000 calls/day free	Your LLM provider limits
Dependencies	Handled automatically	Must be downloadable
Download toggle	Always available	Author must enable `allow_local_download`
Paid agents	Anyone (credits charged)	Owner only (free for testing)
Best for	Production integration	Development, exploration

Production apps call the HTTP API directly from code. The CLI is useful for testing.

Local download is on by default. New agents and skills are locally downloadable unless authors explicitly disable it using the --no-local-download flag at publish time or the toggle in the web UI.

Cloud Execution (`orch run`)

Run an agent on orchagent’s servers. This is the default mode.

orch run acme/summarizer --data '{"text": "..."}'

What Happens

CLI sends request to gateway (api.orchagent.io)
Gateway authenticates your API key
Gateway spins up an E2B sandbox (ephemeral)
Agent code runs with input via stdin
Agent runs with your stored LLM keys
Response (stdout) returned through gateway

When to Use

Production - Reliable, managed infrastructure
Orchestration - Agents calling other agents
No local setup - Run without installing dependencies
Higher reliability - Auto-scaling, health checks

Requirements

orchagent account (free)
API key from dashboard
LLM key stored in account

Local Execution (`orch run --local`)

Download and run an agent on your machine.

# No account needed for public agents
npx orchagent run --local acme/summarizer --input '{"text": "..."}'

# With CLI installed
orch run --local acme/summarizer --input '{"text": "..."}'

What Happens

CLI downloads agent code from registry
Agent installs on your machine
Agent runs locally
Agent calls LLM using YOUR environment keys
Results returned to terminal

When to Use

Development - Test agents before deploying
Privacy - Keep data on your machine
No account - Try agents without signing up
Debugging - See full execution locally

Requirements

Agent must have source_url or pip_package in manifest
Agent must have allow_local_download enabled by its author
LLM API key in environment variable
For orchestrators: dependencies must also be downloadable

Architecture Diagrams

Local Execution

┌──────────────┐      ┌──────────────┐      ┌──────────────┐
│  Your CLI    │─────▶│ Agent Code   │─────▶│  LLM API     │
│              │      │ (local)      │      │  (direct)    │
└──────────────┘      └──────────────┘      └──────────────┘
      │                      │
      └──────────────────────┘
           All on your machine

Server Execution

┌──────────────┐      ┌──────────────┐      ┌──────────────┐
│  Your CLI    │─────▶│  Gateway     │─────▶│ E2B Sandbox  │
│              │      │              │      │ (ephemeral)  │
└──────────────┘      └──────────────┘      └──────┬───────┘
                                                   │
                             ┌─────────────────────┘
                             ▼
                      ┌──────────────┐
                      │  LLM API     │
                      │  (via proxy) │
                      └──────────────┘

Handling Dependencies

Local with Dependencies

Orchestrator agents have dependencies. When running locally:

$ orch run joe/security-review .

Checking dependencies...

This agent has dependencies:
  joe/leak-finder@v1 (downloadable)
  joe/vuln-scanner@v1 (downloadable)
  acme/premium-scan@v1 (cloud-only)

Options:
  [1] Run on cloud (orch run) - recommended
  [2] Download 2 available deps, run locally
  [3] Cancel

Auto-download:

orch run joe/security-review --with-deps .

Server with Dependencies

On the server, dependencies are handled automatically. The gateway routes calls between agents.

Installing Agents as Sub-Agents (`orch install`)

A third option: export agents as configuration files for AI coding tools like Claude Code or Cursor.

# Install to Claude Code (default)
orch install joe/code-reviewer

# Install to Cursor
orch install joe/code-reviewer --format cursor

# Install to project directory
orch install joe/code-reviewer --scope project

What happens:

CLI downloads agent metadata from registry
Converts to target format (Claude Code, Cursor, AGENTS.md)
Writes configuration file to AI tool directory

When to use install:

You want Claude Code or Cursor to delegate tasks to specialized agents
You want sub-agents available across all your projects
You’re building a team workflow with shared agents

Key difference from run:

run executes the agent immediately and returns results
install creates files that your AI tool reads later

See CLI Commands for full details.

Service Deployment (`orch service deploy`)

A fourth mode: deploy agents as always-on services (run_mode: "always_on") that run continuously on Cloud Run.

orch service deploy acme/discord-bot \
  --secret DISCORD_BOT_TOKEN \
  --env BOT_PREFIX="!"

How It Differs

	On-demand (`run_mode: "on_demand"`)	Always-on (`run_mode: "always_on"`)
Runtime	Ephemeral E2B sandbox	Persistent Cloud Run container
Lifetime	Seconds to minutes	Runs indefinitely
Use case	Request/response tasks	Bots, listeners, workers
Restart on crash	No (single execution)	Yes (automatic)
State	Stateless	Can maintain in-memory state
Requires	Any agent	`runtime.command` or `loop` config

See Always-On Services for full documentation.

CLI Commands Summary

Command	Mode	Description
`orch run`	Cloud	Run on orchagent servers (default)
`orch run --local`	Local	Run with installed CLI
`orch dev`	Local	HTTP dev server with hot-reload
`npx orchagent run --local`	Local	Run without installing CLI
`orch run --local --download-only`	Local	Just download, don’t execute
`orch run --local --with-deps`	Local	Auto-download dependencies
`orch service deploy`	Service	Deploy as always-on service
`orch install`	Export	Create sub-agent files for AI tools
`orch update`	Export	Update installed sub-agents
`orch formats`	Export	List available export formats

Choosing the Right Mode

Use Local (`--local` or `orch dev`) When

You want to keep data on your machine
You’re developing or debugging an agent (use orch dev for hot-reload)
You want to try an agent without an account
The agent doesn’t have complex dependencies
The agent author has enabled allow_local_download

Use Cloud (Default) When

You’re building production integrations
The agent has dependencies (orchestrator)
You want managed infrastructure
You need usage tracking and logs
The agent does not allow local download
You want usage tracking and logs

Development Server (`orch dev`)

For active development, use orch dev to start a local HTTP server with hot-reload:

orch dev

This starts a server on http://localhost:4900 that:

Accepts POST requests with JSON input and runs your agent locally
Watches for file changes and reloads automatically
Works with all agent types (prompt, tool, agent)

# Terminal 1: Start dev server
orch dev

# Terminal 2: Send test requests
curl -X POST http://localhost:4900/run \
  -H "Content-Type: application/json" \
  -d '{"task": "hello world"}'

See CLI Commands — dev for full options.

Mixed Mode

You can use all modes in your development workflow:

# Active development with hot-reload
orch dev

# One-off local test
orch run --local my-agent --input '{"test": true}'

# Test on cloud
orch run my-agent --data '{"test": true}'

# Deploy to production
# (Your app calls api.orchagent.io directly)

Get Started

Using Agents

Building Agents

Guides

Concepts

API Reference

Local vs Server Execution

Quick Comparison: Cloud vs Local

Cloud Execution (`orch run`)

What Happens

When to Use

Requirements

Local Execution (`orch run --local`)

What Happens

When to Use

Requirements

Architecture Diagrams

Local Execution

Server Execution

Handling Dependencies

Local with Dependencies

Server with Dependencies

Installing Agents as Sub-Agents (`orch install`)

Service Deployment (`orch service deploy`)

How It Differs

CLI Commands Summary

Choosing the Right Mode

Use Local (`--local` or `orch dev`) When

Use Cloud (Default) When

Development Server (`orch dev`)

Mixed Mode

Get Started

Using Agents

Building Agents

Guides

Concepts

API Reference

​Quick Comparison: Cloud vs Local

​Cloud Execution (orch run)

​What Happens

​When to Use

​Requirements

​Local Execution (orch run --local)

​What Happens

​When to Use

​Requirements

​Architecture Diagrams

​Local Execution

​Server Execution

​Handling Dependencies

​Local with Dependencies

​Server with Dependencies

​Installing Agents as Sub-Agents (orch install)

​Service Deployment (orch service deploy)

​How It Differs

​CLI Commands Summary

​Choosing the Right Mode

​Use Local (--local or orch dev) When

​Use Cloud (Default) When

​Development Server (orch dev)

​Mixed Mode

Quick Comparison: Cloud vs Local

Cloud Execution (`orch run`)

What Happens

When to Use

Requirements

Local Execution (`orch run --local`)

What Happens

When to Use

Requirements

Architecture Diagrams

Local Execution

Server Execution

Handling Dependencies

Local with Dependencies

Server with Dependencies

Installing Agents as Sub-Agents (`orch install`)

Service Deployment (`orch service deploy`)

How It Differs

CLI Commands Summary

Choosing the Right Mode

Use Local (`--local` or `orch dev`) When

Use Cloud (Default) When

Development Server (`orch dev`)

Mixed Mode