Docs · Reference
Run Sift in the cloud
Beta, for studios that want to run Sift on a server: you review in a web browser and edit on your own machine.
For studios that want to run Sift on a server, next to their footage, instead of on a Mac. This page is technical: it’s written for whoever sets up your servers.
Beta The Linux server is in beta. The Mac app is the supported way to run Sift.
Sift also runs as a headless server on Linux: no window, no browser of its own. Agents drive it over MCP, and it runs the heavy work in batches (scans, transcription, labeling, rough cuts) next to your footage. You open its web UI from any browser to review. There is no Linux desktop app.
Premiere Pro doesn’t run on the server. Export on the server, download the XML, and import it on your editing machine (see Export and edit on your own machine).
What you need
- A Linux machine, x64 or arm64, with glibc 2.35 or later (Debian 12, Ubuntu 22.04 or newer), or Docker.
- 4 or more CPU cores and 8 GB of memory. Transcription runs whisper.cpp on the CPU, which is slower than on a Mac’s GPU. More cores make it faster.
- Disk for Sift’s data (about 1 GB for the tools and the Whisper model, plus the cache) and for the exports.
- Your footage on a disk the server can read (see Footage).
- An Anthropic or OpenRouter API key.
Run it with Docker
The image is ghcr.io/yourbuddyconner/sift, for linux/amd64 and linux/arm64. It runs as a non-root user (uid 10001).
export SIFT_TOKEN="$(openssl rand -hex 32)" # keep it: your browser and your agents use it
export SIFT_LICENSE="sift_lic_…" # your license key
docker run -d --name sift -p 127.0.0.1:4947:4947 \
-e SIFT_TOKEN -e SIFT_LICENSE -e SIFT_ALLOWED_HOSTS=localhost -e SIFT_AGENT_ACCESS=1 -e OPENROUTER_API_KEY \
-v sift-data:/data -v /path/to/footage:/media:ro -v sift-exports:/exports \
--stop-timeout 30 \
ghcr.io/yourbuddyconner/sift:latest
Then open http://localhost:4947/?t=<your token>. The first start unpacks the tools, so it takes a minute to report healthy.
docker-compose.example.yml in the repository does the same with Docker Compose.
| Path in the container | What it holds |
|---|---|
/data |
The database, the unpacked tools, the Whisper model, the key file and the logs (SIFT_DATA_DIR) |
/media |
Your footage, mounted read-only. Any other path works too. |
/exports |
Exported XML, captions and sidecars (SIFT_OUTPUT_DIR) |
Run the binary
Download sift-<version>-linux-x64.tar.gz or sift-<version>-linux-arm64.tar.gz from the release and check it against SHA256SUMS.txt:
sha256sum -c SHA256SUMS.txt --ignore-missing
tar -xzf sift-<version>-linux-x64.tar.gz
export SIFT_TOKEN="$(openssl rand -hex 32)"
./sift-<version>-linux-x64/sift --host 0.0.0.0 --port 4947
On Linux, Sift starts headless by default. It keeps its data in ~/.local/share/sift (or $XDG_DATA_HOME/sift). To run it as a service, give it a systemd unit with Restart=on-failure and the environment below. Sift stops cleanly on SIGTERM.
Settings
Flags win over environment variables.
| Flag | Variable | Default | What it does |
|---|---|---|---|
--headless, --no-headless |
SIFT_HEADLESS=1 or 0 |
On for Linux | No browser, no folder picker, Finder or Premiere |
--host |
SIFT_HOST |
127.0.0.1 |
The address to listen on. 0.0.0.0 for every interface. |
--port |
SIFT_PORT |
4947 headless |
The port. 0 picks a free one. |
SIFT_TOKEN |
A new token at each start | The access token. Required when the host is not 127.0.0.1: at least 32 characters. | |
SIFT_LICENSE |
None | Your license key (sift_lic_…). Without one, the API and /mcp answer 403 license_required until you add it in the browser. SIFT_INVITE works too. |
|
SIFT_ALLOWED_HOSTS |
None | Host names the browser or a proxy uses to reach Sift, comma separated | |
SIFT_DATA_DIR |
~/.local/share/sift |
Where Sift keeps its data | |
SIFT_OUTPUT_DIR |
None | Where events export when Settings names no folder | |
SIFT_AGENT_ACCESS=1 |
Off | Turns on Settings → Agent access at start | |
OPENROUTER_API_KEY, ANTHROPIC_API_KEY |
None | The model provider’s key | |
SIFT_STOP_TIMEOUT_MS |
25000 |
How long a stop waits for running work |
sift --help lists them. sift healthcheck exits 0 while the server answers, for scripts and container health checks.
Access and security
Every request needs the token, except GET /healthz, which only says whether Sift is up. Keep the token secret: whoever has it controls Sift.
- The token. Set
SIFT_TOKENto keep one token across restarts. Without it, Sift makes a new token at each start and prints it once, in the startup URL. Sift refuses to listen on any address but 127.0.0.1 without aSIFT_TOKENof 32 characters or more. - Host names. Sift answers only requests addressed to
127.0.0.1:<port>or to a name inSIFT_ALLOWED_HOSTS. This blocks DNS rebinding. When you reach Sift athttps://sift.example.com, setSIFT_ALLOWED_HOSTS=sift.example.com. A name without a port matches any port. - TLS. Sift speaks plain HTTP. Put it behind a reverse proxy with TLS (Caddy, nginx, a cloud load balancer) or a private network such as Tailscale. Don’t expose port 4947 to the internet directly.
- API keys. Sift reads
OPENROUTER_API_KEYandANTHROPIC_API_KEYfrom the environment first. A key typed in Settings goes to<data>/secrets/api-keys.json, readable only by Sift’s user (mode 0600). Sift never logs a key or prints one.
A minimal Caddy site:
sift.example.com {
reverse_proxy 127.0.0.1:4947
}
Footage
Sift reads footage from any path it can see, and never writes to it. Mount the footage read-only.
- A volume on the server. Attach a cloud disk, copy the cards to it, and mount it at
/media. - A network share. Mount it on the host (NFS or SMB), then into the container read-only.
- A synced bucket. Sync the cards down to a local disk first, for example
rclone sync s3:shoots/0927 /srv/footage/0927. Sift reads each file several times, so a disk is much faster than a bucket mounted over the network (s3fs or rclone mount). If you mount a bucket anyway, turn on its local file cache.
When you create an event, give the media folder as a path on the server, such as /media/Shoot_0927. The server has no folder picker, so you type paths.
Exports go to SIFT_OUTPUT_DIR (/exports in the image), in a folder per event. Without it, Sift writes _organizer inside the media folder, which fails on a read-only mount.
Set up the server
Setup has the same three checks as on a Mac: the API key, the Whisper model and the output location. Do them in the web UI, or with the API:
curl -X POST -H "Authorization: Bearer $SIFT_TOKEN" http://127.0.0.1:4947/api/setup/whisper
That downloads the Whisper model (about 0.6 GB) into the data dir. SIFT_OUTPUT_DIR counts as a chosen output location.
Connect agents over MCP
The server’s MCP endpoint is /mcp, with the token as a bearer token. Turn on Agent access first (SIFT_AGENT_ACCESS=1, or Settings → Agent access).
Claude Code:
claude mcp add --transport http sift https://sift.example.com/mcp \
--header "Authorization: Bearer $SIFT_TOKEN"
Other clients that take a JSON config:
{
"mcpServers": {
"sift": {
"type": "http",
"url": "https://sift.example.com/mcp",
"headers": { "Authorization": "Bearer <your token>" }
}
}
}
An agent on the server itself can use stdio instead: sift mcp, or docker exec -i sift sift mcp for the container. The tools are the same 39 as on a Mac (see Agent access).
Export and edit on your own machine
- On the server, export the event as usual. Set Editor drive root to where the footage lives on your editing machine (for example
/Volumes/Shoot_0927), so Sift also writes an XML with your paths. - In the export sheet, press Download XML (or Download editor XML). The same file is at
GET /api/events/<id>/export.xml(add?variant=editorfor the remapped one). - On your editing machine, import it in Premiere Pro with File → Import. Your copy of the footage must be at the editor drive root.
Reveal in Finder and Open in Premiere Pro don’t appear on a server.
Costs
- AI costs the same as on a Mac: the same estimates, caps and prices (see AI keys & costs).
- The server costs what your cloud charges for its CPU, memory and disk. Transcription is the slow part: whisper.cpp on the CPU takes longer than on Apple silicon, and gets faster with more cores. Stop or resize the machine between batches.
- Data transfer. Uploading footage is usually free. Downloading from a bucket to the server can cost egress, depending on the provider and region: keep the bucket and the server in the same region.
What’s different from the Mac app
| Mac app | Linux server | |
|---|---|---|
| Window | Opens your browser | Headless: open the URL yourself |
| Folder picker, Finder, Premiere | Yes | No: type paths, download the XML |
| API key storage | macOS Keychain | Environment, or a 0600 file in the data dir |
| Transcription | whisper.cpp on the GPU (Metal) | whisper.cpp on the CPU |
| Video decode | Hardware (VideoToolbox) and software | Software |
| Notifications | macOS notifications | The server log |