ClaudiOS Agent Runtime

Standalone agent runtime that polls the ClaudiOS server for instructions and executes Claude CLI sessions.

Features

• Polls server for instructions at configurable intervals
• Executes Claude CLI sessions with real-time output streaming
• Supports multiple concurrent sessions
• Automatic error reporting and recovery
• Output signing with HMAC for security
• Buffered output streaming for network resilience

Tech Stack

• Node.js 20+
• TypeScript
• Child process management
• HTTP client for server communication
• Vitest for testing

Setup

Install Dependencies

npm install

Build

npm run build

Configuration

Create a config.json file:

{
  "serverUrl": "http://localhost:3000",
  "agentToken": "your-agent-token-here",
  "pollInterval": 5000,
  "outputFlushInterval": 1000,
  "maxConcurrentSessions": 5
}

Or use environment variables:

SERVER_URL=http://localhost:3000
AGENT_TOKEN=your-agent-token-here
POLL_INTERVAL=5000
OUTPUT_FLUSH_INTERVAL=1000
MAX_CONCURRENT_SESSIONS=5

Get Agent Token

1. Register/login to ClaudiOS web interface
2. Create a project
3. Create an agent for that project
4. Copy the agent token (shown once)
5. Use the token in your agent configuration

Usage

Start Agent

# Using config file
npm start

# Using environment variables
SERVER_URL=http://localhost:3000 AGENT_TOKEN=xxx npm start

# With custom config file
npm start -- --config /path/to/config.json

# Show help
npm start -- --help

# Show version
npm start -- --version

Stop Agent

Press Ctrl+C to gracefully stop the agent. All running sessions will be terminated.

How It Works

1. Polling Loop: Agent polls server every pollInterval milliseconds
2. Instruction Processing: When instructions are received:
   • start_session: Spawn new Claude CLI process
   • command: Send command to existing session
   • terminate_session: Terminate session gracefully
3. Output Streaming: Capture stdout/stderr and stream to server with HMAC signature
4. Error Handling: Report errors to server and continue polling
5. Status Reporting: Periodically report agent status to server

Architecture

Components

• Runtime: Main agent lifecycle and polling loop
• Session Manager: Manages Claude CLI processes
• Output Streamer: Captures and streams output with buffering
• Client: HTTP client for server communication
• Config: Configuration management

Session Lifecycle

┌─────────────┐
│   Queued    │
└──────┬──────┘
       │ start_session instruction
       ▼
┌─────────────┐
│   Running   │◄──── command instruction
└──────┬──────┘
       │ terminate_session or process exit
       ▼
┌─────────────┐
│ Terminated  │
└─────────────┘

Output Streaming

Claude CLI Process
       │
       ├─ stdout ──┐
       │           │
       └─ stderr ──┤
                   │
                   ▼
            Output Streamer
                   │
                   ├─ Buffer
                   ├─ Sign with HMAC
                   └─ Send to Server
                          │
                          ▼
                   WebSocket Server
                          │
                          ▼
                    Web Clients

Configuration Options

| Option | Type | Default | Description | |--------|------|---------|-------------| | serverUrl | string | required | ClaudiOS server URL | | agentToken | string | required | Agent authentication token | | pollInterval | number | 5000 | Polling interval in milliseconds | | outputFlushInterval | number | 1000 | Output flush interval in milliseconds | | maxConcurrentSessions | number | 5 | Maximum concurrent sessions |

Testing

# Run all tests
npm test

# Run tests in watch mode
npm run test:watch

# Run with coverage
npm run test:coverage

Troubleshooting

Agent can't connect to server

• Verify serverUrl is correct and accessible
• Check network connectivity
• Verify firewall rules allow outbound connections
• Check server logs for authentication errors

Agent token invalid

• Verify token is correct (no extra spaces)
• Check if token was regenerated on server
• Create a new agent and get a new token

Sessions not starting

• Verify Claude CLI is installed and in PATH
• Check Claude CLI authentication
• Verify agent has permission to spawn processes
• Check system resources (CPU, memory)

Output not streaming

• Check network connectivity
• Verify server WebSocket is running
• Check for buffering issues
• Review agent logs for errors

High CPU usage

• Reduce pollInterval to poll less frequently
• Reduce maxConcurrentSessions
• Check for runaway Claude CLI processes
• Monitor system resources

Security

• Agent token is used for authentication
• Output is signed with HMAC-SHA256
• Server verifies output signatures
• Tokens are never logged
• Secure communication over HTTPS (in production)

Monitoring

The agent logs:

• Startup and shutdown events
• Polling activity
• Instruction processing
• Session lifecycle events
• Errors and warnings

Example log output:

[INFO] Agent starting...
[INFO] Configuration loaded from config.json
[INFO] Polling server at http://localhost:3000
[INFO] Received instruction: start_session (session-123)
[INFO] Session started: session-123
[INFO] Streaming output for session-123
[INFO] Received instruction: command (session-123)
[INFO] Command sent to session-123
[INFO] Session terminated: session-123

Production Deployment

Systemd Service (Linux)

Create /etc/systemd/system/claudios-agent.service:

[Unit]
Description=ClaudiOS Agent
After=network.target

[Service]
Type=simple
User=claudios
WorkingDirectory=/opt/claudios-agent
ExecStart=/usr/bin/node /opt/claudios-agent/dist/index.js
Restart=always
RestartSec=10
Environment=NODE_ENV=production

[Install]
WantedBy=multi-user.target

Enable and start:

sudo systemctl enable claudios-agent
sudo systemctl start claudios-agent
sudo systemctl status claudios-agent

Docker

docker build -t claudios-agent .
docker run -d \
  --name claudios-agent \
  -e SERVER_URL=https://api.yourdomain.com \
  -e AGENT_TOKEN=xxx \
  claudios-agent

Process Manager (PM2)

npm install -g pm2
pm2 start dist/index.js --name claudios-agent
pm2 save
pm2 startup

Development

# Install dependencies
npm install

# Run in development mode with hot reload
npm run dev

# Build
npm run build

# Lint
npm run lint

# Format
npm run format

License

MIT License - see LICENSE file for details