Skip to main content
running-in-the-cloud is a skill from the Summer skill library: 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.

​
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:
Swap claude-code for your agent, such as codex or cursor. See Skills 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: 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.
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

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/<id>.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:<port>/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: 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:
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.
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

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 '<json>', and summer ops describe <op> prints the exact input. The summer-cli skill has the rest.
  • headless-scripting: Run a GDScript file against Summer Engine from the shell for what no MCP tool does: navmesh, TileSets.
  • playtesting-a-feature: Before calling a gameplay feature done, run the game and walk through it. Static checks do not count.
  • 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, rendered from summer-engine@4.3.0 on npm.