> ## Documentation Index
> Fetch the complete documentation index at: https://docs.orchagent.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Local vs Server Execution

> Understanding cloud, local, and install modes

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.

<Note>
  **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.
</Note>

## Cloud Execution (`orch run`)

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

```bash theme={null}
orch run acme/summarizer --data '{"text": "..."}'
```

### What Happens

1. CLI sends request to gateway (`api.orchagent.io`)
2. Gateway authenticates your API key
3. Gateway spins up an E2B sandbox (ephemeral)
4. Agent code runs with input via stdin
5. Agent runs with your stored LLM keys
6. 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.

```bash theme={null}
# 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

1. CLI downloads agent code from registry
2. Agent installs on your machine
3. Agent runs locally
4. Agent calls LLM using YOUR environment keys
5. 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:**

```bash theme={null}
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.

```bash theme={null}
# 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:**

1. CLI downloads agent metadata from registry
2. Converts to target format (Claude Code, Cursor, AGENTS.md)
3. 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](/using-agents/cli-commands#install) 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.

```bash theme={null}
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](/using-agents/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:

```bash theme={null}
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)

```bash theme={null}
# 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](/using-agents/cli-commands#dev) for full options.

## Mixed Mode

You can use all modes in your development workflow:

```bash theme={null}
# 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)
```