Security & Credentials
Relevant source files
The following files were used as context for generating this wiki page:
The Osmosis SDK implements a multi-tiered security model to protect LLM workflows, agent rollouts, and platform interactions. This system encompasses local credential management for CLI users, API key authentication for remote rollout servers, and environment-based secret resolution for third-party LLM providers.
The security architecture ensures that sensitive tokens are stored securely on disk with restricted permissions, while providing flexible authentication mechanisms for both automated services (like the TrainGate) and interactive developer sessions.
Sources: README.md:167-185, osmosis_ai/auth/credentials.py:126-140
CLI Authentication & Workspace Management
Authentication with the Osmosis Platform is handled via an OAuth-based flow. The CLI initiates a browser-based login that returns a workspace-scoped access token.
Credential Storage Architecture
Credentials are stored locally in a JSON-based store located at ~/.config/osmosis/credentials.json. The SDK enforces strict file system permissions (mode 0o700 for the directory and 0o600 for the file) to ensure only the current user can access the secrets.
Sources: osmosis_ai/auth/credentials.py:126-144, README.md:182-185
The following class diagram illustrates the structure of the local credential store:
The storage allows for multiple workspaces to be logged in simultaneously, with one designated as the "active" workspace for outgoing API requests.
Sources: osmosis_ai/auth/credentials.py:13-94
Platform Communication
Requests to the Osmosis Platform utilize the platform_request helper, which automatically injects the active workspace's bearer token and handles authentication failures.
| Feature | Description |
|---|---|
| Automatic Cleanup | If a request returns a 401 Unauthorized, the SDK automatically deletes the invalid credentials from the local store. |
| Expiration Check | The SDK validates the expires_at timestamp before attempting requests to avoid unnecessary network calls with stale tokens. |
| User Agent | All requests include a specialized User-Agent string containing the PACKAGE_VERSION for platform-side auditing. |
Sources: osmosis_ai/auth/platform_client.py:27-105, osmosis_ai/auth/credentials.py:79-86
Remote Rollout Server Security
When running a RolloutServer, security is maintained through a dedicated API key mechanism. This key authenticates requests from the Osmosis TrainGate to the locally hosted agent loop.
API Key Authentication Logic
The rollout server can be configured with an explicit API key or generate one automatically on startup. All incoming requests to protected endpoints (like /v1/rollout/init and /platform/health) must provide this key in the Authorization header.
Sources: osmosis_ai/rollout/server/app.py:155-165, README.md:214-220
Implementation Details
The server uses constant-time string comparison (via validate_api_key) to prevent timing attacks when verifying tokens.
# osmosis_ai/rollout/server/api_key.py
def validate_api_key(provided: Optional[str], expected: str) -> bool:
"""Validate an API key against the expected value."""
if provided is None:
return False
return provided == expected
Sources: osmosis_ai/rollout/server/api_key.py:46-51
LLM Provider Credentials
For rubric evaluation, the SDK delegates credential resolution to environment variables or inline configurations.
Resolution Hierarchy
When using evaluate_rubric, the system resolves API keys in the following order:
- Inline Secret: Provided via
model_info={"api_key": "sk-..."}. - Custom Environment Variable: Provided via
model_info={"api_key_env": "CUSTOM_VAR"}. - Default Environment Variable: Falls back to provider-specific defaults (e.g.,
OPENAI_API_KEY,ANTHROPIC_API_KEY).
If no key is found, the system raises a MissingAPIKeyError with instructions on how to export the necessary secret.
Sources: README.md:58-76
Supported Provider Environment Keys
| Provider | Default Environment Variable |
|---|---|
| OpenAI | OPENAI_API_KEY |
| Anthropic | ANTHROPIC_API_KEY |
| Google Gemini | GEMINI_API_KEY |
| xAI | XAI_API_KEY |
| OpenRouter | OPENROUTER_API_KEY |
| Cerebras | CEREBRAS_API_KEY |
Sources: README.md:65-71
Summary of Security Commands
The CLI provides several commands to manage the security state of the local environment:
| Command | Action |
|---|---|
osmosis login | Initiates OAuth flow and saves credentials to ~/.config/osmosis/. |
osmosis logout | Interactive removal of workspace credentials; can use --all to clear everything. |
osmosis whoami | Displays the current user and highlights active/expired workspaces. |
osmosis workspace switch | Changes the active token used for platform requests. |
Sources: osmosis_ai/cli_commands.py:175-410, README.md:167-195
Conclusion: The Osmosis SDK centralizes security around a workspace-aware credential store and a robust API key validation system for remote rollouts. By strictly managing file permissions and providing clear CLI tools for authentication lifecycle management, the SDK maintains a secure environment for sensitive LLM training data and agent execution.
Sources: osmosis_ai/auth/credentials.py:126-135, osmosis_ai/rollout/server/app.py:110-140