> ## 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.

# Quickstart

> Deploy your first agent in minutes

Build an agent, deploy it, and run it — all from your terminal.

<Tip>
  orchagent has four types: **prompt**, **tool**, **agent**, and **skill**. The commands below work for all of them. See [Agent Types](/building-agents/agent-types) for the differences.
</Tip>

## Prerequisites

Set up an LLM API key in your environment:

```bash theme={null}
export GEMINI_API_KEY="your-key"
# or
export OPENAI_API_KEY="your-key"
# or
export ANTHROPIC_API_KEY="your-key"
```

<Note>
  API keys are separate from subscriptions. If you use Claude Pro/Max or ChatGPT Plus, you'll need to set up API billing separately at [console.anthropic.com](https://console.anthropic.com) or [platform.openai.com](https://platform.openai.com).
</Note>

## Step 1: Install CLI & Sign Up

```bash theme={null}
npm install -g @orchagent/cli
```

Go to [orchagent.io](https://orchagent.io) and create a free account, then authenticate:

```bash theme={null}
orchagent login
```

### Verify Setup (Optional)

```bash theme={null}
orchagent doctor
```

This checks your environment, config, and connectivity. If everything shows green checkmarks, you're ready to go.

## Step 2: Create an Agent

Initialize a new agent project:

```bash theme={null}
orch init my-agent
cd my-agent
```

<Tip>
  **Not sure what to build?** Run `orch init` with no arguments in your terminal to launch an interactive wizard. It walks you through choosing a use case, language, and template — no flags needed.
</Tip>

This creates:

* `orchagent.json` — agent manifest (type: `"prompt"` by default)
* `prompt.md` — your prompt template
* `schema.json` — input/output schemas

Edit `prompt.md` with your prompt and `schema.json` with your input/output definitions.

<Tip>
  **Building a tool type?** Use `orch init my-tool --type tool` to scaffold a code runtime project. Add `--language javascript` for JavaScript with `main.js` and `package.json`, or use `--template discord-js` for a JavaScript Discord bot. See [CLI Commands](/using-agents/cli-commands#init) for all options.
</Tip>

<Tip>
  **Using Claude Code, Cursor, or another AI coding tool?** Install the agent-builder skill for the complete platform reference:

  ```bash theme={null}
  orch skill install orchagent/agent-builder
  ```

  Your AI assistant will know the exact sandbox contracts, boilerplate patterns, and environment details to build any agent type.
</Tip>

<Tip>
  By default, `orch init` creates a `prompt` type (prompt + schema → single LLM call). Use `--type tool` for code runtime or `--type agent` for a managed LLM loop. See [CLI Commands](/using-agents/cli-commands#init) for all options.
</Tip>

## Step 3: Test Locally

```bash theme={null}
orch run . --local --input '{"text": "test input"}'
```

This runs the agent on your machine using your local LLM keys.

<Tip>
  **Tip: Use `@file` for complex inputs.** Shell special characters (`!`, `$`, backticks) can break inline JSON. Put your input in a file instead:

  ```bash theme={null}
  orch run . --local --data @input.json
  ```

  This reads JSON from `input.json` — no escaping needed. Also supports `@-` for stdin.
</Tip>

## Step 4: Publish

```bash theme={null}
orch publish
```

Your agent is now live and runnable by your team.

## Step 5: Run It

```bash theme={null}
# Via CLI — inline JSON
orchagent run yourorg/my-agent --data '{"text": "hello world"}'

# Via CLI — JSON from file (recommended for complex inputs)
orchagent run yourorg/my-agent --data @input.json

# Or your team can use the web UI at orchagent.io
```

***

## Try a Deployed Agent

Want to see the platform in action first? Run one of our showcase agents:

### Run Locally (No Account Needed)

```bash theme={null}
npx @orchagent/cli run --local orchagent/secrets-scanner https://github.com/your/repo
```

### Run on Server

```bash theme={null}
orchagent run orchagent/secrets-scanner https://github.com/your/repo
```

***

## Quick Reference

| Command                      | What It Does                                       | Where It Runs                  |
| ---------------------------- | -------------------------------------------------- | ------------------------------ |
| `orch run <agent>`           | Execute agent                                      | Cloud (E2B sandbox) by default |
| `orch run --local <agent>`   | Download and execute agent locally                 | Your machine                   |
| `orch install <agent>`       | Export agent as sub-agent for AI tools             | Local files                    |
| `orch skill install <skill>` | Download skill files for AI tools                  | Local files                    |
| `orch pull <agent>`          | Reconstruct a local project from a published agent | -                              |
| `orch fork <agent>`          | Fork a public agent into your workspace            | -                              |
| `orch update`                | Update installed agents to latest                  | -                              |
| `orch formats`               | List available export formats                      | -                              |
| `orch schedule create`       | Create cron or webhook schedule                    | Cloud                          |
| `orch schedule list`         | List your schedules                                | -                              |
| `orch service deploy`        | Deploy agent as always-on service                  | Cloud (Cloud Run)              |
| `orch service list`          | List running services                              | -                              |

### When to Use What

```
Want AI to DO something now?
  |-- Need it local/private? --> orch run --local
  \-- Want managed infra?    --> orch run

Want AI to KNOW something?
  \-- Download knowledge     --> orch skill install

Want to DELEGATE to sub-agents?
  \-- Export for AI tools    --> orch install

Want to RECONSTRUCT a local project?
  \-- Pull published source  --> orch pull
```

## Running with Files

Many agents process files. Pass a file as an argument or use the `--file` flag:

```bash theme={null}
# Code runtime agents: pass file as argument (uploaded to sandbox)
orchagent run acme/invoice-scanner invoice.pdf

# Direct LLM agents: use --file (content is read and mapped to input schema)
orchagent run acme/useeffect-checker --file src/App.tsx

# Pipe file to stdin
cat document.pdf | orchagent run acme/pdf-parser
```

## Running with JSON

For direct LLM agents that accept JSON input:

```bash theme={null}
# Inline JSON
orchagent run acme/text-extractor --data '{"text":"hello world"}'

# JSON from file
orchagent run acme/text-extractor --data @input.json
```

## Next Steps

<CardGroup cols={2}>
  <Card title="API Reference" icon="code" href="/using-agents/api-reference">
    Full endpoint documentation
  </Card>

  <Card title="CLI Commands" icon="terminal" href="/using-agents/cli-commands">
    All CLI commands explained
  </Card>

  <Card title="Agent Types" icon="hammer" href="/building-agents/agent-types">
    The four types — prompt, tool, agent, skill
  </Card>

  <Card title="Code Examples" icon="brackets-curly" href="/using-agents/code-snippets">
    Python, JavaScript, curl examples
  </Card>
</CardGroup>