Daemon API
External integration via HTTP API - Background HTTP daemon for external task queuing and automation integration with Arg0 Desktop.
HTTP daemon API for external integration with Arg0 Desktop.
Overview
The daemon is a background HTTP server that provides external access to agent execution and workflow automation. It runs on port 3999 by default.
Starting the Daemon
From UI
- Navigate to Settings
- Enable daemon
- Configure port (default: 3999)
- Click "Start Daemon"
From CLI
bash
node cli/dist/index.js daemon start
API Endpoints
POST /task
Queue an agent goal for execution.
Request:
bash
curl -X POST http://127.0.0.1:3999/task \
-H "Content-Type: application/json" \
-d '{
"goal": "Analyze the codebase",
"context": "Focus on performance issues"
}'
Request Body:
typescript
{
goal: string // Agent goal
context?: string // Additional context
provider?: string // AI provider (optional)
model?: string // AI model (optional)
timeout?: number // Execution timeout (optional)
}
Response:
json
{
"success": true,
"taskId": "task-123",
"status": "queued"
}
GET /task/:id
Get task status.
Request:
bash
curl http://127.0.0.1:3999/task/task-123
Response:
json
{
"taskId": "task-123",
"status": "executing",
"progress": 50,
"steps": [
{
"type": "thought",
"content": "Analyzing codebase..."
}
]
}
DELETE /task/:id
Cancel a running task.
Request:
bash
curl -X DELETE http://127.0.0.1:3999/task/task-123
Response:
json
{
"success": true,
"status": "cancelled"
}
GET /status
Health check endpoint.
Request:
bash
curl http://127.0.0.1:3999/status
Response:
json
{
"running": true,
"version": "1.0.0",
"port": 3999,
"uptime": 3600
}
GET /
Landing page with daemon information.
Request:
bash
curl http://127.0.0.1:3999/
Response:
html
<!DOCTYPE html>
<html>
<head><title>Arg0 Desktop Daemon</title></head>
<body>
<h1>Arg0 Desktop Daemon</h1>
<p>Status: Running</p>
<p>Port: 3999</p>
</body>
</html>
Task Status
Status Values
- queued: Task is queued for execution
- executing: Task is currently running
- completed: Task finished successfully
- failed: Task encountered an error
- cancelled: Task was cancelled
Progress Tracking
Tasks report progress percentage (0-100):
json
{
"progress": 75,
"currentStep": "Executing tool",
"totalSteps": 10,
"completedSteps": 7
}
CORS Configuration
The daemon enables CORS for local development:
text
Access-Control-Allow-Origin: *
Access-Control-Allow-Methods: GET, POST, DELETE, OPTIONS
Access-Control-Allow-Headers: Content-Type, Authorization
Authentication
API Key Authentication (Optional)
Configure API key in Settings:
bash
curl -X POST http://127.0.0.1:3999/task \
-H "Content-Type: application/json" \
-H "Authorization: Bearer your-api-key" \
-d '{"goal": "Test"}'
Error Responses
Error Format
json
{
"error": {
"code": "INVALID_REQUEST",
"message": "Invalid request parameters",
"details": "Goal is required"
}
}
Error Codes
INVALID_REQUEST: Invalid request parametersTASK_NOT_FOUND: Task ID not foundDAEMON_BUSY: Daemon is at capacityAUTHENTICATION_FAILED: Invalid API keyINTERNAL_ERROR: Internal server error
Webhook Integration
Webhook Callbacks
Configure webhook URL for task completion:
typescript
{
goal: "Analyze code",
webhook: "https://your-server.com/callback"
}
Webhook Payload:
json
{
"taskId": "task-123",
"status": "completed",
"result": {
"final": "Analysis complete"
}
}
Rate Limiting
Default Limits
- 100 requests per minute
- 10 concurrent tasks
- 30 second timeout per task
Rate Limit Response
json
{
"error": {
"code": "RATE_LIMIT_EXCEEDED",
"message": "Rate limit exceeded",
"retryAfter": 60
}
}
Best Practices
External Integration
- Use appropriate timeouts
- Handle errors gracefully
- Implement retry logic
- Monitor task status
- Use webhooks for async completion
Security
- Use API keys in production
- Enable HTTPS in production
- Validate input parameters
- Monitor for abuse
- Rotate API keys regularly
Performance
- Queue tasks efficiently
- Use appropriate timeouts
- Monitor daemon resources
- Implement caching
- Optimize task execution
Troubleshooting
Daemon Not Starting
- Check if port 3999 is available
- Verify daemon is enabled in Settings
- Check firewall settings
- Review daemon logs
- Restart application
Connection Refused
- Verify daemon is running
- Check host and port
- Test with curl
- Check firewall
- Review network settings
Task Not Executing
- Check task status
- Verify goal is valid
- Check AI provider configuration
- Review error logs
- Check daemon capacity
Related Documentation
- CLI Usage - CLI commands
- Agent Implementation - Agent system
- Triggers - Webhook triggers