GUI Access

GUI access is a special-purpose path for prod-gui containers.

Treat it as a container-scoped capability layered on top of normal readiness checks.

Primary route:

GET /api/containers/<container_id>/gui-url

Use GUI access only for prod-gui containers.

GUI-Capable Create Shape

{
  "name": "demo-gui",
  "image": "prod-gui",
  "working_directory": "/app",
  "memory_limit_mb": 1024,
  "cpu_limit_percent": 50,
  "strict": true,
  "environment": {
    "FOO": "bar"
  }
}

Typical GUI Flow

1

Create a `prod-gui` container

Quilt starts the GUI stack automatically.

2

Wait for readiness

Poll until exec_ready=true, network_ready=true, and gui_ready=true.

3

Request the signed GUI URL

The response contains gui_url.

4

Open it on the backend public host

Quilt serves GUI traffic under /gui/<container_id>/....

Notes

• prod-gui does not accept a custom command
• gui_url is typically a relative path under /gui/<container_id>/...
• Quilt keeps browser assets and the VNC websocket container-scoped
• GET /api/containers/<container_id>/gui is not part of the current contract

Rule of Thumb

Wait for gui_ready=true before requesting the signed URL. exec_ready alone is not enough for a working GUI session.