Headless
Headlessπ
LocalGPT Gen builds worlds without opening a window: the same tools, served over MCP to an agent that runs without a display β CI, a server, a batch of variations overnight.
localgpt gen mcp-server --headless # or: localgpt-app mcp-server --headless / localgpt-gen mcp-server --headless
The process is the MCP clientβs own: the client spawns it, calls the gen tools over stdio, and the process exits when the client goes away. Everything a windowed Gen can do is in the tool set β spawn, modify, lights, environment, terrain, the WorldGen pipeline, gen_save_world β and screenshots render offscreen. See MCP Server for the client configuration.
Why headlessπ
Interactive work means sitting and watching one scene. Variation and comparison β five lighting passes over a village, three densities of a forest β are scripting jobs, and an agent that can run a loop runs them: it queues its own prompts, calls the tools, saves each result as a world, and you open the results in the morning.
The agent is yours β Claude Code, Codex, a script with an MCP client β and so is its memory of your preferences. Gen keeps none: what it keeps is the worlds, under ~/.local/share/localgpt/gen-workspace/skills/<name>/, each loadable with gen_load_world and openable in the window.
Exit codesπ
| Code | Meaning |
|---|---|
| 0 | The client disconnected; the process ended with it |
| 1 | Gen could not start (a GPU could not be opened, a world failed to load) |
GPUπ
Headless rendering wants any wgpu backend, software included (Backends::all()); on a machine with little GPU memory, close the Gen window while a headless process runs.
The worldβs command lineπ
For worlds already on disk, nothing of Gen is needed: localgpt world submit, undo, log and verify commit to a .world package from any shell with no display at all. See CLI Commands.