Zalmox CLI and MCP server

Make game-ready assets from your terminal or your AI agent: 3D models (from text or an image, retextured, animated), VFX flipbooks, PBR textures, skyboxes, terrains and images, with Unity packages. The same account, credits and library as zalmox.io.

• Cloud jobs run on Zalmox GPUs and spend credits, as on the website.
• My GPU jobs run free on your own machine, once you've paired it with the Zalmox Runner.
• Everything you make shows up in your library on zalmox.io.

Needs Node.js 18.17 or newer.

Sign in

npx zalmox login

It opens zalmox.io; check the code matches and approve. The CLI saves a personal API key in your user config folder. You can see and revoke keys on zalmox.io under Account → API, or create one there for a CI job or server (ZALMOX_API_KEY=zx_…).

Use it

npm install -g zalmox        # or prefix every command with npx zalmox

zalmox whoami                      # who you are, and your credits
zalmox types                       # what Zalmox makes and what each costs
zalmox types vfx-flipbook          # a type's options

zalmox create text-to-3d --prompt "a dwarven mining cart loaded with crystals" --wait --out ./assets
zalmox create image-to-3d --image ship.png --on my-gpu --wait --out ./assets
zalmox create vfx-flipbook --prompt "violet arcane burst" --effect magic --grid 6x6 --wait --out ./vfx
zalmox create pbr-texture --prompt "mossy cobblestone" --material stone --tier final --wait --out ./textures
zalmox types animate               # how to write the motions list (presets, moving parts, rotors), with an example

zalmox jobs                        # recent jobs
zalmox jobs wait <id> --out ./assets
zalmox jobs download <id> --role model --role unitypackage --out ./assets
zalmox jobs cancel <id>            # credits for an unfinished cloud job come back

Every option a job type lists becomes a flag (--effect, --grid, --loop, …). Useful extras:

3D models with a triangle budget (--targetFaceCount 25000, or --lowPoly) also get a normal map baked from the detailed surface when the budget is 150,000 or fewer: <name>_normal.png, and normalBake in the model's metadata. If it couldn't be baked, the model's metadata checks has a normalMap entry saying why.

| Flag | | |---|---| | --on cloud\|my-gpu\|auto | Where it runs: cloud (credits), my-gpu (free, your paired machine; the job waits for it) or auto (your machine when it's ready, else the cloud). The default is auto; set yours with zalmox config set placement cloud (or my-gpu) | | --tier draft\|final | Final makes several candidates and keeps the best; it costs more | | --max-credits <n> | Refuse to start a job that costs more | | --json | Machine-readable output on stdout, for scripts and agents |

Starting a job is safe to retry: the CLI sends an idempotency key, so a lost response never starts (or charges) a second job.

AI agents (MCP)

zalmox mcp runs the same client as an MCP server. Sign in once with npx zalmox login, then add it to your agent:

Claude Code

claude mcp add zalmox -- npx -y zalmox mcp

Claude Desktop, Cursor, Windsurf, VS Code and others (their MCP settings file):

{
  "mcpServers": {
    "zalmox": {
      "command": "npx",
      "args": ["-y", "zalmox", "mcp"]
    }
  }
}

To use a key instead of the saved login (e.g. on a server), add "env": { "ZALMOX_API_KEY": "zx_…" }.

Tools: list_job_types, estimate_cost, get_credits, create_job, wait_for_job (saves the files with download_dir), get_job, download_outputs, list_jobs, cancel_job. Agents are told to quote the cost before starting a cloud job, and create_job takes max_credits as a guard.

3D model files

• Unity package: import it and a prefab is built with levels of detail, a convex collider and a Lit material.
• Plain FBX: <name>_LOD0–_LOD3 become a LODGroup on import into Unity. The collision hull UCX_<name>_00 comes in hidden: add a convex MeshCollider from its mesh. Unreal takes both as LODs and collision by their names.
• Options: the texture is corrected toward the picture's colours (--colorMatch off to keep it as made); --straighten on takes a three-quarter picture's tilt out of the model.
• Symmetry: --symmetry auto evens out a two-sided object (a drone, a vehicle, a crate) whose sides came out different: it finds the mirror plane, and when the object is clearly symmetric, keeps the better half, mirrors it onto the other and welds the seam. Otherwise the model is left as it is. --symmetry x always mirrors, across the left-right plane (the X axis; use it with --straighten on). The model's metadata reports symmetry: the plane, the score (0–1) and which half was kept. Both halves then share one half's texture, so leave it off for things that aren't meant to be symmetric (a character holding something, a tree).
• Lights: when the picture shows lights (a glowing eye, a light strip: burnt-out colour with a glow around it), the model also gets <name>_emissive.png: the lights on the model's UVs, black elsewhere. It is the GLB's emissive texture and the Unity material's emission map (at emissiveIntensity in <name>_model.json, 2 by default), and the job's emissive metadata lists the lights found. Use it for the glow instead of guessing from the albedo; --emissive off skips it. No lights, no file.

Settings

| | | |---|---| | ZALMOX_API_KEY | A personal API key; overrides the saved login | | ZALMOX_PLACEMENT | cloud, my-gpu or auto (anything else is an error) | | ZALMOX_SERVER | Another Zalmox server (default https://zalmox.io) |

The saved login is in %APPDATA%\zalmox\config.json on Windows and ~/.config/zalmox/config.json elsewhere. zalmox logout removes it from this machine; revoke the key on zalmox.io to stop it working everywhere.

When the cloud has no machine that can run a job type, a cloud job is refused straight away (no_cloud_capacity, no credits held) instead of waiting in a queue that can't move: run it with --on my-gpu, or --on auto. When it can run it but no cloud GPU is up yet, one starts for it: the job stays queued with the stage "Starting a cloud GPU (about 7 min)", counting down, and --wait / zalmox jobs wait print that on stderr (with --json too).