Troubleshooting · Rusty IDE

The window opens off-screen or at a strange size

At launch, Rusty checks the restored window against the displays that are connected. If the size is unusable or the title bar is unreachable, it opens a default-sized window on an available display instead. Valid window geometry is kept, and fullscreen is never restored automatically.

Window display does not wait for the interface to finish loading, so configuration and workspace startup checks can show their own progress and recovery controls. Recovery diagnostics are written to standard error with the [startup/window] prefix, which helps when you report a problem.

If a startup step fails, Rusty shows a banner and retry controls rather than leaving you on a blank screen.

A model does not appear in the picker

Open LLM Integrations, select the provider and fetch its model catalog again.
Check the Connection Base URL. For OpenAI-compatible servers it normally ends in /v1, for example http://localhost:11434/v1 for Ollama.
If your server lists models somewhere other than {base URL}/models, set the Model Catalog URL.
For a custom provider, make sure the model names in Models match what the server reports.

An API key seems to be ignored

A blank key falls back to an environment variable such as OPENAI_API_KEY, but apps launched from Finder or the Dock do not see variables exported in your shell profile. Paste the key into the provider's API Authorization Key field instead.
Confirm the Default API Protocol and Authentication match the service. Anthropic uses Anthropic Messages with Anthropic x-api-key.
GitHub Models needs a personal access token with the models:read scope.

Claude models are not available

Claude models are reached with an Anthropic API key, through the Anthropic provider. Signing in with a Claude subscription is not supported.

The first sign-in downloads that provider's runtime, so you need an internet connection. If the download fails, sign in again to retry.
Use Cancel, then Sign in again if a sign-in seems stuck.
Expand Authentication diagnostics and use Copy Diagnostics to capture details.
Available models depend on your subscription and, for Copilot, your organization's policy.

My keys disappeared, or settings will not save

Secrets are encrypted with a key held in the macOS Keychain. See Data, storage & privacy:

If the Keychain is locked, Rusty will not save over your existing configuration during that session. Unlock the Keychain and restart Rusty.
If the Keychain entry was reset, Rusty cannot decrypt the old data. It keeps the old data aside and starts fresh, and Settings → System → Storage & Cache tells you to re-enter your tokens.

A command was denied and the agent is stuck

If you chose Deny, the agent is told and should try another approach. If it keeps retrying the same command, stop the run and rephrase the request, or add a deny rule with a clear reason to the profile so it knows what to do instead.

Auto does not appear, or a workflow does not switch

The Auto entry needs OpenRouter and a JEV decision model, and flow switching needs its checkbox on and a workflow that lists where it may hand over to. See Troubleshooting Auto flows.

A stage did not use the last result

A stage builds on the last result in the same chat. A new chat starts clean, and Plan, build, verify does not read it. See Steer a long job between stages.

An update will not install

Check under Settings → System → Software Update.
If you installed with Homebrew, run brew upgrade --cask rusty-ide.
Otherwise download the latest DMG from the download page and replace the app in Applications.

Rusty is using a lot of disk space

Open Settings → System → Storage & Cache and use Delete Cache. It clears the WebView cache, process logs and local execution telemetry without touching your workspaces, project files or settings.

Still stuck?

Open an issue on GitHub and include your macOS version, the Rusty version (from Settings → System) and any diagnostics you copied.