Skip to main content
Craft Agents stores API keys, OAuth tokens, and other sensitive credentials in an encrypted file on your machine.

​
Location

~/.craft-agent/credentials.enc

​
Encryption

Credentials are encrypted using:
  • Algorithm: AES-256-GCM
  • Key derivation: PBKDF2 with machine-specific seed
  • Security model: Same protection level as OS keychains, without interactive prompts
The encryption key is derived from machine-specific identifiers, meaning the credentials file can only be decrypted on the same machine where it was created.

​
Key Format

Credentials are stored with keys using different formats depending on scope: Global credentials (2-part key): 
{type}::global
Source credentials (3-part key): 
{type}::{workspaceId}::{sourceId}
LLM connection credentials (2-part key): 
{type}::{connectionSlug}
Where type identifies the credential type, workspaceId is the workspace UUID, and sourceId is the source identifier.

​
Credential Types

TypeDescriptionScope
anthropic_api_keyAPI key for the AI provider (Anthropic, OpenRouter, Vercel, or custom)Global
claude_oauthClaude OAuth token (Pro/Max subscription)Global
llm_api_keyAPI key for an LLM connectionPer connection
llm_oauthOAuth token for an LLM connectionPer connection
llm_iamAWS IAM credentials for BedrockPer connection
llm_service_accountGCP service account JSON for VertexPer connection
source_oauthSource OAuth tokenPer source
source_bearerSource bearer tokenPer source
source_apikeySource API keyPer source
source_basicSource basic authPer source
anthropic_api_key and claude_oauth are legacy global credentials. New installations store credentials per LLM connection.

​
Examples

anthropic_api_key::global
claude_oauth::global
llm_api_key::anthropic-api
llm_oauth::claude-max
source_oauth::ws-abc123::github
source_bearer::ws-abc123::api-service

​
Credential Scoping

Credentials are scoped at two levels: 
LLM Connections (2-part key)
  llm_api_key::anthropic-api
  llm_oauth::claude-max

Source (3-part key: type::workspaceId::sourceId)
  source_oauth::ws-abc123::github
  source_bearer::ws-abc123::exa
This means:
  • LLM connection credentials are tied to a specific connection slug
  • Source credentials are specific to a source within a workspace, using the 3-part key format
Legacy global credentials are migrated automatically into LLM connection credentials:
  • anthropic_api_key::global → llm_api_key::anthropic-api
  • claude_oauth::global → llm_oauth::claude-max

​
Viewing Stored Credentials

You can see what credentials are stored (but not their values): 
> /debug
Shows credential identifiers like: 
Credentials:
  anthropic_api_key::global
  source_oauth::ws-abc123::github

​
Managing Credentials

​
Adding Credentials

Credentials are added automatically when you:
  • Complete the setup wizard (API key or OAuth)
  • Connect to a source requiring authentication
  • Authenticate with an MCP server

​
Removing Credentials

To clear all credentials, delete the credentials file: 
rm ~/.craft-agent/credentials.enc
This removes all stored credentials. You’ll need to re-authenticate on next launch.

​
Security Considerations

The credentials file is created with restricted permissions (readable only by your user). Verify with:
ls -la ~/.craft-agent/credentials.enc
# Should show -rw-------
If you backup your home directory, the credentials file is included but encrypted. It cannot be decrypted on a different machine.
When moving to a new machine, you’ll need to re-enter credentials. The encrypted file from your old machine won’t work.
If multiple users share a system account, they share the same credentials file. Use separate user accounts for isolation.

​
Environment Variable Override

For automation or CI environments, you can provide credentials via environment variables:
VariablePurpose
ANTHROPIC_API_KEYAnthropic API key
CRAFT_ANTHROPIC_API_KEYAnthropic API key (takes precedence over ANTHROPIC_API_KEY)
CRAFT_CLAUDE_OAUTH_TOKENClaude OAuth token (for Claude Max subscriptions)
Environment variables take precedence over stored credentials.

​
Troubleshooting

The credential may have been removed or corrupted. Re-enter it:
  • For API keys: Open Settings and re-enter your key
  • For OAuth: Re-authenticate when prompted
This usually means the file was copied from another machine. Delete the credentials file and re-enter credentials:
rm ~/.craft-agent/credentials.enc
Fix permissions:
chmod 600 ~/.craft-agent/credentials.enc