Quickstart

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

orchagent has four types: prompt, tool, agent, and skill. The commands below work for all of them. See Agent Types for the differences.

Prerequisites

Set up an LLM API key in your environment:

export GEMINI_API_KEY="your-key"
# or
export OPENAI_API_KEY="your-key"
# or
export ANTHROPIC_API_KEY="your-key"

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 or platform.openai.com.

npm install -g @orchagent/cli

Go to orchagent.io and create a free account, then authenticate:

orchagent login

Verify Setup (Optional)

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:

orch init my-agent
cd my-agent

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.

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.

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 for all options.

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

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.

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 for all options.

Step 3: Test Locally

orch run . --local --input '{"text": "test input"}'

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

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

orch run . --local --data @input.json

This reads JSON from input.json — no escaping needed. Also supports @- for stdin.

Step 4: Publish

orch publish

Your agent is now live and runnable by your team.

Step 5: Run It

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

npx @orchagent/cli run --local orchagent/secrets-scanner https://github.com/your/repo

Run on Server

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:

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

# Inline JSON
orchagent run acme/text-extractor --data '{"text":"hello world"}'

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

Next Steps

API Reference

Full endpoint documentation

CLI Commands

All CLI commands explained

Agent Types

The four types — prompt, tool, agent, skill

Code Examples

Python, JavaScript, curl examples

Get Started

Using Agents

Building Agents

Guides

Concepts

API Reference

Prerequisites

Verify Setup (Optional)

Step 2: Create an Agent

Step 3: Test Locally

Step 4: Publish

Step 5: Run It

Try a Deployed Agent

Run Locally (No Account Needed)

Run on Server

Quick Reference

When to Use What

Running with Files

Running with JSON

Next Steps

API Reference

CLI Commands

Agent Types

Code Examples

​Prerequisites

​Step 1: Install CLI & Sign Up

​Verify Setup (Optional)

​Step 2: Create an Agent

​Step 3: Test Locally

​Step 4: Publish

​Step 5: Run It

​Try a Deployed Agent

​Run Locally (No Account Needed)

​Run on Server

​Quick Reference

​When to Use What

​Running with Files

​Running with JSON

​Next Steps

API Reference

CLI Commands

Agent Types

Code Examples

Prerequisites

Step 1: Install CLI & Sign Up

Verify Setup (Optional)

Step 2: Create an Agent

Step 3: Test Locally

Step 4: Publish

Step 5: Run It

Try a Deployed Agent

Run Locally (No Account Needed)

Run on Server

Quick Reference

When to Use What

Running with Files

Running with JSON

Next Steps