AgentUse: Open-source agent runtime

Run agents on-demand via HTTP webhooks using agentuse serve. Integrate with external services, CI/CD pipelines, or any system that can make HTTP requests.

Quick Start

Start the daemon:

agentuse serve

Trigger an agent via HTTP:

curl -X POST http://127.0.0.1:12233/api/run \
  -H "Content-Type: application/json" \
  -d '{"agent": "assistant.agentuse"}'

Serving Multiple Projects

AgentUse runs one serve daemon at a time. Repeat -C on that daemon to serve multiple project roots:

agentuse serve -C ./projA -C ./projB

Project ids default to directory basenames. Duplicate ids fail startup. Select a project in the request body:

curl -X POST http://127.0.0.1:12233/api/run \
  -H "Content-Type: application/json" \
  -d '{"project": "projA", "agent": "assistant.agentuse"}'

Without project, multi-project requests return 400 PROJECT_REQUIRED unless a default is set:

agentuse serve -C ./projA -C ./projB --default projA

Explicit project fields override the default.

Global config

You can put serve defaults in ~/.agentuse/config.json. See Configuration Files for the schema and CLI override behavior.

Environment isolation

Each project loads its own .env / .env.local in its worker process; env vars never mix across projects.

API Reference

All JSON endpoints live under the /api/* prefix. The root paths (/agents, /sessions, /schedules, /stores, /approvals) serve the HTML dashboard pages instead. The per-session page /sessions/:id and its action subroutes carry their own capability auth (session token / API key / local); see Approval Gates.

POST /run, POST /resume/:id, and the POST /approvals/:id/... action endpoints are also still reachable at their original (un-prefixed) paths for backward compatibility. GET /approvals/:id now redirects to /sessions/:id. Prefer the /api/* and /sessions paths; the legacy aliases will be removed in a future release.

GET /api

Returns version, default project, and served projects. (GET / serves the HTML dashboard built from the same data.)

{
  "version": "0.12.0",
  "default": "projA",
  "projects": [
    { "id": "projA", "path": "/abs/path/to/projA", "agentCount": 3, "scheduleCount": 1 },
    { "id": "projB", "path": "/abs/path/to/projB", "agentCount": 2, "scheduleCount": 0 }
  ]
}

POST /api/run

Execute an agent and receive the result. (Legacy alias: POST /run.) Request:

{
  "agent": "path/to/agent.agentuse",
  "project": "projA",
  "prompt": "Optional additional instructions",
  "model": "anthropic:claude-sonnet-5",
  "timeout": 300,
  "maxSteps": 100
}

Field	Type	Required	Description
`agent`	string	Yes	Path to agent file (relative to that project’s root)
`project`	string	Conditional	Required in multi-project mode unless `--default` is set
`prompt`	string	No	Additional prompt appended to agent instructions
`model`	string	No	Override model in agent file
`timeout`	number	No	Max execution time in seconds (default: 300)
`maxSteps`	number	No	Max tool call steps

Response:

{
  "success": true,
  "result": {
    "text": "Agent response",
    "finishReason": "end-turn",
    "duration": 1234,
    "tokens": { "input": 500, "output": 200 },
    "toolCalls": 3
  }
}

Error Response:

{
  "success": false,
  "error": {
    "code": "AGENT_NOT_FOUND",
    "message": "Agent file not found: my-agent.agentuse"
  }
}

Error Code	HTTP Status	Description
`AGENT_NOT_FOUND`	404	Agent file doesn’t exist
`PROJECT_NOT_FOUND`	404	Unknown project id in multi-project mode
`PROJECT_REQUIRED`	400	Multi-project request without `project` or `--default`
`INVALID_PATH`	400	Path outside project root
`INVALID_REQUEST`	400	Invalid JSON body
`MISSING_FIELD`	400	Required field missing
`TIMEOUT`	504	Execution timed out
`EXECUTION_ERROR`	500	Runtime error

GET /api/agents

Lists the agents the daemon loaded as JSON. path matches what POST /api/run expects. (The browsable HTML page is at /agents.) For one agent’s capability summary and raw source, use GET /api/agents/detail?project=<id>&path=<agent-path>. The path must match an agent already loaded by that project; the browsable detail hub is at /agents/<project>/<agent-path>.

{
  "success": true,
  "agents": [
    { "projectId": "projA", "path": "daily.agentuse", "name": "Daily Digest", "model": "anthropic:claude-sonnet-5", "schedule": "0 9 * * *" }
  ],
  "errors": []
}

GET /api/schedules

Lists scheduled agents as JSON, soonest next run first. (The browsable HTML page is at /schedules.)

{
  "success": true,
  "schedules": [
    { "projectId": "projA", "agentPath": "daily.agentuse", "expression": "0 9 * * *", "human": "Daily 9am", "enabled": true, "nextRun": "2026-06-03T16:00:00.000Z", "lastRun": null }
  ]
}

From the terminal, agentuse serve agents and agentuse serve schedules render these as tables. See CLI Commands.

GET /api/sessions

Lists every run (top-level sessions; subagent sessions are excluded) as JSON, newest first. Filter with ?agent=<id>, ?trigger=scheduled|manual|slack|api, and ?days=<n|all> (default ~7 days). The browsable HTML page is at /sessions.

curl "http://127.0.0.1:12233/api/sessions?trigger=scheduled" \
  -H "Authorization: Bearer $AGENTUSE_API_KEY"

{
  "success": true,
  "sessions": [
    {
      "project": "projA",
      "sessionId": "01JFN8K3M2P1",
      "agent": { "id": "daily", "name": "Daily Digest" },
      "status": "completed",
      "trigger": "scheduled",
      "createdAt": 1717430400000,
      "updatedAt": 1717430412000
    }
  ],
  "window": { "days": 7, "createdAfter": 1716825600000 },
  "errors": []
}

trigger records how the run started: scheduled (the built-in scheduler), api (POST /api/run), slack, or manual (CLI runs and the default).

GET /api/sessions/:id

Returns one session including its run-log entries. API-key gated.

curl "http://127.0.0.1:12233/api/sessions/01JFN8K3M2P1" \
  -H "Authorization: Bearer $AGENTUSE_API_KEY"

For the human-facing view + approve page, the redirect target, and the session token, see Approval Gates.

Streaming Response

For real-time output, request NDJSON streaming:

curl -N -X POST http://127.0.0.1:12233/api/run \
  -H "Content-Type: application/json" \
  -H "Accept: application/x-ndjson" \
  -d '{"agent": "analyzer.agentuse"}'

Each line is a JSON event:

{"type": "text", "text": "Analyzing..."}
{"type": "tool-call", "name": "read_file", "args": {"path": "data.txt"}}
{"type": "tool-result", "name": "read_file", "result": "..."}
{"type": "text", "text": "Complete!"}
{"type": "finish", "finishReason": "end-turn", "duration": 2345}

Authentication

When exposing the server externally, authentication is required:

# Set API key
export AGENTUSE_API_KEY="your-secret-key"

# Start on all interfaces
agentuse serve --host 0.0.0.0

Include the key in requests:

curl -X POST http://server:12233/api/run \
  -H "Authorization: Bearer your-secret-key" \
  -H "Content-Type: application/json" \
  -d '{"agent": "assistant.agentuse"}'

Use --no-auth to bypass authentication (dangerous for production).

Exposing Your Local Server

Tailscale (Private)
Cloudflare Tunnel (Public)

Access from your devices or team only:

brew install tailscale
tailscale up
agentuse serve

Connect via http://<machine-name>:12233 from any device on your tailnet.

Expose to the internet for external webhooks:

brew install cloudflared
agentuse serve
cloudflared tunnel --url http://localhost:12233

Prints a public https://xxx.trycloudflare.com URL with automatic HTTPS.

Integration Examples

GitHub Webhook

Create an agent to handle GitHub events:

---
model: anthropic:claude-sonnet-5
description: Process GitHub webhook events
tools:
  bash:
    commands:
      - "gh *"
      - "git *"
---

Process the incoming GitHub event and take appropriate action.

Configure a GitHub webhook to POST to your server:

URL: https://your-server.com/api/run
Content-Type: application/json
Body: {"agent": "github-handler.agentuse", "prompt": "<webhook payload>"}

Slack Integration

Slack slash commands require a response within 3 seconds and signature verification. Use a workflow tool as middleware: With n8n or Make:

Add Slack trigger node (receives slash commands)
Add HTTP Request node → POST to http://server:12233/api/run
Return agent response to Slack

With Zapier:

Trigger: Slack → New Slash Command
Action: Webhooks → POST to AgentUse /run
Action: Slack → Send Channel Message with result

Direct Slack integration requires handling the 3-second timeout, form-urlencoded parsing, and request signature verification. Workflow tools handle this automatically.

n8n / Make / Zapier

Use HTTP request nodes to trigger agents:

Set URL to http://your-server:12233/api/run
Method: POST
Headers: Content-Type: application/json
Body:

{
  "agent": "workflow-agent.agentuse",
  "prompt": "{{trigger.data}}"
}

Cron Job (External)

Trigger from system cron instead of built-in scheduler:

# /etc/cron.d/agent-tasks
0 * * * * curl -s -X POST http://127.0.0.1:12233/api/run \
  -H "Content-Type: application/json" \
  -d '{"agent": "hourly-task.agentuse"}'

Server Configuration

See CLI Commands - agentuse serve for all server options including port, host, debug mode, and authentication configuration.

Production Deployment

For deploying agentuse serve in production with reverse proxies (nginx), process management (PM2), and Docker, see Self-Hosting.

Getting Started

Building

Running

Reference

Webhooks

Quick Start

Serving Multiple Projects

Global config

Environment isolation

API Reference

GET /api

POST /api/run

GET /api/agents

GET /api/schedules

GET /api/sessions

GET /api/sessions/:id

Streaming Response

Authentication

Exposing Your Local Server

Integration Examples

GitHub Webhook

Slack Integration

n8n / Make / Zapier

Cron Job (External)

Server Configuration

Production Deployment

Next Steps

Scheduled Agents

Self-Hosting

​Quick Start

​Serving Multiple Projects

​Global config

​Environment isolation

​API Reference

​GET /api

​POST /api/run

​GET /api/agents

​GET /api/schedules

​GET /api/sessions

​GET /api/sessions/:id

​Streaming Response

​Authentication

​Exposing Your Local Server

​Integration Examples

​GitHub Webhook

​Slack Integration

​n8n / Make / Zapier

​Cron Job (External)

​Server Configuration

​Production Deployment

​Next Steps

Scheduled Agents

Self-Hosting

Quick Start

Serving Multiple Projects

Global config

Environment isolation

API Reference

GET /api

POST /api/run

GET /api/agents

GET /api/schedules

GET /api/sessions

GET /api/sessions/:id

Streaming Response

Authentication

Exposing Your Local Server

Integration Examples

GitHub Webhook

Slack Integration

n8n / Make / Zapier

Cron Job (External)

Server Configuration

Production Deployment

Next Steps