Fornax
Provides a render job type that lets clients submit self-contained Blender scenes to a GPU worker and retrieve rendered outputs; Blender is configured as a worker tool path, with auto-run scripts disabled.
Configures FFmpeg as a worker tool for media and transcription job packs, allowing clients to submit audio or video jobs for processing on the worker and retrieve the results.
This server does not currently have a deployable release on Glama. Follow the repository's setup instructions to install and configure it for your MCP client, including any required credentials and local dependencies.
Fornax
A GPU job queue served over MCP. One worker on a PC with a GPU owns the card; agents and apps on other machines send it jobs (transcription, rendering, upscaling, and any type you add) and get the results back with a manifest.
What Fornax is, in one page — with screenshots of the tray.
Fornax is Latin for an oven, and the name of a constellation.
Status: 0.12, in daily use: several agents share one GPU PC through it. The API may still change.
agent (MCP) ─┐ ┌─ fornax worker on the GPU PC (pulls jobs; no open port)
├──► Fornax server ◄─┤
app (REST) ──┘ queue, files, └─ type packs: transcribe, render, upscale, your own
result pagesOne job at a time, in a fair order. Priorities
high,normalandidle(an idle job waits until someone starts it); every job names the agent that sent it, andqueue_statussays who runs and who waits ahead.Programs on the GPU PC take their turn too.
fornax lease -- <program>waits in the queue, holds the card while the program runs and gives it back when it ends.A tray app on the GPU PC starts the worker and shows the card, the running job, the queue (drag to reorder) and the history.
Generic. Job types are packs on the worker PC (
types/): a contract (inputs, a strict parameter schema) and a command. The server offers exactly what the worker announced; nothing else can run.Safe by construction. No shell, no arbitrary commands: arguments are built from validated values only; tools never run the content of an input (Blender's auto-run scripts stay off). Clients see only their own jobs and files.
Windows and Linux for the worker; the server is one Docker image.
Run the server
docker run -d --name fornax -p 127.0.0.1:3000:3000 -v fornax-data:/data \
-e FORNAX_SECRET="$(openssl rand -base64 48)" -e PUBLIC_URL=https://fornax.example.com \
ghcr.io/<owner>/fornax:latestConfiguration is environment variables only; .env.example lists every one with an example value, and
compose.example.yaml is a local starting point. The important ones:
Variable | Default | Meaning |
| – (required) | at least 32 random characters; signs upload, download and result links |
|
| the public address, scheme and host only |
|
| the SQLite database |
|
| how many reverse proxies may set |
|
| largest input file |
| empty (off) | allowed |
| the system's (UTC in the image) | the time zone of times in sentences (job notes, the result page), e.g. |
| the image's | the worker bundle served at |
| the image's | the tray's installers served at |
The image runs as a non-root user (any UID works), writes only to DATA_DIR and /tmp, migrates its database at
start, answers GET /healthz (health command in the image: node /app/dist/src/healthcheck.js), and stops within
seconds on SIGTERM.
Behind a reverse proxy
Fornax expects TLS in front of it and must be served at the root of PUBLIC_URL. For the proxy:
Do not log secrets in URLs. These paths carry a token or a signature:
/mcp/<token>,/r/<signed>,/api/uploads/<signed>,/pair/<invite>and any?sig=query. Mask them or keep them out of the access log. Fornax's own log never contains them.Large bodies and slow requests: allow request bodies up to
FORNAX_MAX_UPLOAD_MBand long uploads (GBs); an output upload from the worker may take ~30 s while the server makes its preview.Webhooks go out directly: Node's
fetchignoresHTTP(S)_PROXY, so the container needs a route to the callback hosts.Give the container ~1 GB of memory (previews of large images are decoded in memory) and a stop grace period of at least 15 s.
Administration
fornax-admin runs inside the container (docker exec fornax fornax-admin …):
fornax-admin tokens invite <name> [--worker] an invite link (client) or the pair command (worker), valid 24 h
fornax-admin tokens pending | list
fornax-admin tokens approve <name> after comparing the fingerprint with its holder
fornax-admin tokens revoke <name> also cancels the token's queued and running jobs
fornax-admin tokens uninvite <name> removes an unused invite
fornax-admin backup <dir> a consistent database copy and the job filesbackup is safe while the server runs. <dir> must be new or empty and outside DATA_DIR/files; a failure prints
one line and exits 1. A backup written into the data volume is lost with it, so move it out afterwards:
docker exec fornax fornax-admin backup /data/backups/2026-11-14
docker cp fornax:/data/backups/2026-11-14 ./fornax-backup-2026-11-14
docker exec fornax rm -r /data/backups/2026-11-14or give the container a second mount for backups (e.g. -v fornax-backups:/backups, then
fornax-admin backup /backups/2026-11-14).
Job files are kept 14 days after a job finishes (FORNAX_FINISHED_DAYS); the database holds tokens and jobs.
Related MCP server: Jungle Grid MCP Server
Connect a client
The admin runs
fornax-admin tokens invite aliceand sends Alice the link.Alice opens it. The page makes her token in her browser (it is never sent anywhere) and shows:
for Claude Code:
claude mcp add fornax --scope user --transport http https://fornax.example.com/mcp --header "Authorization: Bearer <token>"for claude.ai and other clients without custom headers: the connector URL
https://fornax.example.com/mcp/<token>(treat it like a password)a fingerprint such as
7K2F-9QXA.
Alice's first request registers the token as pending; the admin compares the fingerprint (
fornax-admin tokens pending) and runsfornax-admin tokens approve alice.
MCP tools: list_job_types, create_upload, submit_job, get_job, get_output, list_jobs, cancel_job,
queue_status. Large files go through create_upload, which returns a one-time link and a ready curl -T command
(curl --fail-with-body needs curl 7.76 or newer; use -f with an older one). Agents pass agent with submit_job
(the name other agents reach them by): every client sees who runs and who waits, so whoever waits knows whom to ask.
get_job takes wait_seconds (up to 25) and the change of the previous answer and then answers as soon as the job
changes. While a job waits, note says why in one sentence (the worker is offline, the type is not offered, other
programs hold the GPU, or the jobs ahead of it).
REST API
All with Authorization: Bearer <token>:
Method and path | Purpose |
| offered job types with their schemas |
| upload a file (streamed body) → |
| a one-time upload link ( |
| submit |
| list, details, outputs, result page link; one job also has |
| answers as soon as the job's |
| cancel |
| body |
| body |
| download (or with a signed |
| queue summary: counts, the running job ( |
Another client's job or file answers 404.
The worker's token also opens the operator's routes, for whoever runs the worker (the tray uses them): they see and order the whole queue, every client's jobs included, and none of them counts as a sign of life of the worker.
Route | What it does |
| The paused flag, the worker, the running job, the waiting jobs in the order they run, the last 50 finished jobs. With |
| Body |
| Cancels a job of any client. |
| Body |
| Body |
| Start all: every idle job becomes normal, at the end of the normal ones. |
| Body |
Priorities are high, normal and idle. A new job joins the queue right after the last waiting job of its priority
or higher, so without moves high jobs run first in the order they came, then normal ones. An idle job never starts by
itself: the worker's operator starts it (the tray's Idle block, fornax queue start-idle) or its client sets normal or
high. A job submitted without a priority gets its type's default_priority (upscale: idle). A job that ran and comes
back (the worker stopped, an attempt failed) goes to the top; a job put back with Requeue goes right after the waiting
jobs of a higher priority, and Pause puts it at the top of Idle.
Webhooks
With callback_url (allowed by FORNAX_WEBHOOK_PREFIXES), Fornax posts {"job_id": "…", "state": "succeeded"}
when a job ends, signed with a key derived from your token:
import { createHmac, hkdfSync, timingSafeEqual } from 'node:crypto';
const key = Buffer.from(hkdfSync('sha256', token, Buffer.alloc(0), 'fornax-webhook', 32));
function verified(headers, rawBody) {
const expected = `sha256=${createHmac('sha256', key).update(`${headers['x-fornax-timestamp']}.${rawBody}`).digest('hex')}`;
const got = String(headers['x-fornax-signature'] ?? '');
return got.length === expected.length && timingSafeEqual(Buffer.from(got), Buffer.from(expected));
}Deliveries are at least once (attempts at once, after 1 and after 5 more minutes; redirects are never
followed): deduplicate on job_id, and read the job's state from the API instead of trusting the body.
Run the worker
On the PC with the GPU (Windows or Linux, Node.js 22 or newer):
Download the worker from your server (
https://fornax.example.com/downloads/fornax-worker.zip) or from the GitHub releases, unzip it and install it:node fornax-worker/fornax.mjs install. It goes to%LOCALAPPDATA%\fornax\app(Linux:~/.local/share/fornax/app, with the command~/.local/bin/fornax) andfornaxis put on your PATH: open a new terminal. The unzipped folder can be deleted.On Windows the folder is added to your user Path, which keeps its registry kind (
REG_EXPAND_SZ) and its%VAR%entries as they were. On Linux~/.local/bin/fornaxis a link to the installedfornax; when~/.local/binis not on your PATH yet,installsays how to add it.The admin runs
fornax-admin tokens invite pc --worker, which prints the command to run on the PC:fornax worker pair --server https://fornax.example.com --name pc. Approve its fingerprint on the server.Put the tool paths into
worker.yaml(%APPDATA%\fornax\on Windows,~/.config/fornax/on Linux):server: https://fornax.example.com tools: python: python3 ffmpeg: ffmpeg ffprobe: ffprobe blender: /usr/bin/blenderInstall job types and check them:
fornax types install transcribe,fornax types install render,fornax types install upscale(needs ffprobe inworker.yaml),fornax doctor. Therenderpack needs scenes that are self-contained (File > External Data > Pack Resources).Start it:
fornax worker. Ctrl+C gives the running job back; a second Ctrl+C kills the tool.
Some types download models that need an account's token (transcribe's speaker recognition needs a Hugging Face
token): store it with fornax secrets set HF_TOKEN (it asks without showing what you type, except in Git Bash's own
window, which cannot hide it: use Windows Terminal or PowerShell there; --from-file <path> reads a file), then run the setup again with the worker stopped: fornax types setup transcribe. Secrets live in
<config>/secrets/, only the setup of a pack that asks for one gets it, and they never reach the server.
fornax secrets list shows the names, fornax secrets remove <NAME> deletes one.
Watching and ordering the queue
On the worker's PC (it uses the worker's token) fornax queue shows the whole queue: whether it is paused, the
running job with its time and progress, the waiting jobs in the order they will run, the last finished ones.
fornax queue move <id> --top(or--bottom,--before <id>,--after <id>) changes the order of waiting jobs.fornax queue cancel <id>cancels a job of any client.fornax queue priority <id> high|normal|idlechanges the priority of a waiting job;fornax queue start-idlestarts every idle job;fornax queue requeue <id>stops the running job and puts it back in the queue (--idle: into Idle). All three take--jsonlike pause and resume.fornax queue pauselets the running job finish and starts no other;fornax queue resumegoes on. With--jsonboth print the queue the server answered with, likefornax queue --json.fornax queue --jsonprints the same as one line of JSON ("ok": trueand the fields ofGET /api/worker/jobs;paused_atsays since when the queue is paused).fornax queue --watchprints the queue again after every change (with--json, one line each; with--jsonit also ends when its standard input closes, which is how a program that reads it stops it).
fornax worker --events runs the worker for a program that controls it (the tray): standard output carries only JSON
lines ({"event":"started","version","pid"}, {"event":"log","line"},
{"event":"types","types":[{"name","state","reason"}]} with the state offered, waiting (for the card) or
unavailable, {"event":"restarting"}, {"event":"stopped","code"}), and a line stop on standard input stops it
like Ctrl+C (a second one at once; closing standard input is one stop).
Updating
fornax update installs the version your server offers (fornax doctor and the worker say when it differs). It
checks the download's size and SHA-256 against what the server announces; on a mismatch nothing is changed. It
brings the installed built-in types up to date (their env/ stays; a type's setup runs again only when the type
changed what it installs) and mentions new built-in types (fornax types install <name>); types installed with
--from are left alone. A running fornax worker finishes its job and restarts on the new version in the same
window when it was started from the installed copy (a worker started from the unzipped folder prints what to do
instead): it restarts between jobs, so a running job or lease finishes first, and an idle worker restarts within about
25 s.
--force installs the offered version again even when you have it (the worker does not restart for the same
version); --server <url> asks that server instead of the one in worker.yaml. fornax update refuses a version
older than 0.3.0, which could not restart into a newer one: install such a version by hand from
<server>/downloads/fornax-worker.zip.
The server's image also carries the tray's installers of its version: <server>/downloads/fornax-tray.msi and .deb,
described by <server>/downloads/fornax-tray.json (version, SHA-256 and size of each); fornax tray install and the
tray's update use them.
To uninstall, delete the app folder and remove it from your Path (Linux: ~/.local/bin/fornax).
Your own job types
fornax types add <name> creates an empty pack and copies a prompt for Claude Code that builds the rest with you;
the format is in types/README.md.
The GPU belongs to the queue
Check the card before each job. With gpu.max_used_mib in worker.yaml the worker reads the whole card's memory
in use (nvidia-smi) before it takes a job, and takes none while more than that is in use (another program on the
card, e.g. Blender started by hand) or while the card cannot be read; queue_status then says why nothing runs. The
key has no default: without it nothing is checked. fornax doctor shows the card and suggests a value (what is in use
now plus some room):
gpu:
max_used_mib: 2048A worker that starts while the card cannot be read (an external GPU attached after sign-in) waits for it before it checks its job types, and checks them again whenever the card comes back, so the types that need the card are offered without a restart. Meanwhile the server keeps the types the worker offered last and takes jobs for them.
Lease the card for a program on this PC. fornax types install lease, then store a client token (the worker
token cannot submit jobs):
The admin runs
fornax-admin tokens invite <name>; you make the token on the pairing page.fornax lease tokenreads it from standard input (paste it, or pipe it in) and checks it with the server. A new token waits for approval, so this first check only registers it and nothing is saved.The admin compares the fingerprint (
fornax-admin tokens pending) and runsfornax-admin tokens approve <name>.Run
fornax lease tokenagain: now the token is saved.
FORNAX_CLIENT_TOKEN wins over the stored file. Then:
fornax lease [--minutes N] [--wait-minutes N] [--rerun] [--priority high|normal|idle] [--label TEXT] [--agent NAME] -- <program> [args…]
fornax lease -- blender.exe -b scene.blend -f 1The program waits for the card in queue order like any job, then runs here with your terminal, working directory and
environment (plus FORNAX_LEASE=<job id>, without the client token), and gives the card back when it ends. Give the
program itself, not a .cmd/.bat launcher (there is no shell); a launcher or a program that is not found ends
fornax lease before any job is made. --minutes (default 60, at most 720) is the longest one run may take;
--wait-minutes gives up waiting for the card; --label names the lease in the queue (default: the program's file
name). --agent (or the variable FORNAX_AGENT, which the program keeps) names who asks for the lease; every client
sees it next to the job. Its own lines go to stderr and start with fornax lease: (a usage error is followed by the usage);
fornax lease --help prints the usage to stdout. Everything else on stdout is the program's.
fornax lease inside a lease runs its program at once, under the outer lease. It needs the stored client token
(fornax lease token): FORNAX_CLIENT_TOKEN is removed from the program's environment, so it does not reach a nested
fornax lease either.
On Windows, fornax.cmd passes the arguments through cmd, which interprets unquoted &, |, <, > and ^, and
a Ctrl+C there asks "Terminate batch job (Y/N)?". In scripts, and for arguments with such characters, call Node
directly: node %LOCALAPPDATA%\fornax\app\fornax.mjs lease -- ….
On Linux the program runs in a session of its own (so that its whole process tree can be ended), so it has no
controlling terminal: whatever opens /dev/tty (password prompts of sudo, ssh or getpass), job control
(Ctrl+Z) and terminal resize signals do not work; reading the standard input it inherits works. A nested
fornax lease runs its program in the caller's process group instead. If fornax lease itself is killed on Linux
(kill -9, the out-of-memory killer), its program goes on running, and the lease ends about 60 s later while the
program may still use the card.
Exit code | Meaning | The program |
120 | usage error, or the program cannot start (not found, | not started |
121 | no lease: no client token, a bad | not started |
122 | gave up waiting ( | not started |
123 | the lease was lost: canceled, failed, | stopped or not started |
130 | interrupted (Ctrl+C, | stopped |
other | the program's own code (128 + the signal's number when a signal ended it) | finished |
fornax lease stops on Ctrl+C, SIGTERM, SIGHUP (a closed terminal) and SIGQUIT (Ctrl+) alike. On Linux the
signal itself is passed on to the program (its session does not get the terminal's signals); on Windows the program
gets Ctrl+C from the same console. The program has 10 s to end before it is killed; a second Ctrl+C kills it at once.
A stop while waiting cancels the job (a second Ctrl+C then waits up to 3 s for that cancel).
Stopping or restarting the worker stops a leased program. With --rerun (for a program that is safe to start again,
e.g. one that continues after the frames it has) it starts again once the worker runs again; without it fornax lease
ends with 123. A program never starts without a lease: while the server cannot be reached, fornax lease keeps
trying and waits, and only --wait-minutes (122) or a stop (130) ends that wait. A program that already runs goes on
while the server is unreachable, but only for so long: after 10 minutes without the worker the server takes the job
back (it returns to the queue, or fails), and once the server can be reached again fornax lease stops the program
(123, or with --rerun it starts again when the lease returns).
As a service
Linux (systemd user unit),
~/.config/systemd/user/fornax-worker.service:[Unit] Description=Fornax worker After=network-online.target [Service] ExecStart=%h/.local/bin/fornax worker Restart=on-failure KillMode=mixed TimeoutStopSec=30 [Install] WantedBy=default.targetKillMode=mixed: systemd sends SIGTERM tofornax workeronly, which passes it on to the worker once (withcontrol-groupthe worker would get it twice and quit at once instead of giving its job back); whatever is still running after the stop timeout is killed. The same holds outside systemd: a signal sent to both processes at once (killall,pkill -f fornax) counts as two stops and quits at once. Whenfornax workeritself is killed, the worker stops by itself as after a first Ctrl+C.Then
systemctl --user enable --now fornax-worker(andloginctl enable-linger <user>to run without a login).Windows: a Task Scheduler task "At log on" running
%LOCALAPPDATA%\fornax\app\fornax.cmd worker. Fornax ends a job's whole process tree when it stops; a process that detached from that tree (rare) survives a crash of the worker.
Tray app
On the worker's PC the tray app starts the worker and shows the card and the whole queue. The header shows the
worker's state (with Pause queue and Start/Stop worker), the GPU strip the card's memory, load and temperature and who
holds it (a job, a lease, or programs outside Fornax, with when the next job starts), Running the job with its
progress and time left (or the lease, with Revoke), Waiting the jobs in the order they will run (drag them, or use ⤒
and ⤓ on hover), and the tabs History (today's and yesterday's finished jobs, their result page and error) and Worker
log. The arrow next to the tabs hides their content (a click on a tab shows it again), and the window becomes as high
as what it still shows; the window remembers its size, its place and whether the tabs are open (tray-window.json in
%LOCALAPPDATA%ornax or ~/.local/share/fornax). Pause queue lets
the running job finish and starts no other; Stop worker gives the running job back to the queue. It tells you when a
job fails, and when jobs wait while the worker is stopped or the queue is paused. The footer lists the job types the
worker offers, the ones waiting for the card (dimmed) and the ones whose check failed (red, click for the reason); the
icon turns orange while the worker waits for the card and violet while a lease holds it. The card is read with
nvidia-smi while the window is open.
Install
fornax0.5.0 or newer and pair this PC (see Run the worker); the tray runs the installedfornax.mjswith Node.js 22 or newer.Install it with
fornax tray install(fornax 0.7.0 or newer): it downloads the installer of your server's version (the.msion Windows, the.debon Ubuntu), checks it and runs it (Windows asks through UAC, Ubuntu for your password). Or download it from the GitHub release: the.msi(it is not signed: SmartScreen asks, choose More info, Run anyway), the.debor the.AppImageon Ubuntu (they needlibwebkit2gtk-4.1-0andlibayatana-appindicator3-1, the.AppImagealsolibfuse2, on Ubuntu 24.04libfuse2t64; GNOME shows tray icons with the AppIndicator extension, which Ubuntu enables).Start it once and tick Start at sign-in in its menu. At sign-in it starts without its window and starts the worker. A worker you started yourself in a terminal shows as "Worker runs outside the tray"; stop it there if the tray should own it.
Settings, all optional, go in tray.json next to worker.yaml (%APPDATA%\fornax\tray.json on Windows,
~/.config/fornax/tray.json on Linux): {"node": "<path to node>", "start_worker": true}. The menu item Start
worker with the tray writes start_worker.
The window shows the versions of the tray, of fornax and of the server. When the server is newer it offers
Update to … (in the window and the menu): the tray pauses the queue, lets the running job finish, runs
fornax update, then fornax tray install --wait-pid <its pid> --relaunch <its path> installs the new tray once the old
one has quit and starts it again (also when the installation was cancelled); the new tray says how it went and resumes
the queue. When only fornax is older it offers Update fornax to …. A tray from the AppImage updates only fornax;
get a new AppImage from the GitHub release.
Quit stops the worker first; its running job goes back to the queue. A tray started by the Windows installer starts
itself once more through Explorer, so that tools installed through folder links (scoop) work for the worker. To remove
the tray, uninstall Fornax tray in the Windows settings, or sudo apt remove fornax-tray.
Security
Tokens are stored as SHA-256 hashes; a client token sees only its own jobs and files; a worker token cannot use the client API and the other way round.
Jobs run only types the worker announced, with parameters checked against a strict schema on the server and again on the worker; arguments never pass through a shell; strings may not start with
-.Upload, download and result links are signed, expire, and stop working when their token is revoked.
Worker secrets (
fornax secrets) stay on the worker PC: only the setup of a pack that declares one gets it, no tool inherits a variable of that name, and its value is masked in the setup's output.Accepted risk: the worker token sees every client's inputs (one worker on its owner's PC).
Development
pnpm install
pnpm typecheck # strict compiler checks double as the lint step
pnpm test # all packages, then the type packs' Python tests (needs Python 3.10+)
pnpm bundle:worker # dist/worker/fornax-worker-<version>.zip
pnpm --filter @fornax/tray test:rust # the tray's window build and Rust testspnpm test also checks the landing page in site/ (scripts/site.test.mjs: files, anchors, README links, image
sizes, nothing private). Its screenshots come from invented data only: node scripts/site-shots.mjs photographs the
tray preview (pnpm --filter @fornax/tray preview running) and the link-preview image, and
FORNAX_SITE_SHOT=1 pnpm --filter @fornax/server exec vitest run test/site-shot.test.ts the result page of an
invented job. GitHub Pages publishes site/ from main (.github/workflows/pages.yml).
pnpm test leaves the tray out; its check, pnpm --filter @fornax/tray test:rust, needs Rust 1.90+ and, on Linux,
the Tauri packages listed in .github/workflows/ci.yml.
CI runs the tests on Ubuntu and Windows, builds and smoke-tests the Docker image, tests the tray and builds its
installers on Windows and Ubuntu 22.04, publishes the image to GHCR from main, and attaches the worker zip and the
tray installers to a release for every v<version> tag.
Related: Tabula, the memory server whose transcription worker Fornax grows out of.
License
MIT
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
This server cannot be deployed
Maintenance
Related MCP Connectors
On-demand GPU nodes for agents: create nodes, run commands, and submit jobs, billed by the minute.
Public MCP for agent verification, work discovery and governed interoperability.
GPU compute for agents: run commands on an L4/A100/H100, watch logs, billed per second.
Execution control plane for agents: capabilities, durable jobs, budgets, receipts, and BYOK.
Related MCP Servers
- -licenseNot gradedqualityNot gradedmaintenanceEnables MCP clients to securely execute bounded coding tasks through registered backends, with idempotent job submission, status polling, and artifact retrieval. It isolates each job in Git worktrees and supports optional branch publishing and pull request creation under strict policy constraints.-
- AlicenseAqualityCmaintenanceEnables MCP-aware agents to estimate, submit, monitor, cancel, and retrieve artifacts from Jungle Grid workloads, supporting asynchronous AI execution, batch processing, training, fine-tuning, and access to logs and managed outputs.11MIT
- AlicenseBqualityBmaintenanceEnables AI agents to submit GPU job requests, select eligible workers, track execution, and retrieve results via MCP.1421MIT
- AlicenseBqualityCmaintenanceProvides a persistent compute queue for AI agents, enabling them to submit hardware-aware GPU jobs, monitor execution, and retrieve results and artifacts across sessions via MCP tools.13MIT