Troubleshooting.

Installation

1. Confirm macOS 14+ and your processor in About This Mac. Download Apple Silicon for an M-series Chip or Intel for an Intel Processor.
2. If the DMG fails to open, download it again from Install or the latest GitHub release. Compare the SHA-256 with the release’s checksum when available.
3. Move Gyro.app to Applications. For a blocked first alpha launch, use System Settings → Privacy & Security → Open Anyway for Gyro. Keep Gatekeeper on.

Resolved: Gyro opens from Applications.

CLI availability and login

1. Open your terminal and confirm that the chosen provider’s CLI starts. If it is missing, follow its official installation guide.
2. Complete its login in the terminal and check that a simple task works there. A revoked login or subscription issue must be resolved with the provider.
3. Quit and reopen Gyro after installation. Enable the CLI in Settings → Providers, then choose it in a project session.

Resolved: the provider starts a task in Gyro. If it works in the terminal but not Gyro, include that difference in your support report.

API connection

No API key

Save a key for the selected provider. Check whether an environment variable overrides it.

HTTP 401

The provider rejected the key. Check the account, key, and endpoint. Replace the key if required; never share it in a support report.

Connection error

Check the network and final base URL. Remote endpoints need HTTPS. Redirects and URLs with embedded credentials are not accepted.

No models

Check the API prefix. Model discovery uses {base URL}/models. If discovery is unsupported, enter a model ID documented by the service.

Usage or model access error

Check the provider’s billing balance, rate limits, and access to that model.

Resolved: your selected model answers a small task. Review API setup.

Missing Ollama models

1. Start Ollama on your Mac. Confirm that the local service is running.
2. Check your downloaded models in Ollama. Finish downloading a model before refreshing Gyro.
3. Use Refresh models beside Ollama in Settings → Providers, then choose a model in the chat picker.
4. If a model is too slow or fails to load, try a smaller model that fits your memory.

Resolved: a downloaded model appears and answers a task. Review Ollama setup.

Get support

If the problem continues, include these non-secret details:

• Gyro release, and macOS version.
• Processor: Apple Silicon or Intel.
• Provider and model, plus the step that failed.
• The error message, with keys, tokens, and private file contents removed.

Describe whether the provider works outside Gyro. Share a minimal reproduction when possible.