Reference

The control surface for RunOS: the CLI, the CLI MCP server for AI assistants, runostty for browser terminals, and the platform APIs. This page is the map, not the deep dive.

The RunOS CLI

The runos CLI is a thin client for the RunOS API. It does not talk to your cluster directly. Every command is an HTTP call to the API, which does the real work.

Static and manifest-driven commands

The CLI has two kinds of commands.

Static commands are built into the binary:

account  agents  app-info  apps  builds  cluster-domains  clusters
config  deploy  domains  follow  gpu  integrations  jobs  login
logout  maintenance-scripts  manifest  mcp  nodes  pull  run
service-info  services  status  tags  tools  update  user
version  version-check

Manifest-driven commands have the shape runos <group> <verb>. They are generated from a catalog the RunOS API publishes, so new platform capabilities show up without a CLI upgrade. Refresh the catalog with:

runos manifest update

That downloads the latest manifest and caches it at ~/.runos/manifest.json. Inspect it with runos manifest show (version and command count) or runos manifest list (paths). The live catalog is version 31.14.0 with 483 commands.

Auth and config

Authenticate one of two ways:

runos login                                         # browser login
runos login --account-id <aid> --api-key <pat>      # headless / CI

A PAT (personal access token) has the form runos_pat_<keyId>.<secret> and is scoped to one account, so --account-id is required with --api-key. Credentials are stored in ~/.runos/config.json.

Token precedence, highest first:

1. RUNOS_API_KEY environment variable
2. the stored PAT in ~/.runos/config.json
3. the browser login session from runos login

A RUNOS_API_KEY that is set but empty is a hard error, not a fallback. This stops a CI runner with a typo'd secret reference from silently using a developer's stored credentials.

Set a default cluster so you can drop --cid:

runos config set cid <cid>      # e.g. ky3
runos config get                # show current config
runos status                    # account, default cluster, auth state

runos apps diff returns CI-gate exit codes: 0 no drift, 1 the command itself errored, 2 drift you should reconcile or push. runos services diff behaves the same way.

Install vs self-update

Install with the attested script:

curl -fsSL https://get.runos.com/cli.sh | bash
runos manifest update     # pull the command catalog on first run

Update an existing install in place:

runos update              # download and install the latest version
runos update --check      # report only, install nothing

The CLI MCP server

The CLI ships an MCP server so AI assistants (Claude Code, Codex, Gemini CLI, OpenCode) can drive the platform with the same operations you run by hand. This is the platform control MCP. It is not the internal agent-coordination MCP (see Disambiguation).

Wire it into an assistant:

runos mcp configure claude     # or: codex | gemini | opencode

configure claude writes a project-level .mcp.json and .claude/settings.json.

runos mcp bootstrap is the required first call. The assistant must run it before any other RunOS tool. It returns the rules for using RunOS correctly plus an index of documentation topics. From there:

runos mcp topics search <keywords>     # find docs before an operation
runos mcp topics show <key>            # fetch one topic by exact key

Tools are grouped into four categories so an assistant (and you) can reason about blast radius: read, sensitive-read, write, and sensitive-write.

runostty

runostty is a browser-based terminal served one pod per user. Each user gets an isolated, persistent workspace: a containerised Ubuntu environment with a WebSocket terminal and an HTTP file API, all on a single port.

The image ships the coding agents (claude, codex, gemini, opencode) and the runos CLI pre-installed, plus kubectl and k9s for operators. The home directory is PVC-backed, so projects and shell history survive pod restarts. Beyond the terminal, runostty exposes HTTP endpoints to list directories, read files, and download a project as a .tar.gz. Every request is authenticated with a frequently-rotated pre-shared key over TLS, and file access is scoped to the user's home directory.

The API surface

The CLI and Console sit on top of these services. Most users never call them directly; this table is the map.

API	Protocol	What it is
RunOS API	REST	The main control plane surface. The CLI is a thin client for it.
Cluster Agent	gRPC / mTLS	In-cluster agent. Dials out to the control plane (no inbound port) and runs builds, migrations, and TLS certs in your cluster.
Notify API	REST	Email notification delivery.
runostty API	WebSocket + REST	Per-user terminal and file access.

Disambiguation

Two things in RunOS share a name with something else. Keep them straight.

Two MCP servers. The CLI MCP server described above drives the RunOS platform: deploy, services, clusters, the works. There is also a separate internal MCP used to coordinate the AI agents that build RunOS itself. That second one does not operate your platform and is out of scope for these docs. When this documentation says "MCP", it means the CLI MCP server.

Three meanings of "manifest".

Term	What it is
CLI manifest	The command catalog the RunOS API publishes, cached at ~/.runos/manifest.json, refreshed by runos manifest update.
runos.yaml	Your infrastructure-as-code file. runos deploy reads it from the current directory.
Kubernetes manifest	The rendered Kubernetes objects applied to the cluster.