Credentials

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

Type	Description	Scope
`anthropic_api_key`	API key for the AI provider (Anthropic, OpenRouter, Vercel, or custom)	Global
`claude_oauth`	Claude OAuth token (Pro/Max subscription)	Global
`llm_api_key`	API key for an LLM connection	Per connection
`llm_oauth`	OAuth token for an LLM connection	Per connection
`llm_iam`	AWS IAM credentials for Bedrock	Per connection
`llm_service_account`	GCP service account JSON for Vertex	Per connection
`source_oauth`	Source OAuth token	Per source
`source_bearer`	Source bearer token	Per source
`source_apikey`	Source API key	Per source
`source_basic`	Source basic auth	Per source

Examples

anthropic_api_key::global
claude_oauth::global
llm_api_key::anthropic-api
llm_oauth::claude-max
llm_iam::bedrock
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

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

File permissions

The credentials file is created with restricted permissions (readable only by your user). Verify with:

ls -la ~/.craft-agent/credentials.enc
# Should show -rw-------

Backup considerations

If you backup your home directory, the credentials file is included but encrypted. It cannot be decrypted on a different machine.

Machine migration

When moving to a new machine, you’ll need to re-enter credentials. The encrypted file from your old machine won’t work.

Shared accounts

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:

Variable	Purpose
`ANTHROPIC_API_KEY`	Anthropic API key
`CRAFT_ANTHROPIC_API_KEY`	Anthropic API key (takes precedence over `ANTHROPIC_API_KEY`)
`CRAFT_CLAUDE_OAUTH_TOKEN`	Claude OAuth token (for Claude Max subscriptions)

Environment variables take precedence over stored credentials.

Troubleshooting

Credential not found errors

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

Cannot decrypt credentials

This usually means the file was copied from another machine. Delete the credentials file and re-enter credentials:

rm ~/.craft-agent/credentials.enc

File permission errors

Fix permissions:

chmod 600 ~/.craft-agent/credentials.enc