studio/DEPLOY.md

Deploying Seqcolyte Studio

Studio is a self-hosted container, not a Vercel/serverless app. It shells out to a real Python + Rust pipeline, spawns long-lived jobs, streams logs over SSE, and persists projects to disk — all of which need a normal server with a writable filesystem, exactly what a container gives you (and what serverless does not).

This is the same model as a typical Flask+Docker app: build one image, run it on any host with Docker, and authenticate to the AI with an API key in .env.

Prerequisites

• Docker (with docker compose).
• An Anthropic API key — https://console.anthropic.com/. In a container the Claude CLI can't use your laptop's claude subscription login, so diagnosis + chat authenticate via ANTHROPIC_API_KEY and bill per token.

Run it locally

cd studio
cp .env.example .env          # then set ANTHROPIC_API_KEY
docker compose up -d --build  # first build takes a few minutes (compiles Rust, builds Next)
# open http://localhost:3000

The build bundles everything: the Next app, the Python pipeline, a Linux-compiled qc-core, the Claude CLI, and the demo data (10x control + adapter-dimer sim + whitelist). Projects/runs/chats persist in the studio-data Docker volume.

Deploy to a host

Any Docker host works — a VM (EC2/GCE/DigitalOcean), Fly.io, Railway, Render, or a container service. Two ways:

1. Build on the host: copy the repo, cd studio, set .env, docker compose up -d --build.
2. Build once, push a tag: docker build -f studio/Dockerfile -t <registry>/seqcolyte-studio . from the repo root, push it, and run that image on the host with the same env + a volume mounted at /data.

Put a TLS-terminating reverse proxy (Caddy/nginx) or the platform's routing in front for HTTPS.

Security (important for public URLs)

The app spawns paid Claude calls and runs a pipeline, and the chat agent can read files in the project store. Before exposing it to the internet, set the built-in basic-auth gate:

STUDIO_AUTH_USER=you
STUDIO_AUTH_PASS=a-long-random-string

With both set, every request needs those credentials (browser handles it for fetch + SSE). Leave them blank only on a trusted private network. Consider also setting a spend limit on your Anthropic key.

Environment variables

Var	Required	Purpose
ANTHROPIC_API_KEY	yes	Claude auth for diagnosis + chat (per-token billing)
SEQCOLYTE_MODEL	no	Model (default claude-opus-4-8)
STUDIO_AUTH_USER / STUDIO_AUTH_PASS	for public	Basic-auth gate
SEQCOLYTE_STUDIO_DATA	no	Project store path (default /data/projects, on the volume)

Notes & limits

• Not Vercel serverless — the filesystem store, detached pipeline processes, and SSE-from-subprocess require a long-running server. Use a container host.
• Scope: this image serves QC + inspect + grounded chat. Running the full pipeline from an uploaded protocol PDF (extract → simulate) is not wired into the UI yet and its heavy docling dependency is omitted to keep the image lean.
• First Claude call in-container: the Claude CLI may need to accept the working directory on first use; if diagnosis/chat error on a fresh deploy, verify the ANTHROPIC_API_KEY is set and reachable from the container.