Skip to main content
Connect your coding agent to RunInfra, verify a request, and restore the previous configuration when you are finished.

​
Connect your agent

Use an installed coding agent with its first-time setup complete. Have a workspace API key and available RunInfra credits. Continue CLI can require an explicit configuration path before onboarding is complete.
This is the same as npx @runinfra/connect claude on. In an interactive terminal, Connect starts login if needed. Review the proposed file changes, approve them, then follow the restart hint after verification. To install the command globally:

​
Commands

Use -h for help or -V for the version. No arguments shows help. A bare agent also accepts the on options.
--json is accepted on every command and emits newline-delimited JSON. Machine-mode on requires --yes: without it, Connect prints the file-change summary and exits 8 without writing configuration. on --json --yes applies changes without prompting. Sign in first for machine-mode on; it does not start login for you.
--yes approves on changes without a confirmation prompt. It does not bypass preview approval or repair conflicting files. --force belongs only to off and can discard later edits. Do not repeat options or pass keys as arguments.

​
Supported agents

The registry includes eighteen agents: six ready, nine preview, and three manual. ready supports automatic setup. preview requires --preview and has limitations listed below. manual prints instructions without writing files or claiming a verified connection.

​
What on writes

on checks that the agent is installed, reads your saved key, fetches the available model list, and selects models compatible with the agent. --model must be an available model id. Without it, Connect uses the first compatible model. Before asking for approval, Connect states the agent, model, destination, key placement, affected files, any permission change, and that the following API check uses credits. Connect shows a file-change summary, takes a snapshot, and records a pending operation with the origin snapshot and expected file hashes. It then writes the agent’s native settings and completes the connection record. For Codex the picker shows the configured model; switch with on --model <slug> or Codex’s own model option. Some adapters register models that you must select manually; follow the agent page and printed handoff. Existing unrelated settings are retained where the format can be edited safely; review every warning. Do not edit an agent’s configuration while a Connect command is running. Connect compares current bytes and rechecks file identity before replacement. On POSIX, it also retains a displaced-file copy when its contents differ from the bytes read and warns with its path. Windows does not make that copy. If the filesystem cannot create the copy, Connect warns and proceeds with its other checks. Writes through an already-open file can arrive after the final comparison, so these checks do not make concurrent editing safe. After an interrupted write, the next on, off, or key rotate checks the pending operation. If all files match the expected new bytes, Connect completes the connection record. If all match the previous bytes, it discards the pending operation. Mixed or modified files stop setup with exit 6. Review the named origin snapshot before choosing <agent> off --force to restore it. Status and doctor inspect pending operations without changing state. A final connection-state save failure keeps the written files and recovery record instead of undoing them. Recovery handles process interruption; it does not guarantee recovery after power loss. After writing, Connect makes a small real request using the selected model and the agent’s protocol. This request uses credits. It reports a request id and cached_tokens, or not reported when cache usage is unavailable. Follow the printed restart or new-chat hint before using the agent.
A successful probe is not proof that the agent has restarted. If the API check fails after writing, the settings and snapshot stay saved. Connect still prints the restart hint and launch instructions. Fix the cause it names, then run doctor <agent>, or <agent> off to restore.
Run on again to refresh the agent’s model list. Model choices are saved at setup time, not refreshed on every launch.

​
What off restores

off restores the origin snapshot from before the first on in the active connection and removes files that did not exist then. Later active on calls and key rotate keep that restore point. A changed managed file set requires off before reconnecting. Older state without an origin uses its recorded snapshot. Snapshots are retained, and recorded POSIX file permissions are restored.
If you or the agent edited a managed file after connecting, off refuses to overwrite it. Back up and review your edits first. Use off --force only when you intend to discard them. Connect saves the current contents in a recovery snapshot and prints its id before overwriting them.
Without usable recovery state, Connect removes only recognizable managed regions by default and refuses unmarked RunInfra settings. off --force saves a recovery snapshot before attempting to remove identifiable RunInfra credentials. A provider name or credential field name alone does not prove ownership. Foreign or ambiguous targeted credentials are preserved, and recovery refuses with exit 6 before editing. Unsafe syntax can require manual recovery. Best-effort cleanup leaves other settings unchanged and warns when the original snapshot is missing. It does not claim to restore the original configuration. If cleanup finished but state finalization was interrupted, a forced retry can clear the missing-snapshot state without another edit and reports restored: false, cleaned: true. Keep the retained snapshots for recovery.

​
Login, logout, and key replacement

