# Settings (https://docs.neuralisapp.com/machine-core/config-settings)

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](https://docs.neuralisapp.com/enterprise/deployment.md).

## Desktop and lifecycle [#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 [#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 [#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 [#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) |
