Skip to main content
Catty connects your local terminal to Claude Code running in isolated cloud machines. Here’s how all the pieces fit together.

​
Architecture

The catty CLI on your machine communicates with the Catty API to provision isolated session machines in the cloud. Each session machine runs Claude Code in a PTY. Your terminal connects directly to Claude Code via WebSocket, streaming input and output in real-time. File changes sync back to your local directory, and workspaces are periodically saved to cloud storage for persistence.

​
Components

The command-line tool you install via npm. It handles:
  • User authentication
  • Creating and managing sessions
  • Uploading your workspace
  • WebSocket connection for terminal streaming
  • Real-time sync-back of file changes
  • Encrypted secrets management
The hosted API server. It handles:
  • User authentication and session management
  • Provisioning cloud machines
  • Presigned URLs for workspace downloads
  • Billing and quota management
The runtime environment for each session. It handles:
  • Receiving workspace uploads
  • Running Claude Code in a PTY
  • WebSocket relay for terminal I/O
  • File watching for sync-back
  • Periodic workspace saves to cloud storage
Secure storage for workspace persistence:
  • Receives workspace snapshots every 30 seconds
  • Enables downloads via presigned URLs
  • Survives session termination

​
Data Flow

​
Session Creation

  1. catty new calls the API
  2. API provisions a cloud machine
  3. Machine starts and reports ready
  4. CLI zips your workspace (respecting .gitignore)
  5. Workspace uploads to session machine
  6. WebSocket connection established
  7. Claude Code spawns in a PTY
  8. Terminal I/O streams bidirectionally

​
File Sync-Back

  1. Claude modifies a file in /workspace
  2. File watcher detects the change
  3. Change sent over WebSocket as JSON message
  4. CLI validates path (security check)
  5. File written to your local directory

​
Cloud Persistence

  1. Session saves workspace every 30 seconds
  2. Tarball uploaded to cloud storage
  3. When you run catty download:
    • API generates presigned URL
    • CLI downloads directly from cloud storage
    • Extracts to your local directory

​
Security

AspectImplementation
AuthenticationOAuth via browser, tokens stored locally
SecretsAES-256-GCM encrypted, machine-bound
TransportHTTPS for API, WSS for WebSocket
IsolationEach session runs in its own machine
File accessSessions can only access /workspace