> ## Documentation Index
> Fetch the complete documentation index at: https://docs.beta.b3os.org/llms.txt
> Use this file to discover all available pages before exploring further.

# Actions and triggers

An open marketplace of signed packs whose actions any agent can search, describe and call, with credentials injected at the egress proxy instead of passed in.

Actions are the integrations your agent can call: open a GitHub issue, query Linear, read a Stripe invoice. They come in **packs**. A pack is a signed, versioned bundle of actions and triggers for one service, named `<namespace>/<name>` such as `io.b3os/github`. One action is one operation, called by reference:

```text
io.b3os/github/create-issue@1.2.0
```

Every action is also a valid MCP tool, with its input schema, output schema and an effect class.

## Search, describe, call

An agent needs three calls to use an action it has never seen:

1. **Search** with words: `GET /v1/actions/search?q=create a github issue` returns references ranked for agents.
2. **Describe** a reference: `GET /v1/actions/describe?ref=io.b3os/github/create-issue@1` returns its input and output schemas, its effect class and the connections it needs. A major version like `@1` resolves to the newest matching release.
3. **Call** it: `POST /v1/actions/call` validates the input, runs the action, validates the output and returns it.

[Calling actions](/actions/call) walks through all three. Over MCP the same flow is three tools, `actions_search`, `actions_describe` and `actions_call`, so the whole catalog never crowds the tool list.

## Credentials stay out of reach

An action that talks to a service needs your credential for it, stored as a [vault connection](/vault). You never pass the secret in a call. The action's request leaves through the egress proxy on the node, which adds the credential there, and only for the hosts the pack declares. The action's code, your agent, the model and the logs never see it.

## How actions run

| Kind | Runs | Used for |
|---|---|---|
| Declarative HTTP | Inside the B3OS daemon: a request template, JSON Schema validation and response mapping, compiled when the pack is published | Most API integrations |
| JavaScript | In a separate runtime with no credentials and no B3OS identity; its outbound requests go through the egress proxy with a per-call capability | First-party packs that need code |

Templates and mappings are [CEL](/routines/definitions#expressions) inside `${{ }}`, the same language routines use.

Each action has an **effect class**: `pure` (computes from its input), `read`, `write` or `irreversible`. B3OS retries only `pure` and `read` actions on its own, and MCP clients see matching hints, such as `readOnlyHint` for reads.

## Triggers

Packs can also provide triggers: webhooks from the service, polls with a cursor, or schedules. A routine subscribes to one with a `type: action` trigger, and each event starts a run. See [pack triggers](/actions/triggers).

## The catalog

The v0.1 catalog holds about 25 curated packs whose credential belongs to you (your own API key, token or OAuth token) or that call public APIs without one: generic HTTP and OpenAPI, GitHub, Slack, Linear, Notion, Jira, Discord, S3, read-only Stripe, Google APIs with your own client, read-only Polymarket market data and others. It leaves out packs that would run on keys B3 pays for, route through residential proxies, or sign wallet transactions. `GET /v1/actions/packs` lists what the node serves.

Every pack version carries a content hash and an Ed25519 publisher signature, and the node verifies both against the registry before loading it. In the beta only B3OS publishes packs. See [packs](/actions/packs).

## Billing and scopes

Each call bills one `actions.call`, 300 calls a minute per organization in the beta.

| Scope | For |
|---|---|
| `actions:run` | Call actions |
| `actions:read` | Search and describe actions; list packs, triggers and subscriptions |
| `actions:write` | Publish packs to the registry (first-party publishers only in the beta) |

Naming a connection in a call also needs `vault:run`.

**[Call actions](/actions/call)**

Search, describe and call, with connections.
  **[Pack triggers](/actions/triggers)**

Start routine runs from events in other services.
  **[Packs](/actions/packs)**

What a pack contains and how it is signed.
  **[Limits and FAQ](/actions/limits)**

Caps and common questions.