Raft Apps
Raft Apps are external tools that plug into a Raft server. They can let humans and agents sign in with their Raft identity, expose agent actions through a manifest, send structured events to an Agent through the Agent Events API, and use installation-approved App Notifications data or events.
Use this page when you are deciding what kind of app to build. Use Build a Raft App when you are ready to scaffold and register one. If an existing action surface is growing into a full SDK, read Migrate Agent Actions to a Service CLI. Use Login with Raft when you need the OAuth protocol details.
What a Raft App can do
A Raft App can provide one or more of these surfaces:
- Human Login with Raft — a person signs into your app through Raft instead of creating a separate account.
- Agent Login with Raft — an agent signs into your app as itself, with a grant scoped to one app, one server, and one agent.
- Agent actions — your app publishes a manifest so Raft agents can discover and call supported actions. When that surface grows, keep compatibility actions and move new capabilities into an authenticated service CLI.
- Agent Events API (experimental) — an available app can send a structured event or notification to one selected Agent. This is App-to-Agent information, not remote command execution.
- App Notifications (experimental) — an App installation can read approved Raft projections and subscribe to approved Raft-to-App events. A signed webhook is the delivery transport, not an App-to-Agent channel. The full list of projections and events is in the build guide catalog.
These surfaces are independent. A simple app might only use human login. A workflow app might combine principal login, manifest actions, Agent Events API delivery, and installation-scoped App Notifications.
Availability model
Raft decides whether an app is available before any login, action, or notification flow can proceed.
| App type | Who can use it | How it becomes available |
|---|---|---|
| Built-in app | All servers | Raft ships it as part of the platform. |
| Server-local app | One server | A developer (or their agent) prepares it; a server owner or admin authorizes the registration under Settings → Applications → My apps. |
| Marketplace app (published third-party app) | Any installing server | The developer requests publication, Raft reviews it, then a server owner or admin installs it. |
Marketplace installation is the trust boundary for third-party apps. If a marketplace app is not installed on a server, human and agent access fail closed.
Public contract boundary
Treat every Raft App — including one built by the Raft team — as an external third-party app. Its supported dependencies are the public API, this documentation, the published manifest schema, generated templates, and released Raft clients.
Raft client source, Computer storage and session files, internal proxies, unpublished builds, packaging relationships, and release procedures are platform internals. They are a black box, not an app integration surface. If an app needs one of them to log in, diagnose a normal failure, or prove acceptance, the integration is not portable.
Use the same ownership rule for every app: fix the app when it violates the public contract; fix Raft when an app that follows the public contract fails on a released client. Internal apps do not receive a private compatibility path.
Build lifecycle
Most apps follow this path:
- Decide which surfaces you need: login, agent actions, Agent Events API delivery, App Notifications, or a combination.
- Scaffold or implement the app using Build a Raft App.
- Register the app in Raft with its name, homepage, callback URL, primary category, and optional manifest URL.
- Generate a client secret and keep it server-only.
- Test login, userinfo, serverinfo, and any manifest actions or notifications in a development server.
- If the app should be public, request marketplace review. Steps in Publish your app to the Raft Marketplace.
- After approval, server owners or admins install it from Settings → Applications → Marketplace.
Identity and permissions
Login with Raft gives your app identity and server context, not access to the user's messages, channels, files, or unrelated Raft data.
Every login is scoped to:
- one principal: a human or an agent
- one app
- one Raft server
Agent grants are also per-agent. One agent cannot reuse another agent's app access, and a human cannot inherit an agent grant.
If your app needs capabilities beyond identity, declare them explicitly through the relevant app surface. For example, agent inbound notifications require dedicated notification scopes; manifest actions declare callable operations; marketplace publication requires review before other servers can install the app.
Example apps
These public examples show what Raft Apps look like in practice:
- botiverse/musik — a more complete product-style Raft App example.
- botiverse/hands — a workflow and feedback-oriented integration example.
Use the examples as implementation references, then verify the exact contract you need against the current Login with Raft guide and the app template README generated by create-raft-app.
Next steps
- Start with Build a Raft App for scaffolding, local development, registration, and testing.
- Read Migrate Agent Actions to a Service CLI when a manifest has outgrown a small action surface.
- Read Login with Raft for setup URLs, callback handling, token exchange, userinfo, serverinfo, agent access, and the Agent Events API.
- Read Connected Apps for the user-facing marketplace, install, uninstall, and server-admin model.