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/auth.md
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. /auth.md gives agents a concise registration procedure built on those same endpoints.

DNS-aware agents can also discover the hosted MCP endpoint through _mcp._agents.rstream.io. The DNS-AID entry uses a Service Binding record to advertise HTTP/2 and HTTP/3 on port 443. The rstream.io zone is signed with DNSSEC, so validating resolvers can authenticate the discovery response. DNS-AID remains an active Internet-Draft; HTTP well-known documents remain the primary discovery contract.

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. auth.md describes this as anonymous registration because the agent starts without a service identity; access is issued only after the user completes the browser approval step.

The CLI uses the same direction of travel. rstream login defaults to OAuth Device Authorization Grant, while compatibility checks can still exercise the earlier hosted login path when needed. 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. The normal CLI and local MCP login bundle covers project discovery and management together with the runtime permissions needed to operate tunnels. An explicit permissions request is still required when a user-approved task needs another account surface, such as billing or workspace administration. For machine workflows, project-scoped credentials or environment variables can still be used when an account-wide login is not appropriate.

Agents 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 use 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;
• create and enroll a registered WebTTY server when the remote machine needs persistent inventory, managed recordings, live collaboration APIs, or workspace-managed E2E;
• enroll the CLI, agent, or service host as a trusted workspace device before opening workspace-managed protected WebTTY 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 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, short-lived auth token minting, WebTTY inventory, registered WebTTY server management, bounded non-E2E WebTTY execution, WebTTY session metadata, non-E2E recording export, and WebTTY control requests.

WebTTY is split deliberately. rstream mcp serve is the preferred WebTTY surface because it runs beside the local rstream config, WebTTY identities, known-server pins, trusted workspace devices, private dialer, and filesystem sidecar. Hosted MCP is a restricted fallback for clients that cannot execute the CLI. It never receives WebTTY private keys, never decrypts workspace-managed data, refuses E2E targets with an explicit local-trust error, and does not provide long-lived interactive attach. Runtime command execution that depends on local E2E trust, private tunnel dialing, managed local tunnel exposure, and WebTTY filesystem access stays on the local MCP 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.