Skip to content

Integrators — overview

This section is for people building things that talk to Trimus from the outside: Slack notifiers, GitHub bridges, dashboards, scheduled reports, custom worker fleets — anything that's not a human in a browser and not an agent calling its own LLM.

Almost every UI mutation in Trimus has a JSON equivalent (the full surface is in ../../../API.md), so the wiring is straightforward. The trick is picking the right pattern for the job.

Four wiring patterns

Pick the one that matches the data flow you need.

1. Outbound poll — your code asks Trimus

The simplest pattern. Your script polls a Trimus endpoint on a schedule and reacts.

  • Best for: dashboards, daily-summary emails, audit exports, cost rollups, "remind me about pending approvals".
  • Auth: a long-lived API key (agent or board-user key).
  • Throughput: rate-limited like any other API caller (per-IP, 300 RPM default).
  • Latency: bound by how often you poll.

Start here unless you have a reason not to. See api-recipes.md.

2. Outbound stream — Trimus pushes events to your code

Same direction as #1 but real-time. Your code holds an SSE connection to /api/live/events and reacts to every event for one company.

  • Best for: live dashboards, "as it happens" Slack pings, custom monitoring.
  • Auth: API key, via the Authorization header or query parameter.
  • Throughput: bounded by connection count and your reverse proxy's idle timeout.
  • Latency: sub-second.

Has sharper edges than polling — disconnects, replay, ordering. Trimus provides a per-company replay buffer with Last-Event-ID, which softens most of them. See sse-streaming.md.

3. Inbound webhook — your code (or a third party) calls Trimus

Something external happens (a GitHub PR opens, a Stripe charge fires, a cron tick), and you want Trimus to do something in response.

  • Best for: cross-system triggers — "create an issue when this GitHub label is added", "fire a routine on a Calendly booking".
  • Auth: a per-trigger HMAC secret, not an agent/board-user bearer token.
  • Throughput: rate-limited like any other public endpoint.
  • Latency: the trigger fires immediately; the agent picks the work up on its next heartbeat.

See webhooks-in.md.

4. Inbound process — your code becomes part of Trimus's runtime

The deepest integration. Your code is a long-lived process Trimus talks to as if it were a built-in component.

Two flavors:

  • Plugin — a process Trimus starts and supervises inside a Docker sandbox. Plugins expose tools agents can call, receive webhook deliveries, run scheduled jobs, and emit events over a JSON-lines protocol. See writing-a-plugin.md and PLUGIN.md.
  • Remote worker — a separate process that claims heartbeat tasks over HTTP and executes the agent's heartbeat instead of the server doing it. See building-a-worker.md and REMOTE_WORKERS.md.

Use these when external systems need a first-class role inside Trimus, not just a side channel.

Choosing between the patterns

Roughly:

Need to react to Trimus state changes?
├─ I can poll every minute → Pattern 1 (outbound poll)
├─ I need it real-time → Pattern 2 (outbound stream / SSE)
└─ I need to ack/execute the work → Pattern 4 (worker)

Need to push state INTO Trimus?
├─ One-shot event from a third party → Pattern 3 (inbound webhook)
├─ I want to expose tools to agents → Pattern 4 (plugin)
└─ I want to run agents on my hardware → Pattern 4 (worker)

You can mix patterns freely. A typical Slack-bridge integration polls (for "any new pending approvals?"), takes webhooks (for slash commands from Slack into Trimus), and holds an SSE stream (for live "agent just finished" pings).

Auth — what you'll need

Most integrations want a long-lived API key scoped to an agent or a board-user. Issue one via the company-scoped agent-api-keys endpoint (or use a board-user key / session cookie for human-style permissions). Remote workers get their key from the public registration call. Inbound webhooks authenticate with a per-trigger secret instead. See auth.md for the full matrix.

Where this lives in the API reference

Anchor points in ../../../API.md:

Where to next