AgenTrux Plugins

Status: Experimental — APIs may change in future releases.

AgenTrux plugins let you connect external platforms to AgenTrux. Each plugin signs in to AgenTrux, sends events, and reads events for that platform.

New here? Follow the Setup Guide below first.

Available Plugins

How Authentication Works

There are two patterns. Pick one based on whether your plugin runs in a place a user can open a browser.

Pattern A — OAuth 2.1 browser flow (recommended for interactive clients)

The MCP server and any OAuth-aware client (Claude Desktop, Cursor, Cline, …) follow the standard OAuth 2.1 authorization_code + PKCE loopback flow. There is no copy-paste: the user clicks Allow on a consent screen once and the plugin gets a JWT.

[client, once]
  POST /oauth/register                                      → client_id
[user, once per session]
  open browser to /oauth/authorize?...&code_challenge=<pkce_hash>
  → Console consent UI (Script picker + scope checkboxes)
  → Allow → loopback redirect with ?code=...
[client, per session]
  POST /oauth/token   grant_type=authorization_code         → access_token (JWT) + refresh_token
[client, per call]
  Authorization: Bearer <JWT>

See MCP Server doc for the full flow + Claude Desktop / Cursor config examples.

Pattern B — Activation code (plugin / SDK)

The Agent SDK and the OpenClaw plugin use the single-use Activation Code flow (no public OAuth callback required).

Step 1: Redeem (one-time)
  Activation Code (act_) → POST /auth/redeem-activation-code → client_id (crd_) + client_secret (aks_)

Step 2: Get a token
  client_id + client_secret → POST /oauth/token (grant_type=client_credentials) → JWT aat_ (~10 min)

Step 3: Use the token
  aat_ → Authorization: Bearer header → call any API endpoint

Token renewal: client_credentials does not issue a refresh token. When the aat_ is about to expire the plugin simply calls POST /oauth/token again with the saved client_id (crd_) and client_secret (aks_).

Credential Reference

Note (Phase Z, 2026-05-22): Anonymous inv_ invite codes were removed. Cross-account access is now established through Console (Aliases → Share trust + Grants → Create) — see "Cross-Account Access" below.

Setup Guide {#setup-guide}

Before using any plugin, you need to create resources in the AgenTrux Console and get an activation code.

Step 1: Create resources in the Console

Sign in at console.agentrux.com and follow these steps:

1-1. Create a Alias

A Alias is the top-level container for your project. Topics, Scripts, and Grants belong to it.

Console → Aliases → "+ New Alias"
  Display Name: my-project
  → Create

1-2. Create a Topic

A Topic is a message channel owned by a Alias. Events stay in the Topic for a set time, then AgenTrux deletes them automatically.

Console → Topics → "+ New Topic"
  Alias: my-project
  Name: sensor-data
  Retention: 24h
  → Create

1-3. Create a Script

A Script is your agent's identity — one Script per agent. It belongs to a Alias.

Console → Scripts → "+ New Script"
  Alias: my-project
  Name: temperature-sensor
  → Create

1-4. Add a Grant

A Grant is a permission rule. It decides whether a Script can read from a Topic, write to it, or both.

Console → Grants → "+ New Grant"
  Script: temperature-sensor
  Topic: sensor-data
  Action: write
  → Create

If the Script also needs to read, create a second Grant with Action: read.

1-5. Issue an Activation Code

An Activation Code is a one-time key that activates a Script and gives it permanent credentials.

Console → Scripts → temperature-sensor → "Issue Activation Code"
  Expires in: 24h
  → Issue

Copy the act_... code and give it to your agent.

The code can only be used once. After redemption, it becomes invalid. You can issue a new one any time.

Step 2: Connect your agent

2-1. Redeem the Activation Code (one-time)

POST /auth/redeem-activation-code
Body: { "code": "act_..." }

Response:
{
  "client_id": "crd_e5f6a7b8-...",
  "client_secret": "aks_xxxxxxxx...",
  "script_id": "scr_...",
  "issued_at": "2026-04-08T12:00:00"
}

Save client_id (crd_) and client_secret (aks_) securely. You will need them every time your agent starts. aks_ is shown only once.

2-2. Get an access token

POST /oauth/token   (application/x-www-form-urlencoded)
Body: grant_type=client_credentials&client_id=crd_e5f6a7b8-...&client_secret=aks_xxx...

Response:
{
  "access_token": "aat_eyJhbGciOi...",
  "token_type": "Bearer",
  "expires_in": 600
}

2-3. Publish and read events

# Publish an event
POST /topics/{topic_id}/events
Body: { "event_type": "sensor.reading", "payload": { "temperature": 22.5 } }

Response: { "event_id": "evt_...", "topic_id": "top_...", "payload_kind": "inline", "next_read_cursor": "..." }

# Read events
GET /topics/{topic_id}/events?limit=10

Response: { "events": [...], "next": { "after": "..." } }

Topic & Grant Discovery (for workflow plugins)

Workflow plugins (MCP, Agent SDK, OpenClaw, etc.) populate their topic selectors by calling GET /topics with the script's JWT. The response lists every topic the script can read or write, with human-readable names:

GET /topics
Authorization: Bearer <JWT>

{
  "items": [
    {
      "topic_id": "019d5ec8-...",
      "name": "oc-command",
      "display_name": "OpenClaw Command",
      "retention_seconds": 86400,
      "actions": ["read", "write"]
    },
    ...
  ]
}

For an admin or diagnostic UI that needs the grant detail behind those permissions — who issued them, the per-grant rate limit, the description, when they were created — call GET /grants:

GET /grants
Authorization: Bearer <JWT>

{
  "items": [
    {
      "grant_id": "aaaaaaaa-...",
      "topic_id": "019d5ec8-...",
      "topic_name": "oc-command",
      "topic_display_name": "OpenClaw Command",
      "action": "read",
      "grantor_alias_id": "...",
      "description": "OpenClaw command bus",
      "rate_limit_per_min": 60,
      "daily_limit": 10000,
      "created_at": "2026-04-08T..."
    },
    ...
  ]
}

Both endpoints are built from the JWT scope claim — no extra round trip, no Console auth required. Deleted topics and grants are omitted automatically so an out-of-date entry cannot break the UI. A plugin that only needs UUIDs can equivalently decode topic:<id>:<action> entries directly out of the JWT scope, but for any UI that shows the topic to the end user, prefer GET /topics (and GET /grants for admin views) so users see names instead of UUIDs.

Cross-Account Access (Phase Z, 2026-05-22)

To grant another registered user's agent access to your Topic, both sides operate from their own Console session. Anonymous invite codes have been removed; the partner must already have an AgenTrux account.

Owner side

Console → Aliases → your alias → "Share trust"
  Grantee email: partner@example.com
  → a trust relationship (you → partner) is established immediately

Partner side

Console → Grants → "+ Create"
  Topic: top_<your topic>
  Script: scr_<partner's own script>
  Action: read
  → Grant is created (grantor = your alias, grantee = partner's alias)

The partner's plugin will see the new scope after the next /oauth/token call.

License

MIT