What you do
You need a RunInfra account, a workspace you own, and credits or a serving Coding plan for one short paid check.1
Paste the setup prompt
2
Approve sign-in
Your agent shows you a link, https://runinfra.ai/cli/authorize, and a code such as
ABCD-EFGH.
Open the link and sign in. Type the code and select Continue.
The next page shows the code again and the workspace it will connect.
It uses your active workspace; to use another workspace you own, switch to it in RunInfra and reload the page.
Select Approve only if the code is the one your agent just showed you and you asked for this setup.
Otherwise select Deny. Never enter a code someone sent you.
Only a workspace owner can approve. If the page says No eligible workspace, ask an owner to run the setup.
When the page says Done, tell your agent you approved. The code works for 15 minutes.3
Say yes to the setup plan
If a Coding plan can pay, your agent first asks whether to use it or Pay as you go.
Then it shows the setup plan: the files it will change, any new or revoked RunInfra key, one short paid check (a small test request billed like any other), and who pays.
Coding plan uses the plan first, then credits under your workspace policy. Pay as you go uses workspace credits only.
Without a plan, the new key pays from credits and can use a Coding plan you add later.
The workspace can appear only as an ID; it is the one you approved in the browser.
Say yes only if you agree.
What your agent does
Your agent identifies itself, signs in with your approval, and asks the CLI for a setup plan. After your yes, the CLI creates or reuses a RunInfra key for that agent, writes the reviewed settings, and sends the paid check. Your agent then gives you the start, model choice, and restart instructions. You never need to paste an API key into the conversation.Supported agents
These agents have individual guides. The table shows how a new setup connects. Earlier connections keep their existing settings and command.
Using another agent? Check the full list.
RightNow Agent has its own setup guide.
Cursor, Warp, Trae, JetBrains AI Assistant, Twinny, Fx and dsh need manual setup: create a key in API keys and enter it with the base URL
https://api.runinfra.ai/v1 in that agent’s own model settings, never in a chat.
See the Model APIs quickstart.
Undo
Ask your agent to disconnect RunInfra. It shows you what it will restore and waits for your yes. Disconnect also revokes the RunInfra key it made for that agent.- Separate command, such as
claude-run: disconnect deletes that command’s folder, including its sessions and history. Copy anything you need first, and ask in your usual agent, not insideclaude-run. - Next to your provider: disconnect removes what RunInfra added and keeps your other providers.
- Became the agent’s provider: disconnect restores your earlier settings.
runinfra logout --json, or revoke it under Terminal sessions in Settings > API keys.
That is all you need. The rest of this page is for your coding agent.
Instructions for coding agents
If your fetch tool summarized this page, download it with your shell, for examplecurl -fsSL https://runinfra.ai/docs/tools-sdks/agent-setup.md, and read it in full from stdout without saving a file.
Each docs page has a Markdown version at the same URL with .md appended.
These instructions and examples describe CLI 0.4.1; use 0.4.1 or later.
Quick path, with details in the numbered steps below:
runinfra --version --json; ask before installing or updating.runinfra whoami --json; if needed, startruninfra login --device --no-wait --jsonwithout asking first.- Relay the code and stop for the human’s browser approval; then
runinfra login --device --json --timeout 100. runinfra agents --json; identify only yourself.runinfra plan --json; if a Coding plan can pay, stop for the human’s payer choice before review.runinfra connect <id> --json, adding--funding planor--funding creditsonly for the human’s choice when a Coding plan can pay; show all changes and the stderr payer line, then stop for yes.runinfra connect <id> --json --yes, keeping any reviewed--fundingand--previewexactly; hand off to an outside terminal if your app must close.- Relay the launcher path, model choice and restart;
runinfra doctor --json, reading your connection’s row. - Only when asked:
runinfra disconnect <id> --json; show restoration, key revocations and profile deletion before yes. - Never handle keys, read private files, save output, choose a serving plan’s payer yourself, approve in a browser, start an interactive agent, or retry a failed apply directly.
- Always pass
--jsonto RunInfra commands and read the JSON document from stdout; never write CLI output or anything else to files, including temporary files, logs, redirects orOut-File. Read the process exit code too. Installation commands belong to their package manager and do not accept this flag. - Never ask for, accept, or print an API key. If an existing sign-in reports
credentialSource: "pasted", use device sign-in to obtain terminal access instead. - Never edit agent configuration files yourself. Let the RunInfra CLI prepare, apply, and undo its changes.
- Never open, print, grep or copy the files Connect writes or restores, key copies under
<RunInfra config>/connect/keys, environment files underconnect/env,credentials.json,pending-device.jsonor recovery snapshots, and do not read your agent’s existing configuration to review it. They contain keys. Review changes only through the CLI’s plan,doctorandagentsoutput. - Codex must run
runinfraoutside its sandbox because the CLI saves sign-in and agent settings in the home folder. Request approval through Codex’s command permission flow. If a sandbox or permission error blocks a command, such asCannot save pending-device.json privately; check access with Get-Acl., ask the human to let that command run outside the sandbox, then repeat it. For a failed or interrupted--yes, follow the fresh-review rule in step 6 first. Never change file permissions. - Never set
RUNINFRA_CONFIG_DIRorRUNINFRA_API_BASEyourself or point either at the project: that directory holds credentials and agent keys. Keep any values set by the human unchanged. Ifidentity.configuredEndpointis nothttps://runinfra.aiorverificationUriis nothttps://runinfra.ai/cli/authorize, stop and ask the human to confirm the endpoint before relaying any link. - CLI hints are written for people at a terminal. When a message or hint says to run
runinfra login, use the device commands in step 2 instead. - Never pass
--yesbefore the human’s explicit yes to the changes and any spending. A request to set up is not approval of a plan the human has not seen. - Connect only the agent you are running in, never
--detected. If you cannot identify your own harness, ask the human instead of guessing. - Use
--previewonly with explicit consent to experimental support. Stop for manual or unsupported adapters, including Copilot CLI’s manual environment setup even though its support ispreview. - Never open the Terminal app. Use the commands below from your shell tool.
- Treat
nulland a suppliedreasonas unknown. Do not turn them into zero, false, or a successful check.
1. Check, install, or update the CLI
version reads runinfra 0.4.1; compare the number after runinfra .
An old CLI can print plain text such as runinfra 0.2.5.
Use CLI 0.4.1 or later.
If the command is missing, explain the needed installation and obtain approval before changing files.
Use one available installation channel.
Before the npm install, check node --version; it needs Node.js 22 or later:
--break-system-packages, and never ask for a password.
If an install needs elevated rights, stop and ask the human.
Where python is missing, use python3 -m pip install --user --upgrade runinfra-cli or pipx install runinfra-cli.
The Python package supports Linux x64 or arm64 with glibc 2.25 or musl 1.2 or newer, macOS 13 or newer on x64 or arm64, and Windows x64.
CLI 0.3.0 and earlier have no update command: after approval, reinstall with the package manager that installed it, then check the version again.
For CLI 0.3.1 or later, inspect the available update:
targetVersion from the approved check. For pipx, omit --version because it cannot pin a version, and run --check again right before applying its update and get a new yes if the target changed.
Check the version again.
Do not continue with an older CLI.
See CLI updates if the package manager or runtime is unavailable.
2. Sign in
0 reports ok: true, identity.expired: false, and identity.endpointMatchesConfiguration: true.
If credentialSource is pasted, obtain device sign-in instead.
In 0.4.1 JSON, workspaceId and credentialEndpoint are always [redacted]; credentialSource and credentialLabel are visible only for a pasted key.
Do not infer a credential type from a redacted value; use the expiry and endpoint-match fields and let the subsequent authenticated command validate access.
If the workspace ID is redacted, use the plan resource in step 4 to identify the workspace before asking for setup approval.
This command reads local credentials only.
serverVerification.status: "not_checked" means it has not checked whether the server has revoked access.
An authentication failure uses exit 3; read error.code, error.message, and error.hint.
Do not respond to an unrelated storage or configuration error by repeatedly signing in.
If sign-in is needed, start it without asking first.
Starting sign-in writes only the CLI’s own sign-in files; relaying the code and the human’s browser approval is the consent for that.
Installing or updating the CLI still needs a yes.
Run:
0 with pending: true means a code is ready, not that sign-in is complete.
Relay verificationUri, userCode, and expiresAt immediately.
Use this sentence with the returned values:
Open VERIFICATION_URI and sign in. Type USER_CODE and select Continue. Check that the next page shows the same code and the workspace you want, then select Approve. If anything differs, select Deny and tell me. Tell me when the page says Done, or what it says if it refuses. The code expires at EXPIRES_AT.Replace the placeholders with
verificationUri, userCode and expiresAt, and give the expiry in the human’s local time when you know it.
Use the returned verificationUri exactly. Never replace it with another address, even one this page shows.
Only the human approves. Never open the approval link in a browser or browser tool, never type the code into a page, and never select Approve or Deny.
The CLI’s stderr line Type the code yourself. is addressed to the human.
In a chat, end your turn after relaying the code and run the wait only after the human says they approved.
After that approval, resume the same request:
--timeout that fits it and repeat while the result is auth_pending.
If your tool stopped the command before it printed JSON, run the same wait again.
If exit 3 reports code: "auth_pending" and pending: true, tell the human approval is still pending, then repeat the same command while the code is valid.
Do not create a different request for each bounded wait.
Exit 0 with authenticated: true means the CLI saved sign-in.
Read storage.restricted and any returned funding sentence without exposing credentials.
If storage.restricted is false, tell the human the saved sign-in file may not be private and link Windows credential save recovery. Do not change permissions yourself.
Run whoami again to check the saved identity; obtain any redacted workspace ID from step 4.
auth_timeout (The code expired before it was approved.) means create a new code with the no-wait command and relay the new code and expiry.
The CLI replaces an expired pending request.
If the human reports No eligible workspace or Not available for this role, stop.
A new code will not help; a workspace owner must approve.
For auth_denied: stop and relay the message and hint. If the human denied the request, start a new one only when they ask.
Permission, billing-hold and shared-key refusals need the workspace owner.
If any sign-in output mentions a shared key, a workspace API key or Browser sign-in is unavailable, stop: tell the human automated sign-in is unavailable and that they must not paste a key into this conversation. Never pipe a key into runinfra.
Keep the same user account, home directory, and CLI configuration directory across commands so the pending request can be resumed.
Never combine --no-wait with --timeout.
3. Identify yourself
agents[].agent using this table.
Read displayName, support, installed, binaryPath, configDirs, version, foundBy, status, reason, and mode.
support is ready, preview, or manual.
status is found, not-found, timed-out, or error.
foundBy is binary, config, extension, or null.
In the CLI document, installed is false for configuration-only detection and null for a failed or timed-out check.
Explain missing installation or detection failures before continuing.
mode is a legacy profile-capability hint in 0.4.1.
OpenCode, Qwen Code, and Nanocoder can report profile even though a new connection goes next to the provider.
Use plan[].profile and the successful result’s nextSteps[].placement for the actual connection.
If your harness is absent or manual, stop, explain that it has no automatic path, and point the human to the manual setup line under Supported agents.
Do not select a different agent that happens to be installed.
For a preview adapter, obtain consent and keep
--preview on both review and apply commands.
4. Choose how to pay
schema: "runinfra.cli.plan/1" resource.
On a nonzero exit, plan --json returns the usual error document instead. Read code, message and hint, for example not_found (This server does not provide coding plan information yet., exit 4) or auth_denied (Plan information requires terminal account access.).
Show the plan resource’s workspace_id to the human.
snapshot.availability distinguishes an available, stale, or unavailable read.
snapshot.current: null means there is no current plan in that read; an unavailable read does not prove there is no plan.
Offer Coding plan or Pay as you go only when the read is available, snapshot.current.serving is true, tile_state is neither ended nor refund_closed, and covers includes chat.
When a Coding plan can pay, you MUST ask the human which payer BEFORE running the review.
Never choose for them. Wait for their answer, even if the plan is already serving.
Read snapshot.current.copy when present.
Use its policy, actual, remedy, and freshness fields to explain the current limits and any refusal.
If the read is stale or unavailable, do not use it to choose a plan.
Retry the read once after a few seconds. If it is still stale or unavailable, tell the human you cannot confirm a Coding plan and offer Pay as you go or waiting.
Never choose --funding plan from a stale or unavailable read.
Do not infer eligibility from sales_enabled, a tier name, or the subscription’s status alone.
When no plan can pay for chat, do not ask the human to choose a plan that cannot pay.
Omit
--funding. The new key follows the workspace policy: it pays from credits now and can use a Coding plan the workspace adds later.
Disclose Pay as you go in the setup plan.
Do not add --funding credits on your own: that key is Credits only and keeps paying from credits after a plan is added.
Find the balance before the review: the login funding sentence names it, for example Pay as you go: $250.00 in credits., and at 0 exits 4 before any write, so relay its reason and ask the human to add credits.
Do not purchase a plan or add credits for the human.
An explicit choice on reconnect can change an existing key’s payer with owner approval.
Show every note about that change because it affects every use of the key.
For this procedure, carry the chosen argument, or its absence, unchanged through review and apply.
5. Show the setup plan
Ifruninfra doctor --json already shows your connection row with ok: true and link: "config", tell the human it is already set up and ask before reconnecting, because a reconnect sends another paid check.
Replace <id> with your CLI ID.
Use exactly one of these commands, matching step 4:
--yes yet.
Exit 8 with code: "consent_required" is the expected review result.
It is not a failed connection.
A review can instead exit 6 with code: "config_modified", a refused[] list and plans[] (not plan[]).
Nothing was written and no key was created. Relay each refused[].reason.
If it names --preview, explain experimental support and add --preview to both review and apply only after explicit consent.
If it says the payer is set by the workspace owner, ask an owner or keep the key’s current payer.
Do not sign out, sign in again, or add --yes because of a refusal.
Read every entry in plan[] and show these fields to the human:
In CLI 0.4.1, the payer sentence goes to stderr and is not a stdout plan field.
Read that stderr line and show its balance and any warning with the plan.
State the payer chosen in step 4 alongside the full plan.
Use this template, replacing each placeholder with the returned values:
Setup plan for DISPLAY_NAME in workspace WORKSPACE_ID. Files: PATH (+ADDED/-REMOVED) for each file. Keys: creates KEYS_CREATED, revokes KEYS_REVOKED; the key is kept in KEY_PLACEMENT. Paid check: PAID_REQUESTS short request, paid by PAYER. Result: PLACEMENT_IN_WORDS. Notes: every note. Reply yes to apply this plan and send the paid check.For a
slot agent, say that RunInfra replaces the agent’s current provider until you disconnect.
In 0.4.1 the workspace note always starts with [private identifier omitted]: give the ID in parentheses and say it is the workspace approved in the browser.
Do not invent a workspace name. If you reused a saved sign-in, say so; if the human is unsure which workspace it is, run device sign-in so they can check the name on the approval page.
For Goose and Zed, tell the human before asking for yes that the agent works only after they set RUNINFRA_API_KEY themselves from the key copy the plan lists.
Never open that file or print the key.
Do not silently apply when the plan contains unexpected files, workspace, key changes, or instructions you cannot satisfy.
Ask for the human’s explicit yes to that plan and spending.
Wait for the answer.
6. Apply after yes
Repeat the reviewed command with the same ID, payer argument, and any approved preview flag, adding only--yes:
--funding plan or --funding credits here when the review had it.
If a plan note says to close or quit the app you are running in, do not apply from inside it.
After the human’s yes, give them the exact reviewed command with --yes to run in a terminal outside the app after closing it, say that it sends the one paid check, and stop.
When they are back, run runinfra doctor --json. Disconnect works the same way.
This applies to Cline and to preview apps such as Zed, VS Code Copilot Chat, Theia AI, OpenHands CLI and Octofriend when their plan has this note.
Read plans, changes, probes, and nextSteps.
changes.events records what the engine did, including key, configuration, and verification outcomes.
changes.profiles records separate profiles.
An empty top-level probes array does not mean no paid check ran: connect verifies during apply and records it in changes.events.
Success is exit 0 with changes.verificationFailed: false, a probe event with result.ok: true and an agent_done event with verified: true for your connection.
Compare the returned plans[] with the plan the human approved; if anything differs, tell the human and list what was applied.
If verificationFailed is true (exit 4 when funding refused the check, otherwise 5), the settings were saved but the paid check failed.
Tell the human, quote the probe event’s result.message and any retryAfterSeconds, relay nextSteps as unverified, and run runinfra doctor --json.
For any other nonzero exit, read code, reason, recovery and changes.events.
If missingAgents is returned, report which work did not complete.
After any failed or interrupted --yes command, never repeat it directly: prepare a fresh review without --yes, show the new plan, and wait for a new yes.
7. Finish setup
Tell the human how to start. For a separate command, give the full launcher path fromplans[].profile.launcherPath first (on Windows the .cmd file; in PowerShell run it as & '<path>', in cmd as "<path>"), then the short name from nextSteps[].command, which works by name only once <RunInfra config>/bin is on PATH.
The PATH and Run now lines in plans[].notes and agent_done.followUp are written for the shell your tool ran the CLI in; say which shell.
The PATH line lasts one terminal.
Relay pickHint and restart verbatim, and describe placement in words: fork is a separate command, additive is next to your provider, slot replaces the agent’s provider.
Notes are for the human: never run Run now, the start command, a PATH or shell-profile line, or a note command that sends a model request.
For Goose and Zed, point the human to the private key copy in the plan, <RunInfra config>/connect/keys/goose.json or zed.json.
In their own terminal or editor, outside this conversation, they copy its apiKey value into RUNINFRA_API_KEY in the environment that starts the app; Zed also allows its RunInfra provider settings.
They must fully restart the app. Never open the file or print the key yourself.
For other environment-based connections, relay the plan’s remaining environment step without handling its key.
Do not claim the current running session has changed before its restart or model-selection instructions are satisfied.
8. Verify without another paid request
agent is your connection name from plans[].agent, for example claude-run, not claude.
ok: true with link: "config" means the written files match the saved connection; it does not prove the agent restarted.
Your native agent’s row and other agents’ rows say No Connect configuration is recorded for this agent.; ignore them.
Rows with agent: null are host checks: ok and skip pass, warn and unknown are advisories.
After a fresh sign-in, host:sign-in is unknown because Doctor does not contact the server to validate sign-in, and on Windows the storage:* rows are warn because a read-only check cannot verify file privacy.
Do not sign in again, change permissions, reconnect, or run a command from a hint because of these rows.
If your key lives in the environment (Goose, Zed, Mistral Vibe, Oh My Pi), your row shows ok: false with link: "key" until RUNINFRA_API_KEY holds the key in the shell Doctor runs in; report that as the human’s remaining step.
Otherwise report your row when ok is false, quoting its message and hint.
This command diagnoses without changing the connection or sending paid inference.
Do not add --verify; that sends paid requests and needs separate consent.
9. Undo when asked
claude-run, in place of <id>.
Show the restore plan and key revocations.
Disconnect revocations name the key as keyId; the sessions warning is on stderr.
Do not disconnect the profile you are running in. Ask the human to return to their usual agent first.
If the app must close before restoration, hand the reviewed command to the human as in step 6.
Warn that deleting a profile also deletes its sessions and history.
After explicit approval, repeat with --yes:
--force or --keep-key unless the human has reviewed their effects.
If files changed since setup, preserve those edits and follow CLI troubleshooting.
Exit codes
Error codes and recovery
Read the returnedmessage, hint, reason, and recovery where present.
For whoami, the error code is nested in error; login failures put code at the top level.
Troubleshooting
If approval is still pending, keep the same CLI configuration directory and repeat the bounded wait. If the agent cannot be detected, check its own row’sreason rather than assuming it is uninstalled.
If the current session still uses your earlier provider, follow the exact model-picker and restart instructions in nextSteps.
For billing, configuration conflicts, or a failed paid check, use CLI troubleshooting.
See JSON output for field details and CLI commands for other operations.
Short JSON examples
These are excerpts from CLI 0.4.1 against a test service; IDs, paths and times are placeholders. Read the complete JSON examples for both payers, Doctor after connecting, and removal of a real connection. The test service issues one-day access and 10-minute codes; production terminal access lasts 90 days and codes last 15 minutes. Pending sign-in, exit0; relay the code and wait for the human:
8. This excerpt omits the file list and notes; show every returned field in the actual review:
0. This excerpt omits the events and next steps; read them before claiming success:
Terminal app
The terminal app is for people at a terminal. Coding agents must never run bareruninfra or runinfra launch because those commands can open an interactive application or start a child agent session.
Use the numbered JSON command procedure above.