For developers

One API. Four ways in.

Everything Rytiv does goes through one HTTP API. The CLI, the console and the MCP server use the same routes you can call yourself, with the same keys. Push to GitHub, type ry, write fetch, or let your agent do it.

curl https://api.rytiv.com/v1/apps -H "Authorization: Bearer $RYTIV_TOKEN"

The same call four ways, as every docs page shows it. The base URL is https://api.rytiv.com/v1.

Four ways in

Same keys, same apps, whichever door.

All four see the same apps, databases and machines. The console at console.rytiv.com is where you sign in, create keys, wake a computer and top up credit.

01 · GitHub

Deploy on push

Link a repository to an app. Every push to the branch builds and deploys; other branches open a protected preview that closes on its own.

terminal
ry git connect web --repo acme/web --branch main
02 · CLI

ry, in a terminal or in CI

Signs in with a code, reads rytiv.json, and does what the console does. Every command takes --json for scripts and agents.

terminal
ry login
ry deploy web --source .
03 · REST API

Your own code

The API reference is generated from the control plane's routes: every field, bound and error code is what the code enforces.

terminal
curl https://api.rytiv.com/v1/apps -H "Authorization: Bearer $RYTIV_TOKEN"
04 · MCP

Your coding agent

One endpoint, 24 tools, annotated so your client knows what to confirm. Claude Code, Codex or any client over Streamable HTTP.

terminal
claude mcp add --transport http rytiv https://api.rytiv.com/v1/mcp --header "Authorization: Bearer <your key>"
For coding agents
The first ten minutes

From a folder to a URL, then to your agent.

Six commands from the docs, in order. To run machines an account needs credit: the starting credit if it qualifies, otherwise a first top-up.

  1. Install the CLI

    A Node.js package, Node.js 22.6 or newer. The installer checks the published checksum before it installs anything.

    terminal
    curl -fsSL https://get.rytiv.com/install.sh | sh
  2. Sign in

    ry login shows a code you confirm in the console, and stores a key for the CLI. In CI or a container, use ry login --token <key> or RYTIV_TOKEN instead.

    terminal
    ry login
  3. Deploy a folder

    The app is created if it does not exist. The CLI prints what it detected, uploads, builds on Rytiv and rolls the deploy. The last line is your URL on rytiv.app.

    in your project
    ry deploy web --source .
  4. Watch it run

    Stream the console output of the app's machines. ry init web saves the settings in rytiv.json, so the next deploy needs no flags.

    terminal
    ry logs web -f
    ry init web
  5. Deploy on push

    Installs the GitHub app through the browser and links the repository. Every push to the branch deploys; other branches get a protected preview.

    terminal
    ry git connect web --repo acme/web --branch main
  6. Hand your agent a key

    An agent key that can do what your organization can, except touch credentials, limited to the apps you name. Then add it to Claude Code.

    terminal
    ry keys create claude-code --agent sandbox --app web

Or run ry on its own in a project directory: it signs you in if needed, shows what it detected, asks for an app name and deploys. Deploy a Next.js app walks through secrets, releases and rollback.

REST API basics

A bearer key, JSON, one error format.

Requests and answers are JSON. Every route acts as the organization of the key; a name of another organization answers exactly like one that does not exist.

Base URL and key

base URL
https://api.rytiv.com/v1
every request
Authorization: Bearer ryt_...

Keys start with ryt_. Rytiv stores only a hash, so a key is shown exactly once. The product API has no general rate limit; the MCP endpoint, shell sessions, viewer links and the login entrances do, and answer 429 with Retry-After.

A deploy, a branch or a fork answer 202 and continue in the background. Poll the object they name until it is done.

Errors: branch on code, show error

every error
{ "error": "name already taken", "code": "name-taken" }
400bad-request: malformed, or a field out of range. issues lists every field.
401No API key, or one that does not work.
402Credit at zero. Reads, billing, stops, deletes, detaching and creating keys still pass.
403The key may not: a scope, an agent class, an organization limit.
404Not found, or not yours.
409Conflicts with the current state: a taken name, a deploy already running.
429A limit or a rate limit. Retry-After says when.

New codes can appear; a code your program does not know should fall back on the HTTP status. The error catalog lists every one.

From your code

A few lines of fetch is all it takes.

The API is plain HTTP with one error format, so any language reaches it. This small helper does the job: the key read from RYTIV_TOKEN, errors you can branch on.

const API = process.env.RYTIV_ENDPOINT ?? "https://api.rytiv.com";

