Skip to main content
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.

​
Step 1: Install CLI & Sign Up

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

CommandWhat It DoesWhere It Runs
orch run <agent>Execute agentCloud (E2B sandbox) by default
orch run --local <agent>Download and execute agent locallyYour machine
orch install <agent>Export agent as sub-agent for AI toolsLocal files
orch skill install <skill>Download skill files for AI toolsLocal files
orch pull <agent>Reconstruct a local project from a published agent-
orch fork <agent>Fork a public agent into your workspace-
orch updateUpdate installed agents to latest-
orch formatsList available export formats-
orch schedule createCreate cron or webhook scheduleCloud
orch schedule listList your schedules-
orch service deployDeploy agent as always-on serviceCloud (Cloud Run)
orch service listList 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