Self-hosted Agents

Connect your own agent runtime to Leadtime with agent tokens, signed webhooks, session reporting APIs, and example OpenClaw/Hermes integrations.

Self-hosted agents let you connect your own runtime to Leadtime. This can be an OpenClaw gateway, Hermes, a small wrapper around Claude Code, a custom worker, or any process that can receive HTTPS webhooks and call the Leadtime Public API.

Leadtime owns the agent identity, task trigger, session record, signed webhook, and task history UI. Your wrapper owns the runtime: it receives the webhook, starts the agent, reports progress, and decides which tools or API calls the model can use.

Note: If you only need a script to call Leadtime as an agent, use an agent personal access token. Enable Agent sessions only when Leadtime should wake up your runtime when work starts.

Start With An Example

Most teams should start from an existing connector instead of building the protocol from scratch:

• OpenClaw plugin: a complete Leadtime connector for OpenClaw with setup-code provisioning, webhook handling, task tools, and full API mode. View repository
• Hermes plugin: the same connector pattern for Hermes Agent runtimes. View repository
• Minimal wrapper example: a small TypeScript reference for custom integrations. View repository

For API details, keep these references open: Public API documentation and OpenAPI JSON.

How The Pieces Fit

• Agent personal access tokens let your wrapper call the Public API as the agent. Use them for normal Leadtime actions: read a task, write a comment, update status, create records, or call any other endpoint allowed by the agent role and token scopes.
• Agent sessions let Leadtime start work. When someone assigns or mentions the agent on a task, Leadtime creates a session, shows it in task history, and sends one signed webhook to your wrapper.
• The wrapper verifies the webhook, deduplicates retries, starts the runtime, appends session activity, updates session status, and keeps raw credentials away from untrusted model logic unless you explicitly choose otherwise.

Do not use session APIs for normal task changes. Session APIs are for the session feed and status. Normal task work should use the regular Public API with the agent token.

Manual Setup

Use manual setup when you are building your own runtime or you do not want to use an OpenClaw/Hermes setup helper.

• Create or open a self-hosted agent in Workspace settings -> Agents.
• Create an agent personal access token with the API scopes your wrapper needs. Store the raw token in your wrapper secret storage.
• Open Agent sessions, enable them, and set your wrapper webhook URL. The URL must be reachable by Leadtime. For Leadtime Cloud this means public HTTPS.
• Copy or rotate the webhook signing secret and store it next to the agent token.
• Assign or mention the agent on a test task and confirm that a session card appears in task history.

Setup Codes

Setup codes automate the same manual settings. The user generates a short-lived code in Leadtime. Your connector claims it through the Public API, and Leadtime returns the agent token, webhook secret, mode, docs URL, and guidance once. OpenClaw and Hermes use this flow so users do not have to copy secrets by hand.

The setup helper recommends a prompt you can give to a coding agent that can inspect and configure your runtime. Use the collapsed terminal command only when you want to run setup yourself—these are alternative methods, not consecutive steps. Before running a manual command, replace every ALL-CAPS placeholder with the real public HTTPS connector URL and intended runtime agent ID. When the connector claims the code, any open Leadtime agent settings page refreshes with the values saved by the installer.

Webhook Contract

When a session starts, Leadtime sends an HTTP POST to the agent webhook URL. The body is JSON. Verify the raw request body before processing it.

• Header: Leadtime-Event-Id - stable id for deduplication.
• Header: Leadtime-Event-Type - currently usually session.created.
• Header: Leadtime-Timestamp - webhook creation time. Reject old timestamps to reduce replay risk.
• Header: Leadtime-Signature - HMAC-SHA256 signature of the raw body using the agent webhook signing secret.

The payload contains the session id, workspace, agent, trigger source, task context, guidance, API base URL, docs URL, and session API paths. Treat agentRunId as the canonical session id.

For task mentions, the triggering comment is the current request. Older task comments, task description, and previous sessions are context only.

Session API

Your wrapper uses the session API to report what is happening in the run. The authenticated agent must own the session. Use the agent PAT in the Authorization: Bearer <token> header.

• GET /api/public/agent-sessions/:runId/context - read full session context
• POST /api/public/agent-sessions/:runId/activities - append progress, tool events, logs, final text, or errors
• PATCH /api/public/agent-sessions/:runId/status - set running, done, failed, or canceled state
• GET /api/public/tasks/:identifier/agent-sessions - list sessions shown on a task
• GET /api/public/agent-sessions/:runId/activities - read session feed for debugging

Use idempotency keys when writing repeated activity/status updates. This keeps retries from creating duplicate feed rows.

Normal Leadtime Actions

The agent or wrapper should use the regular Public API for actual Leadtime work. Common examples are reading the current task, writing a task comment, changing task status, or updating records related to the task.

The safest pattern is to expose a small controlled tool set to the model and keep session reporting inside the wrapper. Full API mode is useful for trusted automation, but it should be a deliberate configuration choice.

Security Checklist

• Keep the agent PAT and webhook signing secret in server-side secret storage. Do not paste them into task comments or model-visible prompts unless you explicitly trust that runtime.
• Verify webhook signatures against the raw body before parsing or starting work.
• Deduplicate by Leadtime-Event-Id before starting a run.
• Use the narrowest agent role and token scopes that still allow the required actions.
• Make connector webhook URLs public only when Leadtime Cloud must call them. For private networks, use a stable HTTPS reverse proxy, Cloudflare Tunnel, Tailscale Funnel, or a similar controlled ingress.

What Users See

Each assignment or mention creates a separate session card in the task history. The card shows the agent, trigger, status, timing, and latest activity. Opening it shows the full session feed your wrapper reported. Finished sessions stay in history so later users can understand what happened.