Skilliks Agent

API server for remote Claude Code execution with queue management and process control.

Features

• Remote Execution: Execute Claude Code prompts via REST API
• Queue Management: Priority-based queue with configurable concurrency
• Process Control: Kill, monitor, and manage running processes
• Security: API key authentication and rate limiting
• Health Monitoring: Built-in health checks and metrics
• CLI Tool: Command-line interface for server management
• Configurable: Environment variables and config file support

Installation

Global Installation (Recommended)

npm install -g skilliks-agent

Local Installation

npm install skilliks-agent

Quick Start

1. Initialize configuration:

skilliks-agent init

This creates a config file at ~/.skilliks-agent.json with a generated API key.

2. Start the server:

skilliks-agent start

Or with custom options:

skilliks-agent start --port 3456 --api-key your-secure-key

3. Check server status:

skilliks-agent status

Configuration

Environment Variables

SKILLIKS_PORT=3456                 # Server port
SKILLIKS_HOST=0.0.0.0             # Server host
SKILLIKS_API_KEY=your-key         # API authentication key
SKILLIKS_MAX_CONCURRENT=3         # Max concurrent processes
SKILLIKS_DEFAULT_TIMEOUT=300000   # Default timeout (ms)
SKILLIKS_MAX_QUEUE_SIZE=100       # Maximum queue size
SKILLIKS_RATE_LIMIT_MAX=10        # Rate limit max requests
SKILLIKS_RATE_LIMIT_WINDOW=60000  # Rate limit window (ms)
SKILLIKS_LOG_LEVEL=info           # Log level
SKILLIKS_LOG_FILE=/path/to/log    # Log file path
SKILLIKS_ENV=production           # Environment

Config File

Create ~/.skilliks-agent.json:

{
  "port": 3456,
  "host": "0.0.0.0",
  "apiKey": "your-secure-api-key",
  "maxConcurrent": 3,
  "defaultTimeout": 300000,
  "maxQueueSize": 100,
  "rateLimitMax": 10,
  "rateLimitWindow": 60000,
  "logLevel": "info",
  "env": "production"
}

API Endpoints

Authentication

All API endpoints (except health checks) require authentication via API key:

curl -H "X-API-Key: your-api-key" http://localhost:3456/api/...

POST /api/run-coder

Execute Claude Code with a prompt.

Request:

{
  "prompt": "Create a hello world function",
  "priority": 5,
  "timeout": 300000
}

Response (200 - Started):

{
  "pid": 12345,
  "tempFile": "/tmp/skilliks-agent/skilliks-123456-abc.txt"
}

Response (202 - Queued):

{
  "queuePosition": 3,
  "estimatedStartTime": "2024-01-01T12:00:00Z"
}

GET /api/prompt-status

Check the status of a running or completed prompt.

Query Parameters:

• pid - Process ID
• tempFile - Temporary file path

Response:

{
  "status": "running|completed|failed|queued|killed",
  "pid": 12345,
  "tempFile": "/tmp/skilliks-agent/skilliks-123456-abc.txt",
  "startTime": "2024-01-01T12:00:00Z",
  "endTime": "2024-01-01T12:05:00Z",
  "exitCode": 0,
  "output": "...",
  "error": "..."
}

POST /api/kill

Terminate a running process.

Request:

{
  "pid": 12345
}

Response:

{
  "success": true,
  "pid": 12345,
  "message": "Process killed successfully"
}

POST /api/reset

Reset the system, clearing all processes and temporary files.

Response:

{
  "filesRemoved": 10,
  "processesKilled": 2,
  "queueCleared": true
}

POST /api/queue

Add a prompt to the execution queue.

Request:

{
  "prompt": "Create a REST API",
  "priority": 8,
  "runAfterPid": 12345
}

Response:

{
  "queueId": "uuid-here",
  "position": 2,
  "estimatedStartTime": "2024-01-01T12:10:00Z"
}

GET /api/queue/status

Get current queue status.

Response:

{
  "running": 2,
  "queued": 5,
  "items": [
    {
      "queueId": "uuid-here",
      "prompt": "Create a REST API...",
      "priority": 8,
      "position": 1,
      "estimatedStartTime": "2024-01-01T12:10:00Z"
    }
  ]
}

GET /health

Health check endpoint (no authentication required).

Response:

{
  "status": "healthy|degraded|unhealthy",
  "uptime": 3600000,
  "processes": {
    "running": 2,
    "queued": 3,
    "maxConcurrent": 3
  },
  "memory": {
    "used": 104857600,
    "total": 209715200,
    "percentage": 50
  },
  "timestamp": "2024-01-01T12:00:00Z"
}

Development

Building from Source

# Clone repository
git clone https://github.com/skilliks/skilliks-agent.git
cd skilliks-agent

# Install dependencies
npm install

# Build TypeScript
npm run build

# Run in development mode
npm run dev

Running Tests

npm test
npm run test:coverage

Project Structure

skilliks-agent/
├── src/
│   ├── api/           # API routes and middleware
│   ├── core/          # Core business logic
│   ├── config/        # Configuration management
│   ├── utils/         # Utilities and helpers
│   ├── types/         # TypeScript type definitions
│   ├── index.ts       # Server entry point
│   └── cli.ts         # CLI entry point
├── tests/             # Test files
├── dist/              # Compiled JavaScript
└── docs/              # Documentation

Security Considerations

1. API Key: Always use a strong, unique API key in production
2. HTTPS: Use a reverse proxy (nginx, caddy) for SSL/TLS in production
3. Firewall: Restrict access to the API port
4. Rate Limiting: Adjust rate limits based on your needs
5. Process Isolation: Runs processes with user permissions

Troubleshooting

Server won't start

• Check if port is already in use
• Verify configuration file syntax
• Check log files for errors

Claude Code not executing

• Ensure ccode command is available in PATH
• Check process timeout settings
• Verify sufficient system resources

Queue not processing

• Check max concurrent process limit
• Monitor system resources
• Review logs for errors

License

MIT

Contributing

Contributions are welcome! Please submit pull requests or issues on GitHub.

Support

For issues and questions, please visit: https://github.com/skilliks/skilliks-agent/issues