Agent Native

rstream exposes discovery, authentication, API, CLI, and workflow metadata so agents can understand the product before acting on behalf of a user. The goal is not only to make rstream crawlable, but to give automation clients enough structured context to obtain user-approved access, choose the right permissions, operate tunnels, and stop when a task requires explicit confirmation.

The agent-native surface is built from several independent contracts. Discovery documents advertise where the APIs and skills live. OAuth metadata describes how an agent obtains a bearer token. OpenAPI contracts describe the hosted control plane and engine data plane. Agent Skills provide task-level instructions for setup, APIs, CLI usage, tunnels, WebTTY, and troubleshooting. Markdown negotiation makes public documentation easier to read in compact form.

Discovery entrypoints

Agents can start from the site root and follow HTTP Link headers, or they can request the well-known documents directly.

curl -I https://rstream.io/
curl https://rstream.io/.well-known/api-catalog
curl https://rstream.io/.well-known/oauth-protected-resource
curl https://rstream.io/.well-known/oauth-authorization-server
curl https://rstream.io/.well-known/agent-skills/index.json
curl https://rstream.io/.well-known/mcp/server-card.json

The API catalog is the main API discovery document. It advertises the hosted OpenAPI contract at /api/openapi.json, the engine OpenAPI contract at /api/engine/openapi.json, API documentation, and the status endpoint. OAuth protected resource metadata describes the rstream resource identifier, authorization servers, and supported scopes. The authorization server metadata describes Device Authorization Grant endpoints, the token endpoint, revocation endpoint, JWKS location, and grant support.

Public documentation pages also support Markdown negotiation. Requests with Accept: text/markdown return a Markdown version of supported public pages while browsers continue to receive HTML by default.

Authentication

Agents authenticate with OAuth 2.0 Device Authorization Grant. The flow is designed for public clients that cannot safely hold a client secret. The agent requests scopes, receives a device authorization response, directs the user to the verification URL, polls the token endpoint, and receives a bearer token after the user approves the request.

The CLI uses the same direction of travel. rstream login defaults to OAuth Device Authorization Grant, while the legacy rstream login flow remains available for compatibility checks. For machine workflows, project-scoped credentials or environment variables can still be used when an account-wide login is not appropriate.

API contracts

The hosted control-plane API and the engine data-plane API are intentionally separate.

The hosted OpenAPI contract at /api/openapi.json covers automation-facing managed platform operations. This includes whoami, project listing, project creation options, project creation, project endpoint resolution, hosted logs, TURN credential issuance, and token or credential operations that are appropriate for automation.

The engine OpenAPI contract at /api/engine/openapi.json covers project-scoped runtime operations. This includes listing clients, listing tunnels, watching SSE events, and connecting to the WebSocket event stream.

OpenAPI operations expose x-rstream-required-rules. The same contracts expose x-rstream-permissions, which maps OAuth permissions to the rules they grant, and x-rstream-use-case-permissions, which gives practical bundles for common workflows. Agents should prefer those bundles for product-level tasks, then refine from operation rules when a workflow is narrower.

Skills and workflows

Agent Skills are served from /.well-known/agent-skills. The index exposes each skill name, type, description, URL, and SHA-256 digest. The skills are source-controlled Markdown files, which keeps the workflow instructions close to the product docs and avoids hardcoded TypeScript copies.

The main entrypoint is rstream-setup. It covers discovery, OAuth access, workspace and project selection, project creation, CLI installation, context setup, and readiness checks. More focused skills cover the hosted API, CLI commands, tunnels, WebTTY, and troubleshooting.

Typical agent workflows include:

• install the rstream CLI, authenticate with OAuth, select an existing project, and open a published HTTP tunnel;
• inspect project creation options, present billing impact, create a project with an idempotency key, then configure local CLI access;
• start a published WebTTY server on a machine so it appears in the dashboard and can be reached through token-protected browser sessions;
• list tunnels and clients through the engine API or CLI, then use hosted logs and troubleshooting docs when traffic does not route.

Safety model

Agent workflows should distinguish discovery from mutation. Reading metadata, loading skills, listing projects, inspecting plan options, or checking local CLI state can happen without extra confirmation when the user asked for setup or diagnosis. Paid project creation, public service exposure, destructive deletes, credential rotation, long-lived credential creation, and security policy downgrades require explicit user confirmation.

Project creation is designed for that model. The plan configuration endpoint returns plan availability, recommended region, billing impact, the next server-selected billing action, and a creationFingerprint. Agents do not choose a billing mode. If billingAction.type is stripe_checkout, the agent starts checkout with the selected fingerprint and a stable idempotencyKey, sends the user to Stripe, then completes or cancels the reserved project from the Stripe return parameters. If billingAction.type is none or confirm_create, the agent uses the project creation endpoint. If billing or capacity state changes before creation, the API rejects the stale preview and the agent must refresh the options before asking for confirmation again.

MCP and browser context

rstream publishes an MCP Server Card and a minimal MCP endpoint for discovery. Product-changing MCP tools are intentionally not part of the current contract; stable product automation should use OAuth, OpenAPI, and the documented APIs until the action model is ready for broader MCP exposure.

Compatible browsers can also receive WebMCP context through navigator.modelContext. This exposes page-level context and discovery helpers when the browser supports the WebMCP API, while keeping standard browser HTML behavior unchanged.

Related documentation

The surrounding implementation details are split across focused pages:

• APIs covers the hosted and engine API split.
• CLI Workflow covers contexts, project selection, environment variables, and readiness checks.
• Commands lists automation-friendly CLI output modes.
• Troubleshooting covers rstream doctor and common runtime failures.
• Fine-Grained Tokens covers token grants and scope reduction.