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 Control plane API and Engine API. 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. If the user does not yet have an account, the browser approval step is where they sign up or sign in. MCP does not create accounts anonymously; public MCP tools are discovery-only, authenticated hosted MCP tools require a bearer token, and local MCP can initiate the same user-approved OAuth flow with rstream_auth_start and rstream_auth_poll. Local MCP login starts from the limited CLI setup permissions by default; broader actions such as project creation or settings updates require an explicit permissions request that the browser approval screen shows to the user. For machine workflows, project-scoped credentials or environment variables can still be used when an account-wide login is not appropriate.

Agents should distinguish token jobs before they mint anything. A developer workstation uses the long-lived rstream login credential and linked project contexts; local MCP can prepare those contexts with rstream_runtime_prepare. A remote device usually uses a project-scoped credential restricted by resources and permissions, but scoped does not imply short-lived. Short-lived delegated tokens are for immediate URL, browser, published MCP, query-token, or runtime handoff flows.

API contracts

The Control plane API and the Engine API are intentionally separate.

The hosted OpenAPI contract at /api/openapi.json covers automation-facing managed platform operations. This includes whoami, workspace and member listing, project listing, project creation options, project creation, project endpoint resolution, project settings, hosted logs, project usage, stable domains, TURN usage, 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 allow, 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;
• register the local rstream MCP server for Codex, discover labeled WebTTY machines, run non-interactive commands, and use the optional filesystem sidecar when the server advertises it;
• expose a service that is local to a remote WebTTY machine, including a local MCP server on that device, without opening inbound ports on the device;
• 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. When the action can be confirmed directly, the agent uses the project creation endpoint with a stable idempotencyKey. When the action requires hosted payment, the agent can start the hosted checkout through the OpenAPI-described project checkout operations, send the user to the returned payment URL, then complete or cancel the reserved project from the return parameters. 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 at /.well-known/mcp/server-card.json and a hosted Streamable HTTP MCP endpoint at /api/mcp. The public hosted tools return discovery metadata and the hosted OpenAPI contract. Authenticated hosted tools require Authorization: Bearer ...; they do not fall back to browser cookies, so an agent does not accidentally act as whichever dashboard user is signed in. The authenticated hosted tools expose account identity, workspace discovery, workspace member inspection, tunnel project discovery, project logs, project usage, TURN usage, short-lived TURN credential minting, stable domain inspection and management, project settings, project creation options, explicit project creation or checkout start, and short-lived auth token minting. Runtime command execution, private tunnel dialing, managed local tunnel exposure, and WebTTY filesystem access stay out of the hosted surface.

For workstation-local agent workflows, the CLI provides rstream mcp serve and rstream codex setup. That local MCP server can initiate OAuth login, prepare a selected project context from the local login token, and use the user's native private tunnel dialer, which makes it suitable for Codex workflows that operate remote WebTTY machines, mint delegated tokens, create persistent reviewable HTTP previews, expose remote-local services through WebTTY, and discover remote MCP surfaces.

When a remote agent needs to reach the user's local rstream MCP server, rstream mcp publish serves the same MCP tools over Streamable HTTP and exposes them through an HTTP tunnel. Published MCP tunnels advertise application-protocol=rstream.mcp, rstream.mcp.transport=streamable-http, and rstream.mcp.path=/mcp, and token authentication is enabled at the rstream edge by default.

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.
• Codex covers the local MCP and WebTTY workflow for Codex.
• 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 resources and scope reduction.