Settings
machine-core's 26 platform settings and its environment-only infrastructure variables.
machine-core declares 26 platform settings (Config → Platform Settings, category Machine), read at the moment they apply, so an admin edit needs no restart. Some apply on the host at the next call, check or spawn; the rest are snapshotted into a container when it is created, so a running desktop keeps the caps it was born with until it is replaced. Running the desktops — the image, the Docker socket, networking, storage and the lifecycle in operation — is covered in deployment.
Desktop and lifecycle
Five settings also read an environment variable when unset.
| Key | Environment fallback | Default | Applies |
|---|---|---|---|
machineImage | NEURALIS_MACHINE_IMAGE | neuralisapp/webtop-ubuntu-xfce:<version> (the release's own version) | Next spawn — running machines keep their image |
machineDesktopVariant | NEURALIS_MACHINE_DESKTOP_VARIANT | ubuntu-xfce | Next spawn |
machineIdleMinutes | NEURALIS_MACHINE_IDLE_MINUTES | 30 (1–1440) | Next idle check — an idle machine is stopped, never deleted |
machineRecordingTtlHours | NEURALIS_MACHINE_RECORDING_TTL_HOURS | 24 (0–720) | Next sweep — retention for recordings; 0 disables the sweep |
machineKeyComboExceptions | NEURALIS_MACHINE_KEY_COMBO_EXCEPTIONS | (none) | Comma-separated combos exempted from the desktop-key denylist. The host check reads it live; a machine's own check takes it when the machine is created, so re-create an existing machine after changing it |
machineSpawnSmokeSeconds | — | 60 (15–300) | Next spawn — the browser and agent readiness window |
Tool limits
| Key | Default | Range | Applies |
|---|---|---|---|
machineBatchMaxSteps | 50 | 1–50 | Next call — child actions per machine_use batch |
machineBatchBudgetMs | 600000 | 5000–1500000 | Next call — wall-clock budget for one batch |
machineReadMaxCharsDefault | 8000 | 500–120000 | Next read — default cap when maxChars is omitted |
machineReadDomMaxChars | 12000 | 1000–120000 | Next read — HTML/DOM truncation cap |
machineNavTimeoutMs | 60000 | 1000–60000 | Next call — default goto navigation timeout |
machineActionTimeoutMs | 30000 | 500–60000 | Next call — default actionability/wait timeout |
machineExecOutputMaxChars | 8000 | 1000–20000 | Next call — model-visible Webtop shell stdout cap |
machineRecordMaxMs | 120000 | 1000–300000 | Next spawn — recording duration cap |
machineRecordMaxMb | 25 | 1–500 | Next spawn — finished-recording size cap |
machineScreenshotMaxMb | 8 | 1–64 | Next spawn — desktop screenshot payload cap |
machineExecTimeoutCeilingMs | 1800000 | 5000–1800000 | Next spawn — ceiling over an explicit execute.timeout |
machineDetachedLifetimeMaxMs | 86400000 | 60000–86400000 | Next spawn — how long one background command may run before the desktop kills it |
machineDetachedRunsMax | 16 | 1–64 | Next spawn — background commands one machine may run at once |
machineExecOutputMaxBytes | 131072 | 16384–1048576 | Next spawn — in-container stdout/stderr accumulation cap |
machineFsReadMaxBytes | 2097152 | 65536–16777216 | Next spawn — cap on one filesystem read |
machineSidecarBodyLimitMb | 4 | 1–64 | Next spawn — request-body cap, so the largest file writable into the desktop |
Stream
| Key | Default | Applies |
|---|---|---|
machineStreamCssCursor | true | Next spawn — the browser draws the mouse pointer instead of the server compositing it into the video |
machineStreamFramerate | (empty) | Next spawn — framerate, as a range (24-60) or a fixed value |
machineStreamH264Crf | (empty) | Next spawn — video quality factor for every encoder, range or fixed (lower is better quality) |
machineStreamEncoder | (empty) | Next spawn — comma-separated list of video encoders the desktop may offer |
Leaving the last three empty keeps the image's own range AND the picker inside the desktop's own settings panel, while a fixed value locks that picker to what you set. Empty is the setting that leaves the choice with the person watching the screen; set one only to pin every session, for example to cap bandwidth. The value is passed through verbatim and validated by the desktop image, which logs an invalid value and falls back to its own default.
Environment-only infrastructure
Socket, ports, network and sandbox settings are environment-only by design.
| Variable | Default | Purpose |
|---|---|---|
NEURALIS_MACHINE_DOCKER_SOCKET | /var/run/docker.sock | Docker daemon socket |
NEURALIS_MACHINE_SIDECAR_PORT | 9400 | In-container machine-agent HTTP port |
NEURALIS_MACHINE_SECCOMP_UNCONFINED | false | Run sessions with seccomp=unconfined (Chromium compatibility on legacy kernels) |
NEURALIS_MACHINE_SHARED_NETWORK | (detected) | Override the user-defined Docker network shared with Neuralis |
NEURALIS_MACHINE_HOST_ADDRESS | localhost | Host address used in published-port mode (no shared network) |