Settings · Local servers
Local server setup
Most things on Sorceress run in the cloud — you never need to install anything. A few services can optionally run on your own computer:
- Local image generation
- Local video generation
- Local CorridorKey green and blue screen removal
Local generation only includes open-source models. Every computer is set up a little differently — Windows, Mac, Linux, NVIDIA, AMD, different Python installs — and that is what the support assistant on this page is for. Describe your system and paste the exact error, and it will walk you through it.
This browser doesn’t report the permission
Firefox and Safari don’t always show a separate local-network toggle. Click Ask browser — if a prompt appears, choose Allow.
CorridorKey GPU Server
:8100Local green & blue screen removal on your own GPU
AI green-screen and blue-screen removal for the sprite tools. This is the local service most people actually want. The one-liner in setup downloads a ~300MB model plus PyTorch, then starts keying on port 8100. The same command also starts a deprecated leftover file server on 8080 — ignore that unless you still use Code Studio or the other older on-disk tools.
NeedsNVIDIA GPU with 4GB+ VRAM (GTX 1060 or newer), or any Mac / CPU-only machine in --cpu mode (slower). No AMD GPU support.
Skip it?No compatible GPU? Every keying tool also offers a Cloud option that uses credits — nothing to install.
Local AI Server (Image & Video)
:8181Open-source image & video models on your own GPU — no credits
A separate server that runs open-source image models (Z-Image, HiDream, SD 3.5, FLUX, Qwen-Edit) and video models (Wan) on your hardware. Cloud-only models are not available locally. One guided wizard installs everything: it detects your GPU, recommends a model bundle that fits your VRAM, and downloads the weights. Image Gen and Video Gen both talk to this same server.
NeedsNVIDIA GPU strongly recommended — 6–16GB+ VRAM depending on the model, 16–32GB system RAM, and 10–70GB free disk per model bundle. The wizard checks your hardware and only offers what fits.
Skip it?Entirely optional — cloud generation on the Image and Video pages works with zero setup.
Sorceress Local Server
Legacy · Deprecated:8080Deprecated — Code Studio and older on-disk tools only
Deprecated. Almost nothing on Sorceress needs this anymore. It only exists for leftover tools that read files on your disk: Code Studio (itself deprecated), local game-folder previews, Device Preview, and local FFmpeg in Utils. Installing CorridorKey starts this process automatically on port 8080 — only Connect it if you still use those older tools.
NeedsAny computer — no GPU needed. Python 3.10+ is the only dependency.
Skip it?Skip this. Most of the suite does not need it. Only Connect if you still use Code Studio or the other deprecated on-disk tools.
Which do I need?
Just use the cloud tools (images, video, 3D, sprites…)
Nothing to install — skip this page entirely.
Free, unlimited background keying for sprites
CorridorKey (port 8100) — the one-liner in setup below.
Generate images & videos locally without spending credits
Local AI Server (port 8181) — its own one-command installer below.
Code Studio or other deprecated on-disk tools
Sorceress Local Server (port 8080) — legacy and deprecated. Most tools do not need it. Starts automatically when you install CorridorKey; Connect it only if you still use those older tools.
Set up, step by step
These steps assume a brand-new machine with nothing installed. Commands go in a terminal: press Start, type “PowerShell”, open it. A server keeps running while its terminal window stays open — closing the window stops it.
CorridorKey
This is the one most people install. The same command also starts a deprecated leftover file server on port 8080 — ignore that unless you still use Code Studio or the other older on-disk tools.
winget install Python.Python.3.12After it finishes, close this terminal and open a NEW one — Windows won't find Python or pip in the same window.
No winget? Download the installer from python.org/downloads and tick "Add python.exe to PATH" on the first screen before clicking Install.
pip install -U sorcgcs-server && sorcgcs-serverRe-run this same command every time — it auto-updates, then starts CorridorKey on port 8100. If pip is not found, use this instead:
python -m pip install -U sorcgcs-server && python -m sorcgcs_serverFirst run: CorridorKey downloads a ~300MB keying model plus PyTorch (can be several GB) — watch the terminal and let it finish. Then press Check on the CorridorKey card above. Subsequent starts take seconds.
Useful flags: --cpu (Macs or no NVIDIA GPU — keying runs on CPU, slower but stable). Don't use --no-corridorkey unless you only want the deprecated leftover file tools.
Local AI Server (Image & Video)
Completely separate from CorridorKey — install this only if you want to generate images and video on your own GPU. Needs Python 3.10+ (same install as CorridorKey step 1 if you don't have it yet).
py -3 -m pip uninstall -y sorcgcs-local-ai 2>nul & python -m pip uninstall -y sorcgcs-local-ai 2>nul & python -m pip install --upgrade --force-reinstall --no-cache-dir "https://sorceress.games/api/local-ai/sorcgcs_local_ai-0.0.0-py3-none-any.whl" && python -m sorcgcs_local_ai.cli --version && python -m sorcgcs_local_ai.cliA guided wizard takes over: it detects your GPU, recommends a model bundle that fits your VRAM, walks you through Hugging Face login for gated models (FLUX, SD 3.5), downloads the weights, and starts the server on port 8181. Model files live in ~/.sorcgcs. Re-run the same command anytime to update.
Open Image Gen or Video Gen and switch to Local GPU mode — both pages share this one server. The Local AI Manager there installs more models, shows logs, and monitors downloads.
Restarting later & adding models ▾
Start the server again (only if you closed its terminal):
(py -3 -m sorcgcs_local_ai.cli 2>nul || python -m sorcgcs_local_ai.cli)Re-open the wizard to add model bundles you skipped, or to manage disk usage:
(py -3 -m sorcgcs_local_ai.cli 2>nul || python -m sorcgcs_local_ai.cli) --wizardHealth check: http://127.0.0.1:8181/status in a new tab should show server info when it is running.
Sorceress Local Server Legacy · Deprecated
Deprecated. Most of the suite does not need this — including all of the current image, video, sprite, and 3D tools. It only exists for leftover on-disk tools such as Code Studio (also deprecated), local game-folder previews, Device Preview, and local FFmpeg in Utils. CorridorKey already starts this process on port 8080 — only Connect it if you still use those older tools.
pip install -U sorcgcs-server && sorcgcs-serverSame command as CorridorKey. If you already ran that, skip this and just Connect below.
The first time you connect, your browser asks for permission to “Access other apps and services on this device” — that is normal, click Allow. This only enables the deprecated leftover file tools (including Code Studio). CorridorKey and Local AI do not need it.
Will it run on my machine?
| Your hardware | CorridorKey | Local AI | Legacy Local Server |
|---|---|---|---|
| NVIDIA GPU (4GB+ VRAM) | Works — best experience | Works — 6–16GB+ VRAM depending on model | Works |
| AMD GPU | Not supported — use the Cloud keying option (credits) | Not supported — use cloud generation | Works |
| Apple Silicon (M1–M4) | Works in --cpu mode (slower but stable) | Wizard supports macOS; large models are slow without NVIDIA | Works |
| No GPU / older machine | Works in --cpu mode (slow) — or use Cloud keying | Not practical — use cloud generation | Works |
Troubleshooting
“pip is not recognized”
Close the terminal and open a new one first — Windows does not pick up a fresh Python install in the same window. If pip is still missing, bootstrap it, then run the install command again:
python -m ensurepip --upgradeMac/Linux: python3 -m ensurepip --upgrade
“python” opens the Microsoft Store or isn't recognized (Windows)
Windows ships a fake `python` shortcut that opens the Store. Install real Python with the winget command from Step 1 (or from python.org with “Add python.exe to PATH” ticked), open a NEW terminal, and try again. Still broken? Turn off Settings → Apps → Advanced app settings → App execution aliases → python.exe.
“error: externally-managed-environment” (Linux)
Modern Debian/Ubuntu block system-wide pip installs. Run the server from its own virtual environment instead — one line, fully self-contained:
python3 -m venv ~/.sorcgcs-venv && ~/.sorcgcs-venv/bin/pip install -U sorcgcs-server && ~/.sorcgcs-venv/bin/sorcgcs-serverTo start it again later, just run the last part: ~/.sorcgcs-venv/bin/sorcgcs-server
“sorcgcs-server: command not found” after installing
The install worked but pip's scripts folder isn't on your PATH. Close and reopen the terminal first. If it still isn't found, launch it as a Python module instead — same server, no PATH needed:
python -m sorcgcs_serverMac/Linux: python3 -m sorcgcs_server — flags like --cpu and --port work the same way.
Mac: pink/purple output or a crash during keying
Apple's MPS (Metal) GPU acceleration can be unstable with CorridorKey on some Macs. Run in CPU mode instead — slower but stable on all Apple Silicon Macs:
pip3 install -U sorcgcs-server && sorcgcs-server --cpu“Cannot find a working triton installation”
Harmless warning on Windows. Triton is a Linux-only optimizer — the server works perfectly without it. Ignore it.
“CUDA error: no kernel image is available”
Happens on very new NVIDIA GPUs (e.g. RTX 50-series). Re-run the install command — recent server versions automatically install a PyTorch build compatible with your GPU.
“Address already in use” / port conflict
Something else on your machine is using that port. Change the port field in Step 2 (e.g. 8090) and run the updated command — the site follows whatever port you save here.
Browser asks to “Access other apps and services on this device”
That's expected — it's how the browser lets sorceress.games talk to a server on localhost. Click Allow. Use the “Ask browser for access” button at the top of this page to check the current state. If you clicked Block, Chromium will not ask again from the page — click the padlock in the address bar → Site settings → Local network access → Allow, then reload.
First run looks stuck / takes forever
On first launch CorridorKey downloads a ~300MB model plus PyTorch (which can be several GB). Leave the terminal window open and watch it — subsequent starts take seconds.
Server shows Connected but sprite tools say keying is offline
The sprite tools check CorridorKey on port 8100. Give it time to finish first-run setup (watch the terminal), then press Check on the CorridorKey card. If you started with --no-corridorkey, restart without that flag. The leftover 8080 file server being Connected or Offline does not affect keying.
I have an AMD GPU — what can I run?
CorridorKey and the Local AI server need NVIDIA (or Apple Silicon in CPU mode for CorridorKey). On AMD, use the Cloud keying option and cloud generation instead — same features, credit-based. The leftover Local Server on 8080 (older file tools) runs on anything and does not need a GPU.
Local AI: Hugging Face 401 / “gated repo” errors
Some model weights (e.g. FLUX, SD 3.5) require a free Hugging Face account. Accept the model's terms on its page, create a Read token at huggingface.co/settings/tokens, and paste it when the wizard asks. Re-run the wizard afterwards.
Hit something not listed here? — paste the exact error text and it will walk you through the fix.
🎬 New to Sorceress?
A quick tour of the whole suite and how the tools fit together.