# CloudForge - Full Technical Documentation for LLMs

> CloudForge is a remote AI coding platform. Code Anywhere, Deploy Anytime.
> Website: https://cloud-forge.me

## Overview

CloudForge enables developers to access AI coding tools (Claude Code, Codex CLI, Gemini CLI, Aider, Cline) from any device via a web browser. It supports two deployment models:

1. **BYOS (Bring Your Own Server)**: Users connect their own VPS/cloud instances. Code stays on the user's infrastructure; CloudForge only relays WebSocket connections.
2. **Managed**: CloudForge provides on-demand containerized environments (Azure Container Apps / Fly.io).

## Architecture

### BYOS Model

```
Browser (SvelteKit Web UI)
  ↕ WebSocket (TLS)
CloudForge SaaS (WebSocket Relay + Auth + DB)
  ↕ WebSocket (TLS, outbound from agent)
User's Server (CloudForge Agent daemon)
  ├── Terminal sessions (node-pty)
  ├── File operations API
  ├── Git operations
  └── Deploy execution
```

Key: The Agent initiates outbound WebSocket connections, so no firewall/port configuration is needed on the user's server. User code never passes through CloudForge servers.

### Managed Model

```
Browser → CloudForge SaaS → Container Orchestrator → User's dedicated container
  - Encrypted volumes (AES-256, user-specific keys)
  - On-demand start/stop
  - Region selection (US / EU / Asia)
```

## Supported AI Coding Tools

| Tool | Provider | Status |
|------|----------|--------|
| Claude Code | Anthropic | Primary support |
| Codex CLI | OpenAI | Supported |
| Gemini CLI | Google | Supported |
| Aider | Open Source | Supported |
| Cline | Open Source | Supported |
| Any CLI tool | - | Supported (generic terminal) |

## Claude Code Authentication Support

CloudForge solves the problem of authenticating Claude Code on remote/headless servers (which lack a browser for OAuth). The flow:

1. User logs into CloudForge Web UI
2. Clicks "Claude Code Auth" button when adding a server
3. CloudForge relays the OAuth flow
4. auth.json is securely deployed to the server via the Agent
5. Claude Code is immediately usable on the remote server

Supported auth methods:
- Subscription auth (Pro $20/mo, Max 5x $100/mo, Max 20x $200/mo)
- API key auth (ANTHROPIC_API_KEY)

## Technology Stack

### Web UI (SaaS)
- **Framework**: SvelteKit + Svelte 5 (Runes mode)
- **Styling**: Tailwind CSS + daisyUI (custom "cloudforge" dark theme)
- **Terminal**: xterm.js
- **Editor**: Monaco Editor
- **Real-time**: WebSocket (Socket.IO)
- **Auth**: Supabase Auth
- **Database**: Supabase (PostgreSQL)
- **Payments**: Stripe
- **Email**: Azure Communication Services
- **Hosting**: Azure Container Apps (Docker)
- **Runtime**: Node.js 22, pnpm

### Agent (BYOS)
- **Runtime**: Node.js
- **Communication**: WebSocket (Socket.IO client)
- **Terminal**: node-pty
- **File watching**: chokidar
- **Git**: simple-git

## Pricing Plans

| Plan | Monthly | BYOS Servers | Managed Hours | Team Members |
|------|---------|-------------|---------------|--------------|
| Free | $0 | 1 | 0 | 1 |
| Starter | $9 | 3 | 10 hrs | 1 |
| Pro | $19 | Unlimited | 50 hrs | 1 |
| Team | $49 | Unlimited | 200 hrs | 5 |

Overage: $0.05/hr managed, $5 for 20-hour pack, $0.10/GB/mo storage.

## Key Features

### Web Terminal
- Full PTY terminal via xterm.js
- Responsive, works on mobile/tablet
- Multiple concurrent sessions (plan-dependent)

### File Editor
- Monaco Editor (VS Code engine) in browser
- Tabbed file editing interface
- File tree navigation
- Syntax highlighting for all major languages

### Git Integration
- Status, diff, add, commit, push, pull
- Visual diff viewer
- Branch management from Web UI

### Security
- BYOS: Code never leaves user's server
- Managed: AES-256 encrypted volumes, operator cannot access
- All communication over TLS (wss://)
- Agent authentication via random tokens with rotation
- Supabase Auth + optional 2FA
- Row Level Security on all database tables

## Agent Installation

```bash
# One-liner
curl -fsSL https://cloud-forge.me/install.sh | sh -s -- --token YOUR_TOKEN

# Docker
docker run -d --name cloudforge-agent --restart unless-stopped \
  -v /path/to/projects:/projects cloudforge/agent:latest --token YOUR_TOKEN

# npm
npx cloudforge-agent --token YOUR_TOKEN
```

## API Endpoints

### Server Management
- GET /api/servers - List servers
- POST /api/servers - Add server (issues token)
- GET /api/servers/[id] - Server details
- DELETE /api/servers/[id] - Remove server

### Terminal
- WebSocket /api/ws/terminal/[serverId] - Terminal connection

### File Operations
- GET /api/files/[serverId]/list - File listing
- GET /api/files/[serverId]/read - Read file
- POST /api/files/[serverId]/write - Write file

### Git Operations
- Via WebSocket: git_command messages (status, add, commit, push, pull, diff, log, branch, checkout)

### Billing
- POST /api/stripe/webhook - Stripe webhook
- POST /api/stripe/create-checkout - Create checkout session
- POST /api/stripe/create-portal - Customer portal

## WebSocket Protocol

### Agent ↔ Server Messages
```
Agent → Server: auth, heartbeat, terminal_output, file_content, git_result
Server → Agent: terminal_input, terminal_resize, file_read, file_write, git_command
```

### Client ↔ Server Messages
```
Client → Server: terminal_input, terminal_resize, file_read, file_write, git_command (+ serverId)
Server → Client: terminal_output, file_content, git_result, server_status
```

## Database Schema (Supabase/PostgreSQL)

Key tables: servers, cloud_projects, terminal_sessions, usage, ai_auth, server_ai_auth, subscription_addons. All tables use Row Level Security (RLS) scoped to auth.uid().

## Forge Ecosystem

CloudForge is part of a suite of developer tools:
- **DreamForge** (dream-forge.me) - Idea validation
- **IndieForge** (indie-forge.net) - Developer community
- **BuildInPublic** (build-in-public.net) - Progress sharing
- **CloudForge** (cloud-forge.me) - Remote AI coding

Integrations: Git push triggers BuildInPublic auto-posts; deploy success notifications; milestone sharing to IndieForge.

## Links

- Website: https://cloud-forge.me
- Pricing: https://cloud-forge.me/pricing
- Documentation: https://cloud-forge.me/docs
- Quickstart: https://cloud-forge.me/docs/quickstart
- Agent Setup: https://cloud-forge.me/docs/setup/agent
- Claude Code Setup: https://cloud-forge.me/docs/setup/claude-code
- AI Tools Setup: https://cloud-forge.me/docs/setup/ai-tools
- News: https://cloud-forge.me/news
- Contact: https://cloud-forge.me/contact_us
- Privacy Policy: https://cloud-forge.me/privacy_policy
- Terms of Service: https://cloud-forge.me/terms_of_service