Local agent for Orquesta - connects your VM to the Orquesta dashboard
npm install orquesta-agentLocal agent for Orquesta - connects your VM to the Orquesta dashboard for collaborative AI-powered development.
``bash`
npm install -g orquesta-agent
Or run directly with npx:
`bash`
npx orquesta-agent --token
The --daemon flag enables automatic restart if the agent exits.
- Node.js 18+
- Claude CLI installed and authenticated
- An Orquesta account with a project
1. Generate a token from the Orquesta dashboard (Project > Agent Connection > Generate Token)
2. Run the agent with daemon mode (recommended):
`bash`
npx orquesta-agent --token oat_xxxxxxxxxxxx --daemon
3. Submit prompts from the Orquesta dashboard - they'll execute on your machine
The --daemon flag ensures the agent automatically restarts if it exits for any reason.
`bash`
orquesta-agent [options]
orquesta-agent setup # Check prerequisites
| Option | Description |
|--------|-------------|
| -t, --token | Connection token from Orquesta dashboard (required) |-D, --daemon
| | Run in daemon mode with automatic restart on exit (recommended) |--max-restarts
| | Maximum restart attempts in daemon mode (0=unlimited, default) |-v, --verbose
| | Enable verbose logging |-d, --working-dir
| | Working directory for command execution |--no-auto-clone
| | Disable automatic repository cloning |--no-auto-pull
| | Disable automatic git pull before prompts |-m, --permission-mode
| | Permission mode: auto (default) or supervised |
The daemon mode provides automatic restart functionality similar to systemd:
`bashRun with daemon mode (recommended for production)
npx orquesta-agent --token oat_xxxxx --daemon
Features:
- Automatic restart: Restarts agent if it crashes or exits
- Exponential backoff: 1s to 60s delay between restarts
- Failure counter reset: After 5 minutes of stable uptime, failure count resets
- Graceful shutdown: Forwards SIGINT/SIGTERM to child process
$3
Run the setup wizard to check prerequisites:
bash
npx orquesta-agent setup
`This checks:
- Claude CLI installation
- Claude authentication (API key or web subscription)
- Git installation
Architecture
┌─────────────────────────────────────────────────────────────┐
│ ORQUESTA DASHBOARD │
│ (orquesta.live) │
└──────────────────────────┬──────────────────────────────────┘
│
Supabase Realtime
(WebSocket)
│
▼
┌─────────────────────────────────────────────────────────────┐
│ LOCAL AGENT │
│ │
│ 1. Validates token with Orquesta API │
│ 2. Receives Supabase credentials │
│ 3. Subscribes to project channel │
│ 4. Listens for 'execute' commands │
│ 5. Spawns Claude CLI: claude --print "..." │
│ 6. Streams stdout/stderr back via broadcast │
│ 7. Sends 'complete' or 'error' when done │
└─────────────────────────────────────────────────────────────┘
$3
1. Token Validation: Agent sends token to
2. Credentials Received: Server returns Supabase URL, anon key, channel name
3. Channel Subscribe: Agent subscribes to
4. Presence Tracking: Agent reports its hostname, OS, version
5. Command Execution: Dashboard broadcasts events
6. Output Streaming: Agent broadcasts output events in real-time
7. Completion: Agent broadcasts complete with exit code$3
Dashboard → Agent:
-
execute: Run a prompt { id, promptId, content, workingDirectory? }
- : Kill running process { id }
- : Heartbeat check { timestamp }Agent → Dashboard:
-
: Stream data { id, type: 'stdout'|'stderr', data, timestamp }
- : Finished { id, exitCode, duration }
- : Failed { id, error, code? }
- : Heartbeat response { timestamp, latency }Authentication
The agent supports two Claude authentication methods:
$3
bash
export ANTHROPIC_API_KEY=sk-ant-xxxxx
npx orquesta-agent --token oat_xxxxx
`$3
On your local machine (with browser):
bash
claude auth login
`Then copy credentials to the server:
bash
scp ~/.claude/.credentials.json user@server:~/.claude/
`$3
If you've stored an Anthropic API key in Orquesta:
1. Add credentials in Dashboard > Project > Settings > Credentials
2. Agent automatically receives them on connection
3. No local configuration needed
Git Integration
The agent can automatically manage your repository:
$3
If a repository URL is configured in Orquesta:
bash
npx orquesta-agent --token oat_xxxxx
Automatically clones repo if not present
`Disable with
.$3
Before each prompt execution:
`bash
Agent runs: git pull
Then executes the prompt
`Disable with
.Security
- Your code stays local: No code is uploaded to Orquesta
- Outbound only: No exposed ports or SSH access required
- Token-based auth: Revocable anytime from dashboard
- SHA-256 hashed: Raw token never stored on server
- TLS encrypted: All WebSocket traffic over HTTPS
- 1-year expiration: Tokens auto-expire for security
Troubleshooting
$3
`bash
npm install -g @anthropic-ai/claude-code
`$3
bash
Option 1: Set API key
export ANTHROPIC_API_KEY=sk-ant-xxxxxOption 2: Login (requires browser)
claude auth login
`$3
- Check internet connection
- Verify token is valid (not revoked/expired)
- Ensure no firewall blocking WebSocket (port 443)
$3
Generate a new token from the dashboard:
1. Go to Project > Agent Connection
2. Click "Regenerate Token"
3. Copy the new command
$3
The agent sends heartbeats every 30 seconds. If offline:
1. Check agent is running
2. Check network connectivity
3. Restart agent with
to see errorsDevelopment
`bash
Clone the repo
git clone https://github.com/your-org/orquesta.git
cd orquesta/packages/orquesta-agentInstall dependencies
npm installBuild
npm run buildRun locally
npm start -- --token oat_xxxxx
``MIT