Run Godot headless on a cloud VPS and share a web export link
Godot is a game engine with an editor, but the editor binary also runs without a screen: godot --headless can create projects, run scripts and tests, and export finished builds. That makes a small server a workable place for an AI agent to build a game or prototype and hand you a link to play it. We tried it on real servers; here is what it took and what it cost.
The commands
Three things make a headless server useful for Godot: the editor binary, the export templates that match its exact version, and an export preset in the project.
# run a script with no window
godot --headless --path ./mygame --script res://tools/check.gd
# import assets, then export the web build (needs a "Web" preset and the templates)
godot --headless --path ./mygame --import
godot --headless --path ./mygame --export-release "Web" ./out/index.htmlThe command shapes are standard Godot usage, shown for orientation; the timings in this guide come from our tool server running the same engine.
What we measured on 2 vCPU / 4 GB
Godot 4.7.2 on a shared-CPU server with 2 vCPU and 3.9 GB of RAM, in two runs (one exercising every tool, one clean), plus a fresh Ubuntu 22.04 server. Single observations.
| Step | Measured | Note |
|---|---|---|
| Install (Ubuntu 24.04) | 45 s and 50 s | package install 6 s, templates download and hash check 14 s, Python environment 20 s |
| Install (Ubuntu 22.04) | 50 s | |
| Web export | 11.6–13.5 s | 39.8 MB output |
| Linux export | 11.8 s | 73.5 MB output |
| Peak memory during both exports | 628 MB resident, 802 MB virtual | about 29% of the memory limit we apply |
- Disk: about 300 MB for the engine and templates, 61 MB for the tool server and its Python environment, and the workspace grew by 148 MB over about ten exports.
- Cost: $0.04 of server time per full test run.
The export templates are the big download
The editor is small. The export templates are not: the official bundle for 4.7.2 is 1.28 GB. On a datacentre link, downloading and hash-checking it took 14 seconds. On a slower connection or a metered one, it is the step to plan around, and the server needs room for it during the install even though most of it is thrown away.
We pin both files by hash, check the bundle before unpacking it, and keep only the templates we need (web and Linux, in release and debug). That is why the installed footprint is about 300 MB rather than several gigabytes. The pins are in pin your agent versions.
Play links on their own subdomain
A web export is just static files, so the preset serves them with a small read-only viewer behind the reverse proxy, on a per-app hostname of your server (for example godot.<your-server>). The agent finishes an export and hands you a play link. Two details are worth copying:
- We use Godot’s single-threaded web template, so the page runs without the special cross-origin isolation headers that a multi-threaded build needs.
- An export is written to a temporary folder and swapped in only when it is complete, so a failed export never destroys the last playable build.
A caution from our own testing: a check on the server’s main hostname can pass while the app on its subdomain is broken, because the proxy answers the main hostname with a landing page. Test the exact URL you hand out.
The bug that only concurrency showed
Our first viewer read each file into memory whole. Six people downloading the 73.5 MB Linux export at once pushed it to 260 MB, the container’s memory limit fired, and all six downloads failed. After switching to streaming in 64 KiB pieces, 24 of 24 concurrent downloads returned 200 and the viewer peaked at 18.7 MB. A second bug: a script with a runtime error sat idle until the 300 s job budget, holding the only job slot; it now fails in 1.1 s.
The plan floor we chose, and why
We offer the Godot preset on plans from 2 vCPU / 4 GB (11 plans at the time of writing; plan floors are chosen with margin). Exports peaked at 628 MB, about 29% of the 2.74 GB limit we apply, so 4 GB leaves comfortable margin. We did not test 2 GB, and it is a chosen floor with margin, not a discovered minimum. Larger projects and imported assets will use more than a default project does; we did not measure those.
Letting an agent drive it over MCP
The preset wraps headless Godot in an MCP server on the loopback interface, so nothing is exposed to the internet. Its tools cover creating a project, running a script, adding scenes and nodes, setting properties, importing assets, exporting for web and Linux, and running tests. On a raw Ubuntu 22.04 server, Hermes, Claude Code and Codex each listed all of them. OpenClaw needs the transport named explicitly; with a bare url it failed with SSE error: Non-200 status code (400):
claude mcp add --scope user --transport http godot http://127.0.0.1:8040/mcp
# OpenClaw
openclaw mcp set godot '{"url":"http://127.0.0.1:8040/mcp","transport":"streamable-http"}'More on the agents: self-host OpenClaw, self-host Hermes Agent, Claude Code and Codex on a VPS. The sister preset for 3D scenes is covered in Blender headless on a VPS.
Want a Godot-ready server with an agent on it?
The Godot preset installs the pinned engine and templates and the tool server, and registers it with the agents on the box.
Related
- Run Blender headless on a VPS — models and renders for your game.
- The cheapest VPS for AI agents — how small a server can be.
- Pin your agent versions — the Godot hashes in full.
Measured on
- Godot 4.7.2 on a 2 vCPU / 3.9 GB shared-CPU server: two runs (one exercising every tool, one clean), 29 September 2026, both passed.
- Fresh Ubuntu 22.04 server for the install and the agent registrations.
On servers we paid for, each destroyed afterwards. Single observations from one provider’s CPUs. Install times assume a fast datacentre link (about 130 MB/s). Not tested: 2 GB servers, large projects, anything but the default templates, game quality.