orquesta-agent

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> --daemon

The --daemon flag enables automatic restart if the agent exits.

Prerequisites

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

Quick Start

• Generate a token from the Orquesta dashboard (Project > Agent Connection > Generate Token)
• Run the agent with daemon mode (recommended):

npx orquesta-agent --token oat_xxxxxxxxxxxx --daemon

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

Usage

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

Options

Option	Description
-t, --token <token>	Connection token from Orquesta dashboard (required)
-D, --daemon	Run in daemon mode with automatic restart on exit (recommended)
--max-restarts <n>	Maximum restart attempts in daemon mode (0=unlimited, default)
-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
-m, --permission-mode <mode>	Permission mode: auto (default) or supervised

Daemon Mode

The daemon mode provides automatic restart functionality similar to systemd:

# Run with daemon mode (recommended for production)
npx orquesta-agent --token oat_xxxxx --daemon

# Limit restart attempts (default: unlimited)
npx orquesta-agent --token oat_xxxxx --daemon --max-restarts 10

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

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

IDE Hooks — mirror Claude Code and Cursor sessions

Everything above is dispatch: Orquesta sends work down to the agent. Hooks are the opposite direction — you keep working in your own IDE and Orquesta mirrors what happened. No daemon runs, and nothing is ever executed back into your editor.

# Wire both tools (default)
orquesta-agent init --token oat_xxxxx

# Or pick one
orquesta-agent init --token oat_xxxxx --client cursor
orquesta-agent init --token oat_xxxxx --client claude

init writes .orquesta.json (project binding — it is added to .gitignore because it holds the raw token) plus .claude/settings.json and/or .cursor/hooks.json. Hooks you already had are preserved, and re-running init upgrades Orquesta's entries rather than stacking duplicates.

Moment	Claude Code	Cursor	Recorded as
Prompt sent	UserPromptSubmit	beforeSubmitPrompt	The prompt
Tool ran	PostToolUse	postToolUse, afterShellExecution, afterFileEdit	Tool call + result
Answer written	—	afterAgentResponse	The assistant's reply
Session done	Stop	stop	Marks the prompt complete

Cursor surfaces shell runs and file edits as their own events on top of postToolUse, so all three are wired and the handler de-dupes by content — an action reported twice is still logged once.

Two behaviours differ per tool, both deliberate:

• stdout. Claude Code reads UserPromptSubmit stdout as extra model context, so the hook injects a short Orquesta block there. Cursor parses hook stdout as a JSON permission decision, so on that path the hook writes nothing.
• Failure is always silent. Every hook exits 0. An unreachable Orquesta, a revoked token, a malformed payload or a directory with no .orquesta.json all leave your session untouched.

The tool is detected from the payload, so --client is only needed to override the guess. Mirrored prompts arrive with source: terminal and a cli_type of claude-code or cursor-cli, and are excluded from agent dispatch so a hooked session is never re-executed.

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

• Token Validation: Agent sends token to /api/agent/validate
• Credentials Received: Server returns Supabase URL, anon key, channel name
• Channel Subscribe: Agent subscribes to agent:project-{projectId}
• Presence Tracking: Agent reports its hostname, OS, version
• Command Execution: Dashboard broadcasts execute events
• Output Streaming: Agent broadcasts output events in real-time
• 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:

• Add credentials in Dashboard > Project > Settings > Credentials
• Agent automatically receives them on connection
• 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:

• Go to Project > Agent Connection
• Click "Regenerate Token"
• Copy the new command

Agent shows "Offline" in dashboard

The agent sends heartbeats every 30 seconds. If offline:

• Check agent is running
• Check network connectivity
• 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