> ## Documentation Index > Fetch the complete documentation index at: https://docs.summerengine.com/llms.txt > Use this file to discover all available pages before exploring further. # Running in the cloud skill for AI agents > Run Summer Engine on a Linux box with no display: install, launch headless, xvfb, sign in without a browser. A Summer Engine skill for AI agents. `running-in-the-cloud` is a skill from the [Summer skill library](/mcp/skills): a guide your AI agent reads when the task matches, so it builds the good version on the first try. Run Summer Engine on a Linux box with no display: install, launch headless, xvfb, sign in without a browser. | | | | - | - | | Status | Stable | | Domains | Agent workflow, Project | | Version | `1.0.3` | | Engine version | `>=4.6` | | Recommended set | No, installed by `--all` or by name | ## When your agent uses it * Summer Engine runs in a cloud container, CI job, remote agent sandbox, or any Linux machine with no desktop * Installing the engine on Linux, or a tool reports "engine not running" in an environment that has no display * Deciding whether a render path (screenshots, previews, verification frames) needs xvfb-run and software GL * SUMMER\_ENGINE\_BINARY, SUMMER\_ENGINE\_URL, or SUMMER\_TOKEN come up ## Install `summer setup` installs every skill for your agent. To add only this one: ```bash theme={null} npx -y summer-engine@latest skills install running-in-the-cloud --agent claude-code ``` Swap `claude-code` for your agent, such as `codex` or `cursor`. See [Skills](/mcp/skills#quick-start) for every option. ## The skill ## Overview Summer Engine runs on a Linux machine with no display and no human. Everything in this skill was measured in a real cloud container: headless engine boots, MCP tools answer, and renders work under xvfb + llvmpipe. Three facts carry the whole setup: 1. **Local engine ops need no login.** The engine mints its own API token (`~/.summer/api-token`, per-instance tokens in `~/.summer/instances/*.json`) on every launch. Scene mutation, inspection, play, diagnostics, headless scripting — all of it works with zero accounts. 2. **Only gateway features need a credential** — asset search, asset/image/3D generation, releases. In the cloud, pass it as an env var instead of a browser login. 3. **Most containers have no GPU and no Vulkan.** Pure headless work does not care. Anything that produces pixels needs a virtual display and software GL. ## Install the engine `summer install` on Linux (x86\_64) resolves in this order: | Priority | Source | When | | - | - | - | | 1 | `SUMMER_ENGINE_BINARY=` | The container already carries a prebuilt engine binary. Registers that binary — no download. | | 2 | `SUMMER_ENGINE_URL=` | Download any artifact URL: `.tar.gz`, `.zip`, or a raw executable. | | 3 | (default) | The newest published Linux release artifact (`Summer-linux-x86_64-.tar.gz`). | All three register the binary at `~/.summer/engine/summer-linux-x86_64`, which is where `summer run` and `summer doctor` look. `SUMMER_ENGINE_BINARY` is also honored directly at lookup time, so setting the env var alone (without ever running `summer install`) is enough for `summer doctor` to report the engine as installed. ```bash theme={null} # Container with a prebuilt binary: export SUMMER_ENGINE_BINARY=/abs/path/to/engine-binary summer install # registers it; summer doctor now shows Engine: ok ``` `summer doctor` is the readiness check: Engine, Local API, MCP tools. "Login: not signed in" is a warning, not a blocker — engine ops do not need it. ## Launch headless ```bash theme={null} --headless --editor --path ``` That boots the real editor — import pipeline, local API server, MCP reachability — with no window and no display. Give it a few seconds, then `summer doctor` should show `Local API: :6550`. * One-shot work (bake, import, export, scripted authoring) uses `--headless ... -s res://script.gd` — load `headless-scripting`, it is the authoritative guide including the crash-handler flag and the exit-code traps. * **Boot → act → exit.** A long-lived headless editor never rescans the filesystem; it serves a boot-time snapshot forever. ### Instance discovery Every running editor writes `~/.summer/instances/.json` — pid, port, token, project root, heartbeat. The CLI and MCP discover engines through those files; stale entries (dead pid, old heartbeat) are ignored automatically. In a container you can read them yourself to find the port/token for raw HTTP against `http://127.0.0.1:/api/...`. ## Pixels: when you need xvfb-run + software GL `--headless` uses the dummy renderer: **no pixels, ever**. Any path that renders an image needs a real (virtual) display: | Needs xvfb + GL | Pure headless is fine | | - | - | | `summer_screenshot` scene previews (ScenePreview images) | Scene mutation, inspection, scene tree reads | | GameSnapshot / viewport captures | Diagnostics, script errors, console | | RunVerification frames (`--summer-verify` probes) | Imports, exports, navmesh/collision baking | | Anything judged by looking at a frame | Play/stop, project context, file ops | Most cloud containers have no Vulkan device. The working recipe is X virtual framebuffer plus Mesa's software rasterizer (llvmpipe), driving the GL compatibility renderer: ```bash theme={null} apt-get install -y xvfb libgl1-mesa-dri # names vary by distro xvfb-run -a --path --rendering-driver opengl3 ... ``` Limitations: * **No Vulkan in most containers** → Forward+/Mobile renderers are unavailable; you get software GL (Compatibility). Colors and composition are trustworthy; GPU-specific effects, performance numbers, and driver-dependent output are not. * Software rendering is slow. Budget seconds per frame, not milliseconds, and never quote FPS measured this way. * If a render tool returns a null/blank image in a container, check for a display before suspecting the scene: no `$DISPLAY` means no pixels. ## Authentication without a browser * **Engine ops: nothing to do.** The local API token is auto-generated; `summer login` is never required for them. * **Gateway features** (asset search, generation, releases): set `SUMMER_TOKEN` to a CLI token from a logged-in machine (`~/.summer/auth-token`). It overrides the stored file for that process only. ```bash theme={null} export SUMMER_TOKEN="$(cat ~/.summer/auth-token)" # gateway: assets/generation/releases ``` Treat it as a secret: env-inject it from the runner's secret store, never bake it into images or logs. Without it, gateway tools fail with a clear "not signed in" message — everything else keeps working. ## Red Flags — STOP | Red flag | Reality | | - | - | | "Linux isn't supported, download manually" | `summer install` supports Linux x86\_64; set `SUMMER_ENGINE_BINARY` when the container has its own build. | | Running `summer login` in a container | There is no browser. Engine ops need no login; gateway needs `SUMMER_TOKEN`. | | Screenshot/preview attempted under plain `--headless` | Dummy renderer, null image. Use `xvfb-run` + `--rendering-driver opengl3`. | | Expecting Forward+ output in a container | No Vulkan device in most containers. Software GL (Compatibility) is what you get. | | Quoting performance numbers from a software-GL run | llvmpipe measures the CPU, not the game. | | Polling the engine before it finished booting | Give it seconds; watch `summer doctor` / `~/.summer/instances/`. | | Baking a token into an image or committing it | Tokens are secrets. Env-inject at runtime. | **Related skills:** * `headless-scripting` — the headless invocation contract, exit-code traps, and what scripts unlock. * `playtesting-a-feature` — the verify instance and probes (run them under xvfb in the cloud). * `verification-before-completion` — judging work by artifacts, which matters more when nobody can see a screen. ## From a shell No Summer MCP tools in this session? Run each one as a command; when `summer --version` is missing or below 4.0, use `npx -y summer-engine@latest` in place of `summer`. Fields are flags in kebab-case (`--scene-path res://main.tscn`) or one `--input ''`, and `summer ops describe ` prints the exact input. The `summer-cli` skill has the rest. | In this skill | Command | | - | - | | `summer_screenshot` | `summer engine screenshot` | ## Related skills * [`headless-scripting`](/skills/headless-scripting): Run a GDScript file against Summer Engine from the shell for what no MCP tool does: navmesh, TileSets. * [`playtesting-a-feature`](/skills/playtesting-a-feature): Before calling a gameplay feature done, run the game and walk through it. Static checks do not count. * [`verification-before-completion`](/skills/verification-before-completion): Run verification and read its output before claiming work done, fixed or passing: evidence first. *** Source: [`library/skills/running-in-the-cloud/SKILL.md`](https://github.com/SummerEngine/summer/blob/main/library/skills/running-in-the-cloud/SKILL.md), rendered from `summer-engine@4.3.0` on npm. This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.