Quickstart

This guide gets Sandcut running locally without changing the existing Worker deployment path.

Deployment model

Use two independent services:

• Application service: the existing Worker + Container deployment from the repo root
• New Sandcut service: a second Worker + Container deployment using wrangler.sandcut.toml
• Documentation service: a separate Cloudflare Pages project built from apps/docs

This keeps docs releases completely isolated from media processing releases.

Prerequisites

• Node.js 20+
• Cloudflare account with Workers, Containers, Durable Objects, KV, and R2
• Wrangler authentication already configured locally

Install the application

npm install
cp .dev.vars.example .dev.vars

Run the application locally

npm run dev

Run the new Sandcut service locally

npm run dev:sandcut

Create a bearer token

wrangler kv key put --binding=AUTH_KV "your-secret-token" "active" --remote

Test a processing request

curl -X POST http://127.0.0.1:8787/video/process \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer your-secret-token" \
  -d '{
    "input_url": "https://example.com/video.mp4",
    "ffmpeg_args": ["-vf", "scale=640:360", "-c:v", "libx264"],
    "seek": { "mode": "hybrid", "start": 30, "duration": 8 }
  }'

Start the docs app

The docs app lives in apps/docs and is intentionally isolated from the root package.

cd apps/docs
npm install
npm run dev

Build and deploy the docs app

cd apps/docs
npm run build
npm run deploy

The deploy script targets the separate Pages project sandcut-docs.

Configure your own Cloudflare resources

Before deploying publicly, replace placeholder values in wrangler.toml or wrangler.sandcut.toml with your own:

• CDN_DOMAIN
• OUTPUT_BUCKET.bucket_name
• AUTH_KV.id

Deploy the new Sandcut Worker + Container service

npm run build:sandcut
npm run deploy:sandcut

This deploys a separate Worker named sandcut-video-sandbox and does not overwrite the existing application service.