Ollama Cloud Authentication
Relevant source files
The following files were used as context for generating this wiki page:
Ollama Cloud Authentication is the mechanism used by the ollacc tool to securely connect Claude Code directly to the Ollama Cloud API at https://ollama.com. This system bypasses the need for a local Ollama server by managing API keys and configuring the Anthropic SDK environment variables to route requests through Ollama's OpenAI-compatible endpoint.
The authentication process involves capturing a user's Ollama Cloud API key, persisting it with restricted filesystem permissions, and exporting specific environment variables required by the Anthropic SDK.
Sources: README.md:10-18, lib/auth.sh:22-38
Authentication Architecture and Workflow
The authentication flow is designed to be "just-in-time." If a valid token is not found in the configuration during execution, the system interrupts the flow to prompt the user for credentials.
Authentication Process Flow
The following diagram illustrates the sequence of checking, prompting, and saving the authentication token.
The system ensures that the API key is requested only when necessary and is stored securely for subsequent runs.
Sources: lib/auth.sh:7-14, lib/auth.sh:19-24, lib/auth.sh:45-50
Credential Storage and Security
API keys and configuration settings are stored in a dedicated configuration file. Security is enforced through filesystem permissions to ensure that sensitive tokens remain private.
| Attribute | Value | Description |
|---|---|---|
| Config Directory | ~/.ollacc/ | Permissions: chmod 700 (Owner only) |
| Config File | ~/.ollacc/config | Permissions: chmod 600 (Owner only) |
| Auth Variable | ANTHROPIC_AUTH_TOKEN | The Ollama Cloud Bearer token |
| Base URL | ANTHROPIC_BASE_URL | Defaulted to https://ollama.com |
Sources: install.sh:35-36, install.sh:65, lib/auth.sh:13-14
Secure Configuration Updates
The config_set function in lib/config.sh manages writing the token to the configuration file. It uses bash_escape to sanitize the input, preventing shell injection or corruption when the configuration file is sourced in future sessions.
# Example of config_set usage for auth
config_set ANTHROPIC_AUTH_TOKEN "$NEW_KEY"
Sources: lib/config.sh:41-70, lib/auth.sh:47
SDK Environment Integration
To facilitate the connection between Claude Code and Ollama Cloud, the system exports specific environment variables that the Anthropic SDK recognizes. A critical requirement for this integration is the handling of the ANTHROPIC_API_KEY variable.
Required Environment Variables
| Variable | Value | Purpose |
|---|---|---|
ANTHROPIC_BASE_URL | https://ollama.com | Redirects SDK to Ollama Cloud |
ANTHROPIC_AUTH_TOKEN | [User Token] | Provides the Bearer token for auth |
ANTHROPIC_API_KEY | "" (Empty) | Force SDK to use AUTH_TOKEN instead |
Per Ollama issue #13854, if ANTHROPIC_API_KEY is not explicitly empty, the Anthropic SDK may ignore the ANTHROPIC_AUTH_TOKEN, causing authentication failures.
Sources: lib/auth.sh:58-62, README.md:144-152
Management and Maintenance
The system provides built-in mechanisms to clear or refresh authentication credentials.
Credential Reset
Users can clear their stored API key using the --key-clear flag. This invokes the config_unset function, which removes the ANTHROPIC_AUTH_TOKEN line from the configuration file while preserving other settings and comments.
Sources: lib/flags.sh:18-26, lib/config.sh:75-87
Troubleshooting Authentication
The system handles common authentication errors:
- 401 Unauthorized: Typically indicates a bad token. Users are advised to run
ollacc --key-clearto re-trigger the prompt. - Catalog Verification: The system uses the token to fetch the authenticated catalog from
https://ollama.com/api/tagsto ensure the user has access to specific models.
Sources: README.md:113-115, lib/catalog.sh:31-38
Summary
Ollama Cloud Authentication provides a secure, streamlined path for Claude Code to access Ollama Cloud. By managing environment variables and local credential storage with strict permissions, it ensures that users can interact with cloud models without the overhead of a local Ollama server, while maintaining standard security practices for API key management.