Credentials

How xiantong stores sensitive data securely

xiantong stores API keys, OAuth tokens, and other sensitive credentials in an encrypted file on your machine.

Location#

~/.xiantong/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#

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
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

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 ~/.xiantong/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 ~/.xiantong/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:

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 ~/.xiantong/credentials.enc

File permission errors

Fix permissions:

chmod 600 ~/.xiantong/credentials.enc