API server for remote Claude Code execution
npm install skilliks-agentAPI server for remote Claude Code execution with queue management and process control.
- 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
``bash`
npm install -g skilliks-agent
`bash`
npm install skilliks-agent
1. Initialize configuration:
`bash`
skilliks-agent init
This creates a config file at ~/.skilliks-agent.json with a generated API key.
2. Start the server:
`bash`
skilliks-agent start
Or with custom options:
`bash`
skilliks-agent start --port 3456 --api-key your-secure-key
3. Check server status:
`bash`
skilliks-agent status
`bash`
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
Create ~/.skilliks-agent.json:
`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"
}
All API endpoints (except health checks) require authentication via API key:
`bash`
curl -H "X-API-Key: your-api-key" http://localhost:3456/api/...
Execute Claude Code with a prompt.
Request:
`json`
{
"prompt": "Create a hello world function",
"priority": 5,
"timeout": 300000
}
Response (200 - Started):
`json`
{
"pid": 12345,
"tempFile": "/tmp/skilliks-agent/skilliks-123456-abc.txt"
}
Response (202 - Queued):
`json`
{
"queuePosition": 3,
"estimatedStartTime": "2024-01-01T12:00:00Z"
}
Check the status of a running or completed prompt.
Query Parameters:
- pid - Process IDtempFile
- - Temporary file path
Response:
`json`
{
"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": "..."
}
Terminate a running process.
Request:
`json`
{
"pid": 12345
}
Response:
`json`
{
"success": true,
"pid": 12345,
"message": "Process killed successfully"
}
Reset the system, clearing all processes and temporary files.
Response:
`json`
{
"filesRemoved": 10,
"processesKilled": 2,
"queueCleared": true
}
Add a prompt to the execution queue.
Request:
`json`
{
"prompt": "Create a REST API",
"priority": 8,
"runAfterPid": 12345
}
Response:
`json`
{
"queueId": "uuid-here",
"position": 2,
"estimatedStartTime": "2024-01-01T12:10:00Z"
}
Get current queue status.
Response:
`json`
{
"running": 2,
"queued": 5,
"items": [
{
"queueId": "uuid-here",
"prompt": "Create a REST API...",
"priority": 8,
"position": 1,
"estimatedStartTime": "2024-01-01T12:10:00Z"
}
]
}
Health check endpoint (no authentication required).
Response:
`json`
{
"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"
}
`bashClone repository
git clone https://github.com/skilliks/skilliks-agent.git
cd skilliks-agent
$3
bash
npm test
npm run test:coverage
`$3
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
$3
- Check if port is already in use
- Verify configuration file syntax
- Check log files for errors
$3
- Ensure
- Check max concurrent process limit
- Monitor system resources
- Review logs for errors
MIT
Contributions are welcome! Please submit pull requests or issues on GitHub.
For issues and questions, please visit: https://github.com/skilliks/skilliks-agent/issues