orquesta-agent

Local agent for Orquesta - connects your VM to the Orquesta dashboard for collaborative AI-powered development.

Installation

npm install -g orquesta-agent

Or run directly with npx:

npx orquesta-agent --token <your-token>

Prerequisites

• Node.js 18+
• Claude CLI installed and authenticated
• An Orquesta account with a project

Quick Start

1. Generate a token from the Orquesta dashboard (Project > Agent Connection > Generate Token)
2. Run the agent:

npx orquesta-agent --token oat_xxxxxxxxxxxx

3. Submit prompts from the Orquesta dashboard - they'll execute on your machine

Usage

orquesta-agent [options]
orquesta-agent setup    # Check prerequisites

Options

| Option | Description | |--------|-------------| | -t, --token <token> | Connection token from Orquesta dashboard (required) | | -v, --verbose | Enable verbose logging | | -d, --working-dir <dir> | Working directory for command execution | | --no-auto-clone | Disable automatic repository cloning | | --no-auto-pull | Disable automatic git pull before prompts |

Setup Command

Run the setup wizard to check prerequisites:

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                   │
└─────────────────────────────────────────────────────────────┘

Connection Flow

1. Token Validation: Agent sends token to /api/agent/validate
2. Credentials Received: Server returns Supabase URL, anon key, channel name
3. Channel Subscribe: Agent subscribes to agent:project-{projectId}
4. Presence Tracking: Agent reports its hostname, OS, version
5. Command Execution: Dashboard broadcasts execute events
6. Output Streaming: Agent broadcasts output events in real-time
7. Completion: Agent broadcasts complete with exit code

Message Protocol

Dashboard → Agent:

• execute: Run a prompt { id, promptId, content, workingDirectory? }
• cancel: Kill running process { id }
• ping: Heartbeat check { timestamp }

Agent → Dashboard:

• output: Stream data { id, type: 'stdout'|'stderr', data, timestamp }
• complete: Finished { id, exitCode, duration }
• error: Failed { id, error, code? }
• pong: Heartbeat response { timestamp, latency }

Authentication

The agent supports two Claude authentication methods:

Option 1: API Key (Recommended for servers)

export ANTHROPIC_API_KEY=sk-ant-xxxxx
npx orquesta-agent --token oat_xxxxx

Option 2: Web Subscription (Pro/Max users)

On your local machine (with browser):

claude auth login

Then copy credentials to the server:

scp ~/.claude/.credentials.json user@server:~/.claude/

Server-Provisioned Credentials

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:

Auto-Clone

If a repository URL is configured in Orquesta:

npx orquesta-agent --token oat_xxxxx
# Automatically clones repo if not present

Disable with --no-auto-clone.

Auto-Pull

Before each prompt execution:

# Agent runs: git pull
# Then executes the prompt

Disable with --no-auto-pull.

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

Claude CLI not found

npm install -g @anthropic-ai/claude-code

Claude not authenticated

# Option 1: Set API key
export ANTHROPIC_API_KEY=sk-ant-xxxxx

# Option 2: Login (requires browser)
claude auth login

Connection issues

• Check internet connection
• Verify token is valid (not revoked/expired)
• Ensure no firewall blocking WebSocket (port 443)

Token expired

Generate a new token from the dashboard:

1. Go to Project > Agent Connection
2. Click "Regenerate Token"
3. Copy the new command

Agent shows "Offline" in dashboard

The agent sends heartbeats every 30 seconds. If offline:

1. Check agent is running
2. Check network connectivity
3. Restart agent with --verbose to see errors

Development

# Clone the repo
git clone https://github.com/your-org/orquesta.git
cd orquesta/packages/orquesta-agent

# Install dependencies
npm install

# Build
npm run build

# Run locally
npm start -- --token oat_xxxxx

License

MIT