# sorcgcs-server

Local development server for [SorcGCS (Sorceress)](https://sorceress.app) — game preview, file management, AI code agent support, and GPU-powered green screen removal.

## Quick Start

```bash
# Using uv (fastest)
uvx sorcgcs-server

# Using pipx
pipx run sorcgcs-server

# Or install and run
pip install sorcgcs-server
sorcgcs-server
```

One command sets up **everything**:
- The local file server (game preview, file API, agent support)
- The **CorridorKey GPU server** for AutoSprite green screen removal

On first run, CorridorKey setup runs automatically — clones the repo, downloads the model (~300MB), and installs GPU dependencies (PyTorch).

## Options

```
sorcgcs-server --port 8080       # Custom port (default: 8080)
sorcgcs-server --dir ./games     # Serve a specific directory
sorcgcs-server --no-corridorkey  # Skip CorridorKey GPU server
sorcgcs-server --version         # Show version
```

## What It Does

### Local File Server (port 8080)

Lightweight HTTP server (Python stdlib, no dependencies) that provides:

- **Game Preview** — Serve HTML5 games with live reload support
- **File API** — Read, write, list, search, and manage project files
- **FFmpeg Integration** — Audio/video format conversion (if ffmpeg is installed)
- **AI Agent Support** — Endpoints for the SorcGCS AI code agent
- **Checkpoint System** — Create and restore file snapshots

### CorridorKey GPU Server (port 8100)

Neural green screen removal powered by [CorridorKey](https://github.com/nikopueringer/CorridorKey):

- **Auto-setup** — Clones repo, downloads model, installs PyTorch on first run
- **GPU inference** — NVIDIA CUDA, Apple MPS, or CPU fallback
- **Runs alongside** the main server as a background process

Requires: GPU (NVIDIA or Apple Silicon recommended), ~2GB disk, ~4GB VRAM.

## API Endpoints

### Main Server

| Method | Path | Description |
|--------|------|-------------|
| GET | `/api/status` | Server status and config |
| GET | `/api/games` | List available games |
| GET | `/preview/*` | Serve game preview files |
| GET | `/games/*` | Serve game files |
| POST | `/api/read-file` | Read a file |
| POST | `/api/write-file` | Write a file |
| POST | `/api/list-dir` | List directory contents |
| POST | `/api/search-files` | Search files by glob pattern |
| POST | `/api/run-command` | Execute a shell command |
| POST | `/api/create-dir` | Create a directory |
| POST | `/api/delete-file` | Delete a file |
| POST | `/api/rename-file` | Rename/move a file |
| POST | `/api/ffmpeg-process` | Process media with FFmpeg |

### CorridorKey Server

| Method | Path | Description |
|--------|------|-------------|
| GET | `/health` | GPU server health + VRAM info |
| POST | `/process` | Process image for green screen removal |

## Requirements

- Python 3.8+
- No additional dependencies for the file server (uses Python standard library only)
- GPU with CUDA or MPS for CorridorKey (optional — use `--no-corridorkey` to skip)
- FFmpeg (optional, for media processing)

## License

MIT
