Provider setup
Configure Anthropic, OpenAI, or OpenRouter as your AI provider on SpineOS using your own API key, with no vendor lock-in.
5 min read
Bring your own API key #
SpineOS uses a BYOK (Bring Your Own Key) model: your agent runs on your own API key or AI account, and SpineOS charges no markup on model usage. Where the agent's requests go depends on the agent:
- OpenClaw: straight from the desktop to your provider, with the API key you pasted or the ChatGPT account you connected.
- Claude Code: straight from the desktop to Anthropic, with your Claude credential or Anthropic API key.
- Hermes Agent: straight from the desktop to your provider, with the API key you pasted.
- Codex: straight from the desktop to OpenAI with an OpenAI API key, or in the "ChatGPT — sign in on the desktop" mode. In the "ChatGPT — via SpineOS" mode, its requests go through SpineOS, which talks to ChatGPT for you and keeps your ChatGPT credential on our side.
- Grok: straight from the desktop to xAI, with the account you sign in with there.
Supported providers #
Anthropic #
The provider behind Claude models. Strong at reasoning, coding, and long-context tasks.
API key format: sk-ant-api03-...
Get your key: console.anthropic.com -- go to API Keys and create a new key.
OpenAI #
The provider behind GPT models. Good at general tasks, function calling, and structured output.
API key format: sk-...
Get your key: platform.openai.com -- go to API Keys in your account settings.
OpenRouter #
A unified gateway to 200+ models from multiple providers. Useful if you want access to many models through a single key.
API key format: sk-or-v1-...
Get your key: openrouter.ai -- create an account and generate an API key.
Configuring your provider #
During desktop creation #
- Click "New desktop" in the dashboard.
- In the provider configuration section, select your provider.
- Enter your API key.
- Choose a model (or use the default for that provider).
- Create the desktop.
On an existing desktop #
A provider API key is given to a desktop when it is created, and no setting changes it afterwards. What you can change depends on the agent:
- OpenClaw: on a desktop that runs on a ChatGPT account, the "ChatGPT account" button above the chat opens "ChatGPT account for this desktop", where you switch it to another account you connected in Settings, under ChatGPT. An OpenClaw desktop created with an API key keeps that key: create a new desktop to use a different provider or key.
- Claude Code: if you own the desktop, the Claude button in its toolbar opens "Claude credential for this desktop", where you switch it to another Claude credential you connected in Settings, under Claude. The switch applies at once, or after a restart when the page says "Restart the desktop to apply the new credential".
- Hermes Agent: create a new desktop to use a different provider or API key.
- Codex: on a desktop that runs on a ChatGPT account, the "ChatGPT account" button above the chat opens "ChatGPT account for this desktop", where you switch it to another account you connected in Settings, under ChatGPT. A Codex desktop created with an OpenAI API key keeps that key.
- Grok: there is no key to change. Grok signs in with your xAI account on the desktop itself.
The model is not fixed: when the chat's message box offers a model menu, pick another model there.
Key security #
Your API key is encrypted at rest in the SpineOS database. It is injected into the VM at boot during initialization. The key is not shown in the dashboard UI after you enter it.
SpineOS staff cannot see your API key. If you lose it, you will need to generate a new one from your provider's console.
Verifying your setup #
After the desktop boots, verify the provider configuration by sending a test message in the chat panel. If the agent responds, your provider is configured correctly. The chat's message box shows the desktop's model, and a reply shows the model that wrote it.
Common issues #
| Problem | Cause | Fix |
|---|---|---|
| Agent not responding | Invalid or expired API key | Generate a new key from your provider, then create a new desktop with it |
| "This desktop needs your own AI credential." | The create form has no account or key for the agent you picked | Connect an account or paste an API key in the form, then create the desktop |
| Rate limit errors | Too many requests to the provider | Wait for the limits to reset, or switch to a different model |
| Model not found | Typo in model name or model deprecated | Check the provider's model list and update |
Tips #
- If you are not sure which provider to start with, Anthropic's Claude handles most agent tasks well.
- OpenRouter is handy for experimentation since you can switch models without changing keys.
- Keep your API key confidential. If you suspect it has been compromised, rotate it immediately at your provider's console.