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πŸ”—

CodeMeaning
0The client disconnected; the process ended with it
1Gen 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.