Claude CLI Configuration Architecture

Last Updated: 2025-08-09

Overview

This document describes the secure architecture for managing the Anthropic API key in a single-organization deployment. The key is collected during onboarding, used to configure the Claude CLI on the server, and never stored in the browser. The system includes persistent storage for Docker deployments.

Architecture Principles

Security First

API key is never stored in browser localStorage
API key is never transmitted after initial configuration
All Claude API calls happen server-side via Claude CLI
Single configuration point for the entire organization

Single Organization Model

One API key for all users in the organization
Configured once during initial setup
Can be updated by administrators through settings
Shared Claude CLI instance on the server

Persistent Storage

Configuration persists across server restarts
Docker volumes maintain API key configuration
Automatic environment variable loading on startup
Backwards compatible with existing deployments

System Architecture

┌─────────────────┐     ┌─────────────────┐     ┌─────────────────┐
│                 │     │                 │     │                 │
│  Browser (UI)   │────▶│  Node Server    │────▶│  Claude CLI     │
│                 │     │                 │     │                 │
└─────────────────┘     └─────────────────┘     └─────────────────┘
     No API Key         Uses Environment Var     ANTHROPIC_API_KEY

Implementation Flow

1. Onboarding Phase

graph LR A[User Enters API Key] --> B[Send to Server] B --> C[Server Configures Claude CLI] C --> D[Set ANTHROPIC_API_KEY env var] D --> E[Success Response] E --> F[Continue Onboarding]

2. Normal Operation

graph LR A[User Sends Message] --> B[WebSocket to Server] B --> C[Server Spawns Claude CLI] C --> D[Claude Uses Configured Key] D --> E[Response to User]

API Endpoints

Configure Claude CLI

POST /api/setup/configure-claude

Request:

{
  "apiKey": "sk-ant-..."
}

Response:

{
  "success": true,
  "message": "Claude CLI configured successfully"
}

Actions:

Sets ANTHROPIC_API_KEY environment variable
Persists to config directory .env file
Saves configuration metadata to .claude-config.json
Creates config directory if it doesn't exist
Returns success/failure status

Check Configuration Status

GET /api/setup/claude-status

Response:

{
  "configured": true,
  "lastConfigured": "2024-01-15T10:30:00Z",
  "keyHint": "****-XXXX"  // Last 4 characters only
}

File Changes

Backend Changes

1. New File: `/server/routes/setup.js`

Handles API key configuration
Sets environment variables
Validates API key format

2. Modified: `/server/index.js`

Removes API key from WebSocket messages
Registers setup routes
Simplifies message handling

3. Modified: `/server/claude-cli.js`

Removes client API key acceptance
Uses only server environment configuration
Simplified spawning logic

Frontend Changes

1. Modified: `/src/components/OrganizationSetupScreen.jsx`

Keeps API key input UI
Removes localStorage storage
Calls configuration API instead

2. Modified: `/src/components/ChatInterface.jsx`

Removes localStorage.getItem('ANTHROPIC_API_KEY')
Removes apiKey from message payload
Cleaner message structure

3. Modified: `/src/components/QuickSettingsPanel.jsx`

Adds API Configuration section (admin only)
Shows configuration status
Allows reconfiguration

Security Benefits

Before (Client Storage)

API key visible in browser DevTools
API key in localStorage (persistent XSS risk)
API key transmitted with every message
Each client manages its own key

After (Server Configuration)

API key never reaches browser
API key only transmitted once during setup
Server-side environment variable storage
Single point of configuration

Deployment Considerations

Docker Deployment

# Set via environment variable
ENV ANTHROPIC_API_KEY=${ANTHROPIC_API_KEY}

# Or mount .env file
VOLUME ["/app/.env"]

Production Deployment

Docker with Persistent Volumes

# Using docker-compose (recommended)
docker-compose up -d

# Configuration persists in sasha-config volume
docker volume inspect sasha-config

Manual Configuration

# Set environment variable on server
export ANTHROPIC_API_KEY="sk-ant-..."

# Or use .env file in config directory
echo "ANTHROPIC_API_KEY=sk-ant-..." >> /app/config/.env

Development

# Local .env file
ANTHROPIC_API_KEY=sk-ant-dev-key...

Migration Guide

For Existing Users

On next login, prompt for API key if not configured
Remove old localStorage entries
Configure server-side Claude CLI
Continue normal operation

Clean Up localStorage

// Run once during migration
if (localStorage.getItem('ANTHROPIC_API_KEY')) {
  // Send to server for configuration
  await configureClaudeCLI(localStorage.getItem('ANTHROPIC_API_KEY'));
  // Remove from browser
  localStorage.removeItem('ANTHROPIC_API_KEY');
}

Error Handling

Configuration Errors

Invalid API key format → Clear error message
Network failure → Retry with exponential backoff
Server error → Log and provide user feedback

Runtime Errors

Claude CLI not configured → Prompt admin to configure
API key invalid → Show configuration needed message
Rate limits → Pass through Claude's error messages

Admin Features

Settings Panel

View configuration status
Update API key (with validation)
Test configuration
View last configuration date

Monitoring

Log API key configuration changes
Track configuration errors
Monitor Claude CLI health

Testing Strategy

Unit Tests

API key format validation
Configuration endpoint logic
Error handling paths

Integration Tests

Full onboarding flow
Message sending without API key
Configuration persistence

Security Tests

Verify no API key in browser storage
Verify no API key in network traffic
Verify environment variable is set correctly

Rollback Plan

If issues arise after deployment:

# Revert to checkpoint
git reset --hard 7f273c0

# Or temporarily add fallback
if (!process.env.ANTHROPIC_API_KEY) {
  // Fallback to client-provided key
  process.env.ANTHROPIC_API_KEY = data.apiKey;
}

Benefits Summary

Enhanced Security: API key never exposed to client
Simplified Architecture: One configuration for all users
Better UX: Users don't manage API keys
Easier Maintenance: Single point of update
Compliance Ready: Follows security best practices
Cost Control: One organizational key with proper quotas
Persistent Configuration: Survives container restarts
Zero Downtime Updates: Configuration maintained during deployments