Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/nestrilabs/nestri/llms.txt

Use this file to discover all available pages before exploring further.

Maitred is a Go daemon that sits between the Nestri cloud and your local Docker engine. When a user requests a game session through nestri.io, maitred receives the request via SST Realtime (an MQTT-based channel), creates a runner container, starts it, and monitors it for the duration of the session. It also automatically creates and starts a local relay container on every startup.
Maitred is intended for deployments that are connected to the Nestri managed cloud. If you are self-hosting everything independently and managing containers manually, you do not need to run maitred.

​
Docker image

ghcr.io/nestrilabs/nestri/maitred:nightly
The image is built from containerfiles/maitred.Containerfile. It is a two-stage Go build on golang:1.24-bookworm with pciutils installed in the runtime layer for GPU detection.

​
Startup sequence

The following describes the exact order of operations in cloud/packages/maitred/main.go:
1

Parse flags and configure logging

Maitred calls internal.InitFlags() to read all configuration from command-line flags and environment variables. If --verbose (or VERBOSE=true) is set, the logger is set to debug level. If --debug is set, verbose is also implied.
2

Start system monitoring (unless disabled)

Unless --no-monitor is set, maitred calls system.StartMonitoring(ctx, 5*time.Second). This goroutine collects CPU, memory, and GPU metrics every 5 seconds and makes them available for reporting.
3

Retrieve machine ID

system.GetID() reads /var/lib/dbus/machine-id (falling back to /etc/machine-id) and logs it. This ID uniquely identifies the host to the Nestri cloud.
4

Initialize container engine

containers.NewContainerEngine() attempts to connect to the Docker daemon. If Docker is unavailable, maitred logs the error and exits. The engine is closed with a deferred cleanup that runs on shutdown.
5

Initialize container manager

realtime.InitializeManager(ctx, ctrEngine) performs startup cleanup:
  • Finds any leftover runner containers from a previous maitred run (matching ghcr.io/nestrilabs/nestri/runner:nightly) and stops and removes them.
  • Finds any leftover relay containers and removes them.
  • In normal mode (not debug), pulls the latest runner image (ghcr.io/nestrilabs/nestri/runner:nightly) and relay image (ghcr.io/nestrilabs/nestri/relay:nightly) from the registry.
6

Connect to SST Realtime (skipped in debug mode)

Unless --debug is set, maitred initializes the SST resource configuration and calls realtime.Run(ctx, machineID, ctrEngine, res). This establishes the MQTT connection to the Nestri cloud and starts listening for session management messages (create runner, start runner, remove runner).
7

Create and start the relay container

Regardless of mode, maitred calls realtime.CreateRelay and then realtime.StartRelay to bring up a local relay container. A background monitor goroutine watches the relay at 10-second intervals and logs its output if it stops unexpectedly. Only one relay container is allowed at a time (CountRelays() >= 1 returns an error if another exists).
8

Wait for shutdown signal

Maitred blocks on <-mainCtx.Done(), waiting for SIGINT or SIGTERM. On signal receipt, the deferred cleanup runs: all managed containers (runners and the relay) are stopped and removed with a 30-second timeout before the Docker engine connection is closed.

​
Flags and environment variables

All flags can be set via environment variables with the same name in uppercase.
​
flag.--verbose
boolean
default:"false"
Enable debug-level logging. Equivalent to setting VERBOSE=true. Implied by --debug.
​
flag.--debug
boolean
default:"false"
Enable debug mode. Implies --verbose. In debug mode, maitred skips the SST/MQTT connection to the Nestri cloud and uses alternative image names (ghcr.io/datcaptainhorse/nestri-cachyos:latest-v3 for runners and ghcr.io/datcaptainhorse/nestri-relay:latest for the relay). It also skips pulling images at startup.Use debug mode when testing maitred locally without a Nestri cloud account.
​
flag.--no-monitor
boolean
default:"false"
Disable the system monitoring goroutine. When set, maitred does not collect CPU, memory, or GPU metrics. Equivalent to NO_MONITOR=true.

​
Container lifecycle management

Maitred tracks all containers it creates in an in-memory map (managedContainers in realtime/managed.go). Each entry records the container ID, name, state, image, and type (Runner or Relay). Runner limits: Maitred enforces a hard limit of 4 simultaneous runner containers (CountRunners() >= 4 returns an error). This is a safety guard — the actual capacity of your host depends on GPU memory and CPU headroom. Relay limit: Only one relay container is managed at a time. Cleanup on shutdown: The deferred cleanup in main.go calls realtime.CleanupManaged with a 30-second context. It iterates all managed containers, stops any that are in running state, and removes them. If the timeout is exceeded, the cleanup returns an error but the process exits regardless. Per-container monitoring: Both StartRunner and StartRelay launch a background goroutine (monitorContainer) that inspects the container every 10 seconds. If the container stops running, the goroutine fetches the container logs and returns an error that is logged by the caller.

​
Running maitred

docker run -d \
  --name nestri-maitred \
  -v /var/run/docker.sock:/var/run/docker.sock \
  -e VERBOSE=true \
  --restart unless-stopped \
  ghcr.io/nestrilabs/nestri/maitred:nightly
Maitred requires access to the Docker socket to create and manage containers. Mount /var/run/docker.sock from the host.

​
Debug mode (no cloud connection)

docker run --rm \
  --name nestri-maitred-debug \
  -v /var/run/docker.sock:/var/run/docker.sock \
  -e DEBUG=true \
  ghcr.io/nestrilabs/nestri/maitred:nightly
In debug mode, maitred starts with alternative development images, skips pulling them, and does not attempt to connect to the Nestri cloud SST/MQTT endpoint. The relay container still starts automatically.

​
Machine ID

Maitred reads the machine ID from /var/lib/dbus/machine-id (falling back to /etc/machine-id) at startup. This ID is used to identify the host to the Nestri cloud. If neither file exists inside the container, system.GetID() returns an error and maitred logs it — it does not exit, but the machine will be unidentifiable to the cloud. To use the host machine’s ID inside the container, bind-mount it: 
-v /etc/machine-id:/etc/machine-id:ro

​
Graceful shutdown

Send SIGINT or SIGTERM to maitred to trigger a graceful shutdown. It will:
  1. Stop and remove all managed runner containers.
  2. Stop and remove the managed relay container.
  3. Close the Docker engine connection.
  4. Exit with code 0 if cleanup succeeded, or log errors and exit if any step failed within the 30-second timeout.

Build docs developers (and LLMs) love

Get started for freeTalk to us