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

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

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.

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

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