Without RUNINFRA_API_KEY set, interactive login opens the RunInfra dashboard key page. Create or select a workspace API key for the workspace you intend to use, then paste your key at the hidden prompt. If the browser cannot open, use the URL printed by Connect. An existing RUNINFRA_API_KEY takes precedence over both paste and standard input. To paste a replacement interactively, unset that value first. To replace a key through the environment, update its value before running key rotate; otherwise the old key can be reused without a paste prompt. Login validates key access, reports available credits, and checks for available models before saving credentials. It does not require a positive credit balance. The completion probe happens during on, not login. For unattended login, supply the key through standard input from your secret manager or through RUNINFRA_API_KEY. Do not put the key in command arguments, shell history, screenshots, or logs. logout removes only Connect’s saved credentials. Agent settings and snapshots stay on disk, and the key is not revoked. Use <agent> off to restore an agent’s settings and revoke unwanted keys in the dashboard. key rotate acquires a replacement key, updates agents whose managed files are active, and probes them again. Missing or modified configurations are skipped and reported. Update helper environments yourself. Check every result before revoking the old key; retained snapshots can contain it. A partial rotation is reported as a failure even though new local credentials may already be saved. Machine results distinguish updated from probed; a failed probe after a successful write reports updated: true, probed: false.

​
Key placement

Unless an agent defaults to helper mode, the default --key-source literal stores a plaintext key in its native configuration or credential file with 0600 permissions on POSIX systems. Goose and Zed default to helper mode and refuse literal mode. Cline supports literal mode only. Crush is manual and writes nothing. For Goose, helper mode is the default; pass the key through OPENAI_API_KEY. Connect leaves the keyring unchanged. You do not need to pass --key-source helper explicitly. Zed requires a manual environment or in-app credential handoff and has no settings API-key field. Connect restricts permissions only on its own configuration directories, not an agent’s directory or your home directory. External files retain inherited Windows permissions. Connect reports Windows protection for its own credential and snapshot directories only after verifying access is limited to the current user, SYSTEM, or Administrators. Review any permissions warning; these files are not encrypted.
--key-source helper uses the agent’s supported indirection or printed environment handoff instead of a new literal key. Set RUNINFRA_API_KEY through your secret-management workflow, then follow the agent-specific instructions in the environment that actually launches it. A variable set only in a terminal does not reach an already running app, a background service, or a Windows GUI launch. Fully restart the app with the required environment. The setup probe uses saved credentials; it does not prove the app inherited the helper value. Helper mode does not erase Connect’s saved key or keys retained in older snapshots. Treat the credentials, snapshots, and agent configuration as secrets.

​
Status

Status includes the support tier, selected model, and connection time. active describes file contents only, not a running app or a successful current request. The all-agent command also checks for paused models when saved credentials are available; a catalog warning does not change the local file result.

​
Doctor

Doctor checks saved-key access, available models, and managed files before making a real protocol request. The first failing check determines the exit code: 3 for the key, 6 for configuration, 2 for the base URL or model, and 5 for the endpoint. Use an agent argument to check one setup strictly. Without it, doctor checks recorded connections. Unconnected adapters appear as informational not-connected rows and do not fail the command. Missing or modified files with recorded state still fail. Manual adapters are marked manual, not verified. Doctor does not rewrite configuration or verify an app restart. A stale model list can require on again. In helper mode it also checks the current process’s RUNINFRA_API_KEY, which does not prove a different app inherited that environment. Doctor’s real requests use credits. After a successful check, doctor prints the agent’s restart hint and launch instructions again.

​
JSON output

Add --json to any command and read stdout as newline-delimited JSON. Each nonempty line is one complete object with a string kind, not one element of a JSON array. Narration, warnings, recovery paths, and launch instructions go to stderr. JSON mode never opens a sign-in or confirmation prompt; machine-mode on needs an existing login and --yes. Consume the exit code as well as every record. A command can emit useful records and then fail. configured precedes verification and is not final success. A successful probe checks API access, not whether the agent restarted. Structured paths, model names, and identifiers keep their punctuation; secret and unsafe-control-character filtering still applies. Record kinds are config-conflict, configured, diff, doctor, error, help, key-rotate, login, logout, manual, off, paused-models, pending-recovery, probe, recovery-snapshot, status, and version. Key rotation includes per-agent records and a summary with summary: true. A failed probe includes httpStatus, reason, and retryAfterSeconds. Accept unknown fields and kinds so additive changes do not break your script. See Connect JSON output for every field, record condition, and command ordering table.

​
Preview adapters

Read the reason before opting in. on requires --preview for these adapters. Preview is not a dry run: it writes settings and sends a request using credits. It does not certify the adapter.
Kilo Code needs live stream/tool, override, IDE activation and post-start restoration checks before promotion from preview.
See Kilo Code for the verified CLI response, first-start permission block, and configuration precedence.
This preview writes Goose’s model and URL settings without changing the keyring or secrets.yaml. Set OPENAI_API_KEY in Goose’s launch environment. Confirm the settings and request destination in a new Goose chat before relying on this preview.Connect could not confirm the OPENAI_HOST/OPENAI_BASE_PATH URL recipe, GOOSE_PATH_ROOT and XDG_CONFIG_HOME overrides, system and additional-file precedence, companion-secret resolution, optional model limits, BOM or flow-style trailing commas, or comment preservation after native saves against the current Goose documentation; check the environment guide and provider guide before relying on it.
See Goose for the default helper handoff, private goose info -v settings check, and separate new-chat destination check. The settings check does not prove authentication or routing.
Continue requires explicit —config for safe first-run/rewrite handling. CLI tool execution is not sandboxed; IDE activation, routing, secrets and restoration after native saves need separate verification.
Follow the explicit-config startup instructions, including after onboarding. Continue CLI 1.5.47 completed a verified RunInfra round trip from the Connect-written file; IDE activation and the remaining preview checks are separate. --readonly is plan mode, not a sandbox.
This preview writes only providers.json with a literal API key. Connect could not confirm its paths, schema, selectors, authentication and helper resolution, globalState/Plan/Act precedence, model metadata fallback, CLI flags or restoration after native saves against the current Cline documentation; check the configuration guide and CLI reference before relying on it.
See Cline for literal credentials and separate CLI routing and VS Code Plan/Act checks. Connect prints manual follow-up guidance, not a Cline diagnostic command.
This preview registers RunInfra models in ~/.factory/settings.json. Connect could not confirm path overrides, parser behavior, effective generated IDs, saved-default selection, credential resolution, file watching or restoration after native saves against the current Droid documentation; check the CLI settings guide and BYOK guide before relying on it.
See Droid for the derived custom: id from the final written personal array and selection in Droid’s Custom models section. Confirm the derived id in the installed picker before use. Connect does not write a personal saved-default selector.
This preview writes RunInfra models to settings.json with a manual environment or keychain handoff. Connect could not confirm path overrides, the compatible-provider schema, RUNINFRA_API_KEY environment/keychain precedence, CLI diagnostics or restoration after saves against the current Zed documentation; check the configuration guide and API access guide before relying on it.
See Zed for the agent: open settings and zed: open settings file command-palette actions, credential handoff, and new Agent chat checks. These are editor actions, not shell diagnostics. Confirm a new Agent reply and its request destination separately.
This preview adds RunInfra models with api_backend = chat_completions and uses env_key in helper mode. Connect targets Grok Build’s user configuration, not project model settings.Connect could not confirm literal api_key support, GROK_HOME edge cases, other path and policy overrides, credential precedence, parser tolerance or save and restoration behavior against the current Grok Build documentation; check the settings reference and enterprise configuration guide before relying on it.
In literal mode, only the selected model stores the key. Other model selections also need RUNINFRA_API_KEY in the launch environment.Review GROK_DEFAULT_MODEL, GROK_MODELS_BASE_URL, GROK_MODELS_LIST_URL, GROK_CONFIG, and GROK_CONFIG_PATH before relying on the user file. Connect does not resolve those overrides.Restart Grok Build. Inspect the loaded configuration:
Confirm the selected RunInfra model and request destination separately. Connect’s API probe does not prove Grok Build used these settings. Restoring the managed file does not restore your external environment.
This preview adds a RunInfra provider to config.yaml with .env for literal keys. Connect requires at least 64,000 context tokens for this setup. That minimum is Connect’s preview guard.Connect could not confirm the native Windows default path, HERMES_HOME and profiles, the named-provider fields including api, key_env, transport, default_model and context_length, model.default and the custom:runinfra selector, credential and dotenv precedence, api_mode and enabled effects, required metadata, Hermes’s minimum context size, parser tolerance or save and restoration behavior against the current Hermes documentation; check the named-provider guide and configuration guide before relying on it.
Review the active profile and settings file before use. Check existing api_mode and enabled settings for competing provider choices. Connect keeps an existing .env assignment when another provider uses it.Restart Hermes after editing files. Inspect selection:
This checks configuration, not a reply or its destination. Confirm those separately. Restoring Connect’s files does not restore external credentials or profile settings.
This preview adds RunInfra models using JSON/JSONC only, not full JSON5. It sets models.mode to merge and selects runinfra/<model-id> through agents.defaults.model.primary. Connect leaves modelPolicy.allow unchanged. Check that policy before selecting RunInfra.Connect could not confirm the active file under OPENCLAW_CONFIG_PATH, OPENCLAW_STATE_DIR, OPENCLAW_HOME or profiles, parser tolerance, credential and per-agent model precedence, missing helper values, reload or changes after saves and restoration against the current OpenClaw documentation; check the configuration guide, environment guide, and model registry guide before relying on it.
If Connect refuses JSON5 syntax or a structure it cannot rewrite safely, review the non-secret settings before applying them through this command:
Supply the reviewed setting and value yourself. Use models.mode: merge, models.providers.runinfra.baseUrl: https://api.runinfra.ai/v1, and models.providers.runinfra.api: openai-completions. Set agents.defaults.model.primary to runinfra/<model-id>. Use the catalog’s exact model ids, names, reasoning support, context windows, and output limits for models.providers.runinfra.models; Connect uses input: ["text"].Enter your API key through OpenClaw’s Control UI Settings > Models. In helper mode, start OpenClaw with RUNINFRA_API_KEY in its actual environment. An export in another terminal does not reach an already running process.Check the active provider and model. Restart OpenClaw if reload is disabled or fails. Start a new chat. A successful Connect API probe does not prove OpenClaw used these settings. Credential cleanup without the origin snapshot does not remove the provider, model catalog, or primary selection.

​
Manual setup

These commands print the registry’s instructions. They do not edit the app or verify a request.

​
Crush

  1. Connect writes nothing for Crush. Native crushrc is Bash, and legacy crush.json fields are shell-resolved. Keep a backup before editing. Check ~/.config/crush/crushrc on macOS and Linux or %USERPROFILE%\.config\crush\crushrc on Windows. Check XDG_CONFIG_HOME and CRUSH_GLOBAL_CONFIG for location overrides.
  2. For legacy crush.json only, use type: openai-compat and base_url: https://api.runinfra.ai/v1 in providers.runinfra. Review api_key before using ${RUNINFRA_API_KEY:?set RUNINFRA_API_KEY} as its value. For native crushrc, use --type openai-compat, --base-url, and --api-key with an exported variable.
  3. For legacy crush.json, confirm both models.large and models.small use provider runinfra and an exact RunInfra model id. Native model ids use provider/model. Press Ctrl+L to open the model picker. Confirm the intended model there.
  4. Do not guess model limits or capabilities. Review the --context-window and --default-max-tokens limit flags before setting them. Empty openai-compat model lists auto-discover models. Explicit metadata takes precedence over discovered values.
  5. Review project .crushrc, then crushrc, before the global native file. Check legacy .crush.json and crush.json, CRUSH_GLOBAL_DATA, and workspace .crush state for conflicting selections. Data files are application state, not configuration. Do not edit them by hand.
  6. Restart the whole Crush process after reviewing configuration and permissions. Do not use crush run as an automatic verifier. Test only in an isolated disposable environment. Confirm the request destination separately.
  7. To disconnect, undo only the provider, model, and credential changes you made. Alternatively, restore your reviewed backup without discarding later edits. Connect off does not manage Crush files. Keep a shared environment key if another app uses it. Removing it does not revoke it. Connect could not confirm the full legacy crush.json schema, ${RUNINFRA_API_KEY:?set RUNINFRA_API_KEY} expansion, models.large/models.small selection, path and state precedence, discovery completeness, required metadata, parser and reload behavior, changes after saves or crush run permissions against the current Crush documentation; check the configuration guide and run implementation before relying on it.
See Crush for native and legacy configuration, picker checks, discovery limits, permission cautions, and manual restoration. Connect writes no files and prints no automatic verification command.

​
Cursor

  1. Open Cursor Settings > Models. Find OpenAI API Key and Override OpenAI Base URL. Some current Cursor versions make these fields uneditable. Stop if either field cannot be edited.
  2. Set Override OpenAI Base URL to https://api.runinfra.ai/v1. Confirm this destination before entering or verifying your RunInfra key.
  3. Paste your RunInfra API key into OpenAI API Key only after confirming the base URL. Enter the key in Cursor, not in this command. Restore your previous URL or turn the override off before switching keys.
  4. If your version offers Add model, enter each exact RunInfra model id you want to use. Select that exact model in a new chat.
  5. Confirm the request destination for each mode before using it. Do not assume the same routing for Tab, Inline Edit, Agent, or Auto.
  6. Check the selected model and request destination in a new chat. Check that requests use the expected OpenAI-compatible format. This manual path does not establish end-to-end compatibility.
  7. To disconnect, turn off Override OpenAI Base URL and reselect your previous Cursor model. Restore the previous key and base URL values. Remove only the custom entries you added. Removing a saved key does not revoke it. Connect could not confirm a nested API Keys page, per-version save, verification and removal controls, Add model and model-id acceptance, /v1 request compatibility, the override’s scope across other keys, routing for Tab, Inline Edit, Agent and Auto, which requests pass through Cursor’s servers, or restart and saved-setting behavior against the current Cursor documentation; check Cursor’s field-editability report, base URL discussion, and request-format guidance before relying on it.

​
Fx

Current Fx documentation does not show a custom base URL or an OpenAI-compatible provider setting, so Connect has no setup recipe. No Fx settings are changed. Connect could not confirm direct RunInfra setup against the current Fx documentation; check the current Fx documentation before relying on it.

​
Exit codes

​
Troubleshooting