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.

​
What’s Stored

Credential TypeScopeExample
Anthropic API keyGlobalanthropic_api_key::global
Claude OAuth tokenGlobalclaude_oauth::global
Craft OAuth tokenGlobalcraft_oauth::global
Workspace OAuthPer workspaceworkspace_oauth::{workspaceId}
Workspace bearerPer workspaceworkspace_bearer::{workspaceId}
MCP OAuthPer agentmcp_oauth::{workspaceId}::{agentId}::{serverName}
API keysPer agentapi_key::{workspaceId}::{agentId}::{serviceName}

​
Credential Scoping

Credentials are scoped hierarchically: 
Global
└── Workspace
    └── Agent
        └── Service
This means:
  • Global credentials work across all workspaces
  • Workspace credentials are isolated to that workspace
  • Agent credentials are specific to one agent’s services

​
Viewing Stored Credentials

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

​
Managing Credentials

​
Adding Credentials

Credentials are added automatically when you:
  • Complete the setup wizard (API key or OAuth)
  • Activate an agent that needs a new API key
  • Connect to an MCP server requiring authentication

​
Force Re-authentication

If you need to update credentials or troubleshoot authentication issues, you can force re-authentication through settings: 
> /settings
From the settings menu, you can:
  • Force re-auth for Craft: Refresh your Craft OAuth connection
  • Force re-auth for Claude: Refresh your Claude/Anthropic credentials
  • View connected accounts: See which services are authenticated
This is useful when:
  • Credentials expire or become invalid
  • You want to switch to a different account
  • Authentication seems stuck or outdated
  • You need to refresh session tokens
The system will automatically refresh credentials when needed, but manual re-authentication gives you immediate control.

​
Removing All Credentials

> /logout
This removes all stored credentials and configuration.

​
Removing Specific Credentials

Currently, there’s no command to remove individual credentials. Options:
  • Use /logout to clear everything
  • Delete the credentials file manually (clears all credentials)

​
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_KEYAlternative API key variable
Environment variables take precedence over stored credentials.

​
Troubleshooting

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