Arg0/Docs

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

  1. Navigate to Settings
  2. Enable daemon
  3. Configure port (default: 3999)
  4. 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 parameters
  • TASK_NOT_FOUND: Task ID not found
  • DAEMON_BUSY: Daemon is at capacity
  • AUTHENTICATION_FAILED: Invalid API key
  • INTERNAL_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

  1. Check if port 3999 is available
  2. Verify daemon is enabled in Settings
  3. Check firewall settings
  4. Review daemon logs
  5. Restart application

Connection Refused

  1. Verify daemon is running
  2. Check host and port
  3. Test with curl
  4. Check firewall
  5. Review network settings

Task Not Executing

  1. Check task status
  2. Verify goal is valid
  3. Check AI provider configuration
  4. Review error logs
  5. Check daemon capacity