Integrations

Connect Runtype to coding agents

Run the following command to connect the coding agent in your current session to Runtype:

Onboard the coding agent
$npx -y @runtypelabs/cli@latest onboard

The command signs you in to Runtype. It installs Runtype agent skills, configures the hosted OAuth MCP connection, and prints the next steps. After you restart or reload the coding agent, use it to build and operate Products, Flows, Agents, Tools, Surfaces, and Records in your Runtype account.

What onboard does

The onboard command runs setup in five stages:

  1. Sign in to the CLI. Use an existing CLI credential or RUNTYPE_API_KEY. Without credentials, browser OAuth is available only in an interactive terminal outside JSON mode. A noninteractive coding harness receives authentication instructions instead; use the browserless setup below.
  2. Install skills. Install Runtype agent skills from the public runtypelabs/skills repository for the detected coding agent.
  3. Configure MCP. Write a user-level MCP server entry named runtype that points to https://api.runtype.com/v1/mcp/protocol.
  4. Authorize MCP. Start the coding agent’s MCP OAuth flow when the client supports it. Otherwise, print the client’s OAuth instruction.
  5. Restart or reload. Print the instruction for the detected coding agent. Restart or reload the coding agent before you use this connection.

After the restart, ask the coding agent to work with Runtype. Before building a product or flow, fetch the matching get_build_instructions task. Read-only account operations do not need that build setup. Start with a prompt such as “Use Runtype to build a customer-support agent.” The client then fetches the platform rules.

Onboard detects the coding agent that runs it. To select a coding agent explicitly, run:

Select a coding agent
$runtype onboard --agent <id>

Replace <id> with claude, codex, cursor, gemini, opencode, or vscode. Add --force only when the command reports a conflicting runtype entry that points to another URL.

Browserless CLI authentication

Before starting a new signup, run runtype auth status to inspect stored login and pending signup state. If RUNTYPE_API_KEY is configured, verify it with runtype auth whoami --no-tty instead: status does not inspect environment credentials. Reuse a valid account; otherwise resume a pending signup using its returned next command.

For a new account, ask the user for their email, run runtype auth register --email <email>, then ask for the emailed code and run runtype auth verify <code>. Neither command opens a browser. Existing-account credentials must be configured privately by the user, not pasted into agent chat. Verify them with runtype auth whoami --no-tty, then rerun runtype onboard. The harness’s later MCP OAuth remains a separate authorization step.

Use the CLI safely from a coding harness

Prefer hosted MCP after restarting your coding agent. When shell automation or a first-session fallback needs the CLI, inspect its effective target first:

$runtype config context --json
$runtype --no-input --expect-api-url https://api.runtype.com --expect-org org_example \
>  flows run flow_example --inputs '{"limit":5,"enabled":true}' --json

Replace the example organization and flow IDs with your own. config context shows the endpoint and credential source without exposing the key. It is offline; orgVerified: false means any stored organization hint has not been checked. --expect-org verifies server identity before API actions. The endpoint resolves from --api-url, then RUNTYPE_API_URL, saved apiUrl configuration, the stored credential endpoint, and finally production. Saved URL settings now apply to ordinary API commands, so remove stale settings before relying on a default. Claim/verify retains the token’s issuing endpoint and checks it against --expect-api-url before acting. Anonymous registration and claim/verify reject --expect-org because the ceremony cannot verify the resulting organization.

dispatch, flows run, and agents execute accept typed JSON objects through --inputs or --inputs-file <file|->, and message arrays through --messages-file <file|->. A - reads stdin; only one source can consume it. Repeatable --variable key=value values remain strings. Conflicting sources and duplicate input keys are rejected before execution.

For these execution commands, --json prints one final JSON result; --jsonl prints event lines followed by an execution_summary event. Choose one format. Exit code 1 means failure, invalid input, authentication failure, or an incomplete stream. Exit code 2 means the execution awaits input or approval, not success; the CLI never approves or restarts it automatically.

--no-input disables prompts and does not imply consent. Destructive delete, bulk-delete, revoke, and reset commands also require --yes. Implicit login does not prompt on piped stdin; configure credentials privately before supplying data. Marathon and agents task use their own headless JSON mode and reject --no-input.

To wait for an existing batch without resubmitting it:

$runtype batch status batch_example --watch --timeout 600000 --interval 2000 --json

Watching works without a terminal. It defaults to a 300,000 ms timeout and a 2,000 ms polling interval; --json emits only the final result or wait error. Timeout stops the local watcher, not the server batch. Failed, cancelled, or partially failed batches exit nonzero.

Per-agent notes

Onboard uses each coding agent’s MCP configuration and OAuth flow. Use the following notes when you need to complete OAuth or restart a specific coding agent.

Claude Code

Onboard writes a user-level MCP configuration entry that matches claude mcp add --transport http --scope user runtype https://api.runtype.com/v1/mcp/protocol. Run claude mcp login runtype to complete OAuth. Onboard installs Runtype agent skills in Claude Code’s global skills directory. Start a new Claude Code session or reload MCP servers.

Cursor

Onboard writes the connection to Cursor’s global MCP configuration. Run cursor-agent mcp login runtype to authorize it. Onboard installs Runtype agent skills for Cursor. Restart Cursor or start a new Cursor agent session.

Codex CLI

Onboard configures the same server as codex mcp add runtype --url https://api.runtype.com/v1/mcp/protocol. Run codex mcp login runtype to complete OAuth. Onboard installs Runtype agent skills for Codex. Restart Codex or start a new Codex task.

Gemini CLI

Onboard adds a user-level server that matches gemini mcp add --scope user --transport http runtype https://api.runtype.com/v1/mcp/protocol. In Gemini CLI, run /mcp auth runtype, then /mcp reload to authorize and reload the connection. Onboard installs Runtype agent skills for Gemini CLI.

OpenCode

Onboard configures the same server as opencode mcp add runtype --url https://api.runtype.com/v1/mcp/protocol. Run opencode mcp auth runtype to authorize it. Onboard installs Runtype agent skills for OpenCode. Restart OpenCode or start a new OpenCode session.

VS Code

Onboard registers a user-level HTTP MCP server through the VS Code CLI with code --add-mcp. Onboard installs Runtype agent skills for GitHub Copilot. Approve the browser OAuth prompt the first time a chat uses Runtype. Reload the VS Code window, then start a new chat.

Use the machine-readable resources

Use these machine-readable resources when you set up Runtype for someone else:

Run runtype onboard instead of writing MCP configuration by hand. You can run the command again without duplicating the runtype entry. When the installer edits an existing configuration file directly, it backs up the file, verifies the configured entry, and restores the backup if verification fails.

Work inside an existing codebase

After setup, define agents and flows in your Runtype account or in your repository. Use hosted configuration when you want to edit definitions in the dashboard, version them there, and call them from your code through the dispatch API. Use the TypeScript SDK’s FlowBuilder when you want definitions to ship with your code and go through review. Both options run on the same platform, and you can combine them.

Next steps

Continue with one of these guides: