CLI troubleshooting
Updated
Ask your agent to run runinfra doctor --json first. It changes nothing and sends no paid check.
| Connection | Value |
|---|---|
| Control site | https://runinfra.ai |
| Command | runinfra |
| Sign-in | Approve the device code in your browser. Keep your API key out of agent chat. |
| Billing | The existing funding rules of your open-model account. |
If you see
| What you see | Do this |
|---|---|
| No eligible workspace or Not available for this role | A workspace owner must approve. |
| The wrong workspace | Switch workspaces in the open-models service and reload the approval page. |
| The code expired | Ask your agent for a new code. |
| Your agent cannot run commands | Leave plan or read-only mode. In Codex, approve running outside its sandbox. |
| Your agent asks for a key | Do not paste it. Point your agent to the setup instructions. |
Browser sign-in is unavailable | Use manual setup. Keep keys out of the chat. |
Add credits in Billing before connecting. | Add credits in Billing before approving a connection. |
| The new command is not found | Step-by-step setup adds the folder to PATH; open a new terminal. If needed, run the full path your agent gave or add ~/.config/runinfra/bin to PATH (%LOCALAPPDATA%\ on Windows). |
| Inside is refused from a separate command's terminal | Open a normal terminal outside claude-run or codex-run and try again. |
| You still see the old model | Start the new command, pick an open-models service model, or fully restart as instructed. A paid check does not change your current chat. |
| Goose or Zed has no key | Load the environment file your agent names and restart the app from that same terminal. Follow Goose or Zed. |
| One project uses another model | Check that project's settings, environment files and launch flags. |
| The paid check failed after saving | Fix the reported billing or network problem, then ask for Doctor. Approve a fresh plan before another attempt. |
This key's payer is set by the workspace owner. | Ask the workspace owner. |
| The name is taken | Choose another name with --name. |
Codes your agent reports
| Code | Next step |
|---|---|
usage | Read the message and runinfra help --json. |
agent_not_installed | Install and start the chosen agent, then run runinfra agents --json. |
not_found | Read the named resource's message; plan information may be unavailable. |
not_entitled | Read the plan and credits before another paid action. |
network, server_error, rate_limited | Wait for the returned retry delay. |
config_modified without refused[] | Changed settings: follow the recovery below. Changed pending sign-in: repeat the device command and read its returned code. Unsafe pending read: review runinfra logout --local --json; after approval add --yes. Local logout does not revoke server access; revoke the old terminal key in Settings > API keys. |
storage_unwritable, disk_space | Have the person fix the reported access or disk space. |
checksum_mismatch, artifact_changed, range_mismatch | Stop and follow the reported recovery. Never overwrite files yourself. |
interrupted, batch_incomplete | Read saved changes and run Doctor. Never repeat a failed --yes directly. |
unexpected | Stop and report the message. |
Plan coverage unavailable. Refresh Models. | Read runinfra models --harness <agent> --json and runinfra plan --json again. |
After any failed or interrupted --yes, prepare a fresh review without --yes, show it and wait for a new yes.
Windows sign-in privacy warning
These steps are for you. Your agent must not open credential files or change permissions. With storage.restricted: false, keep the saved sign-in and inspect the named path with Get-Acl; privacy is unconfirmed. If saving failed, revoke only the unsaved terminal key named in the notice in Settings > API keys. Run runinfra whoami --json to check the sign-in still saved. Fix access before signing in again; repeated approvals can leave more unsaved keys.
You edited the agent's settings
Keep any edits, sessions and history you need. Ask your usual agent to review runinfra disconnect <name> --force --json. It saves managed files for recovery; deleting a separate command also deletes its sessions and history. Approve only the files and key revocations you intend. Recovery copies can contain keys; keep them private.
Finish a key revocation
Doctor names the key and recovery command. Restore connections that still use it, then review runinfra keys revoke --id <keyId> --json. Add --yes only after approval. Pending revocations are not retried automatically.