async function rytiv(path: string, init: RequestInit = {}) {
  const res = await fetch(`${API}/v1${path}`, {
    ...init,
    headers: {
      Authorization: `Bearer ${process.env.RYTIV_TOKEN}`,
      "Content-Type": "application/json",
      ...init.headers,
    },
  });
  const body = res.status === 204 ? null : await res.json();
  if (!res.ok) throw new Error(`${body?.code ?? res.status}: ${body?.error ?? res.statusText}`);
  return body;
}

const sandbox = await rytiv("/sandboxes", {
  method: "POST",
  body: JSON.stringify({ template: "app:web", ttlSeconds: 600 }),
});
const result = await rytiv(`/sandboxes/${sandbox.id}/exec`, {
  method: "POST",
  body: JSON.stringify({ cmd: ["node", "--version"] }),
});
console.log(result.stdout);
await rytiv(`/sandboxes/${sandbox.id}`, { method: "DELETE" });

The helper creates a sandbox from the image of the app web, runs node --version in it, prints the output and ends it. RYTIV_ENDPOINT overrides the address, like it does for the CLI. Your coding agent already has the platform as MCP tools.

Authentication and keys

One kind of key. Narrow it as far as you like.

The same key works for the REST API, the MCP server and the CLI. Without scopes it is the whole organization; scopes, an expiry, an agent class and an app list make it do less, never more. The platform enforces all of them.

Create a key for an agent

Creating a key needs a full key; your first one comes from the console or from ry login. The value is in the answer once.

ry keys create claude-code --agent sandbox --app web --app web-try

Scopes

readEvery read of the product API that is a status. Not credentials, not billing, not the files of a machine.
deployThe deploy routes of every app: build, deploy, releases, rollback, logs, machines, secrets. Never creating or deleting an app, never a key.
deploy:<app>The same for exactly that app.
mail:sendSending mail from any proven domain of the organization.
mail:send:<domain>Sending from exactly that domain.
a CI key for one app, for 30 days
ry keys create ci-web --deploy web --expires-in 30d
ry keys create status-page --scope read

Expiry

A key may stop working at a moment or after a duration, from 60 seconds to 365 days ahead. A key with an expiry cannot create a key that outlives it. Revoking rejects requests already using it, right away.

Agent classes

sandbox and twin may do what your organization's keys do, except create, reveal or revoke credentials. production may only read. Every agent action is audited before it runs. More on agents.

Device login

ry login asks for a code, you confirm it in the console, and the CLI receives a key of your team that you can revoke like any other. Where nobody can open a browser: ry login --token <key> or RYTIV_TOKEN.

OAuth for hosted clients

A hosted MCP connector needs nothing but the address. OAuth 2.1 with dynamic registration and PKCE, no client secrets; you approve once in the console. Access tokens last an hour, refresh tokens 30 days.

Managed organizations

Once we enable you as a partner, your organization can manage others, and a key of yours can act inside one with the header X-Rytiv-Org. Agent tokens cannot use it.

Environment

RYTIV_TOKEN for the key, never written to disk. RYTIV_ENDPOINT for the address. RYTIV_PROFILE to pick one of several saved logins.

Webhooks

Be called when mail moves.

Register a URL for events of your organization; every delivery is recorded and can be read back over GET /v1/webhooks/:id/deliveries. The events are mail events: email.sent, email.delivery_delayed, email.bounced, email.complained, email.failed and email.received. Up to 20 webhooks per organization.

The answer to the create carries a signing secret, shown once. Registering and removing webhooks needs a full key; agent tokens are refused. Mail is in private beta and is for transactional mail only, no advertising or newsletters.

register a webhook
curl -X POST "https://api.rytiv.com/v1/webhooks" \
  -H "Authorization: Bearer $RYTIV_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"url":"<url>","events":["email.sent"]}'
or with the CLI
ry mail webhooks add https://www.example.com/hooks/rytiv
ry mail webhooks list
Docs for agents

Docs your agent can read without scraping.

Every page of the docs is also plain Markdown, generated from the same source. /llms.txt lists every page with a one-line description; /llms-full.txt is the whole documentation in one file. Every page has a Copy page button for pasting into a conversation.

The MCP tools page is generated from the table the server answers tools/list with, and the CLI reference from the CLI's own command definitions. If a parameter is listed, it is accepted. Inside a connected agent, search_docs answers from a knowledge base in the platform, without a request to the docs site.

terminal
curl https://docs.rytiv.com/llms.txt
curl https://docs.rytiv.com/llms-full.txt
curl https://docs.rytiv.com/quickstart.md

Your first deploy is one command away.

Deploy from a folder, or connect your coding agent with one command.

Add Rytiv to Claude Code
claude mcp add --transport http rytiv https://api.rytiv.com/v1/mcp --header "Authorization: Bearer <your key>"