Generated reference

Configuration, with every tradeoff attached.

Network #

Controller network listeners and proxies.

Only the console listener may bind beyond loopback.

server:
  httpAddress: ":8080"

Default console

server:
  httpAddress: ":8080"

`server.httpAddress` #

Exposes the management console.

Open this option in the local console

Type: string
Presence: Required
Default: ":8080"
Allowed values: Any value satisfying the constraints
Constraints: {"maxLength":255,"minLength":1}
Restart: controller
Secret: No
Legacy environment variable: VM_HTTP_ADDR

`server.desktopProxyURL` #

Connects the controller to noVNC.

Open this option in the local console

Type: string
Presence: Required
Default: "http://127.0.0.1:6080"
Allowed values: Any value satisfying the constraints
Constraints: {"maxLength":2048,"minLength":1}
Restart: controller
Secret: No

Desktop #

Virtual desktop, browser, VNC, and CDP settings.

All desktop service endpoints remain loopback-only.

Open Desktop in the local console

desktop:
  resolution: 1600x900x24

HD desktop

desktop:
  resolution: 1600x900x24

`desktop.display` #

Selects the virtual X display.

Open this option in the local console

Type: string
Presence: Required
Default: ":99"
Allowed values: Any value satisfying the constraints
Constraints: {"pattern":"^:[0-9]+$"}
Restart: desktop
Secret: No
Legacy environment variable: VM_DISPLAY

`desktop.resolution` #

Sizes the Xvfb desktop.

Open this option in the local console

Type: string
Presence: Required
Default: "1600x900x24"
Allowed values: Any value satisfying the constraints
Constraints: {"pattern":"^[0-9]+x[0-9]+x(16|24|32)$"}
Restart: desktop
Secret: No
Legacy environment variable: VM_RESOLUTION

`desktop.x11SocketDirectory` #

Locates X11 Unix sockets.

Open this option in the local console

Type: string
Presence: Required
Default: "/tmp/.X11-unix"
Allowed values: Any value satisfying the constraints
Constraints: {"maxLength":4096,"minLength":1}
Restart: desktop
Secret: No
Legacy environment variable: VM_X11_SOCKET_DIR

`desktop.vncAddress` #

Carries the private VNC stream.

Open this option in the local console

Type: string
Presence: Required
Default: "127.0.0.1:5900"
Allowed values: Any value satisfying the constraints
Constraints: {"maxLength":255,"minLength":1}
Restart: desktop
Secret: No
Legacy environment variable: VM_VNC_ADDR

`desktop.noVNCAddress` #

Serves browser-based desktop access.

Open this option in the local console

Type: string
Presence: Required
Default: "127.0.0.1:6080"
Allowed values: Any value satisfying the constraints
Constraints: {"maxLength":255,"minLength":1}
Restart: desktop
Secret: No

`desktop.noVNCUpstreamAddress` #

Connects noVNC to x11vnc.

Open this option in the local console

Type: string
Presence: Required
Default: "127.0.0.1:5900"
Allowed values: Any value satisfying the constraints
Constraints: {"maxLength":255,"minLength":1}
Restart: desktop
Secret: No

`desktop.noVNCHealthURL` #

Checks noVNC readiness.

Open this option in the local console

Type: string
Presence: Required
Default: "http://127.0.0.1:6080/vnc.html"
Allowed values: Any value satisfying the constraints
Constraints: {"maxLength":2048,"minLength":1}
Restart: controller
Secret: No
Legacy environment variable: VM_NOVNC_URL

`desktop.cdpURL` #

Provides read-only browser observations.

Open this option in the local console

Type: string
Presence: Required
Default: "http://127.0.0.1:9222"
Allowed values: Any value satisfying the constraints
Constraints: {"maxLength":2048,"minLength":1}
Restart: desktop
Secret: No

`desktop.chromiumWatchdogGrace` #

Controls browser restart grace.

Open this option in the local console

Type: integer
Presence: Required
Default: 3
Allowed values: Any value satisfying the constraints
Constraints: {"maximum":30,"minimum":1}
Restart: desktop
Secret: No
Legacy environment variable: VM_CHROMIUM_WATCHDOG_GRACE

Services #

Persistent queue and state service.

Open Services in the local console

valkey:
  address: 127.0.0.1:6379

Default

valkey:
  address: 127.0.0.1:6379

`valkey.address` #

Locates the local Valkey service.

Open this option in the local console

Type: string
Presence: Required
Default: "127.0.0.1:6379"
Allowed values: Any value satisfying the constraints
Constraints: {"maxLength":255,"minLength":1}
Restart: valkey
Secret: No
Legacy environment variable: VM_VALKEY_ADDR

Inference #

Local language and vision inference.

Context size trades memory for retained task history.

Open Inference in the local console

Tradeoffs

Larger context: Retains more observations. Uses more memory.

llama:
  contextTokens: 32768
  threads: 8

Local CPU

llama:
  contextTokens: 32768
  threads: 8

`llama.address` #

Locates the local inference server.

Open this option in the local console

Type: string
Presence: Required
Default: "127.0.0.1:8081"
Allowed values: Any value satisfying the constraints
Constraints: {"maxLength":255,"minLength":1}
Restart: llama
Secret: No
Legacy environment variable: VM_LLAMA_PORT

`llama.contextTokens` #

Sets the model context window.

Open this option in the local console

Type: integer
Presence: Required
Default: 32768
Allowed values: Any value satisfying the constraints
Constraints: {"maximum":131072,"minimum":2048}
Restart: llama
Secret: No
Legacy environment variable: VM_LLAMA_CTX

Higher values preserve more task context.

Tradeoffs

32768: Balances task depth and memory. Consumes more KV cache than small contexts.

`llama.modelPath` #

Selects the pinned local model.

Open this option in the local console

Type: string
Presence: Required
Default: "/opt/models/gemma-4-E2B-it-Q4_0.gguf"
Allowed values: Any value satisfying the constraints
Constraints: {"maxLength":4096,"minLength":1}
Restart: llama
Secret: No
Legacy environment variable: VM_MODEL_PATH

`llama.projectorPath` #

Selects the model's vision projector.

Open this option in the local console

Type: string
Presence: Required
Default: "/opt/models/mmproj-gemma-4-E2B-F16.gguf"
Allowed values: Any value satisfying the constraints
Constraints: {"maxLength":4096,"minLength":1}
Restart: llama
Secret: No
Legacy environment variable: VM_MMPROJ_PATH

`llama.threads` #

Controls CPU inference parallelism.

Open this option in the local console

Type: integer
Presence: Required
Default: 0
Allowed values: Any value satisfying the constraints
Constraints: {"maximum":1024,"minimum":0}
Restart: llama
Secret: No
Legacy environment variable: VM_THREADS

`llama.chatCompletionsURL` #

Connects the controller to llama.cpp chat.

Open this option in the local console

Type: string
Presence: Required
Default: "http://127.0.0.1:8081/v1/chat/completions"
Allowed values: Any value satisfying the constraints
Constraints: {"maxLength":2048,"minLength":1}
Restart: controller
Secret: No

Speech #

Offline text-to-speech service.

Open Speech in the local console

tts:
  cacheMaxMiB: 256

Default cache

tts:
  cacheMaxMiB: 256

`tts.address` #

Locates the local TTS daemon.

Open this option in the local console

Type: string
Presence: Required
Default: "127.0.0.1:8082"
Allowed values: Any value satisfying the constraints
Constraints: {"maxLength":255,"minLength":1}
Restart: ttsd
Secret: No
Legacy environment variable: VM_TTS_PORT

`tts.healthURL` #

Checks TTS readiness.

Open this option in the local console

Type: string
Presence: Required
Default: "http://127.0.0.1:8082/healthz"
Allowed values: Any value satisfying the constraints
Constraints: {"maxLength":2048,"minLength":1}
Restart: controller
Secret: No
Legacy environment variable: VM_TTS_HEALTH_URL

`tts.sherpaDirectory` #

Locates the speech runtime.

Open this option in the local console

Type: string
Presence: Required
Default: "/opt/sherpa-onnx"
Allowed values: Any value satisfying the constraints
Constraints: {"maxLength":4096,"minLength":1}
Restart: ttsd
Secret: No
Legacy environment variable: VM_SHERPA_DIR

`tts.modelDirectory` #

Locates the pinned voice model.

Open this option in the local console

Type: string
Presence: Required
Default: "/opt/models/tts"
Allowed values: Any value satisfying the constraints
Constraints: {"maxLength":4096,"minLength":1}
Restart: ttsd
Secret: No
Legacy environment variable: VM_TTS_MODEL_DIR

`tts.cacheDirectory` #

Stores disposable rendered sentences.

Open this option in the local console

Type: string
Presence: Required
Default: "${data}/tts-cache"
Allowed values: Any value satisfying the constraints
Constraints: {"maxLength":4096,"minLength":1}
Restart: ttsd
Secret: No
Legacy environment variable: VM_TTS_CACHE_DIR

`tts.cacheMaxMiB` #

Bounds disposable speech cache storage.

Open this option in the local console

Type: integer
Presence: Required
Default: 256
Allowed values: Any value satisfying the constraints
Constraints: {"maximum":65536,"minimum":1}
Restart: ttsd
Secret: No
Legacy environment variable: VM_TTS_CACHE_MAX_MB

`tts.maxCharacters` #

Bounds individual synthesis requests.

Open this option in the local console

Type: integer
Presence: Required
Default: 4096
Allowed values: Any value satisfying the constraints
Constraints: {"maximum":65536,"minimum":1}
Restart: ttsd
Secret: No
Legacy environment variable: VM_TTS_MAX_CHARS

Agent #

Browser-agent execution limits and tools.

Open Agent in the local console

agent:
  maxSteps: 100

Short tasks

agent:
  maxSteps: 100

`agent.maxSteps` #

Bounds autonomous task length.

Open this option in the local console

Type: integer
Presence: Required
Default: 500
Allowed values: Any value satisfying the constraints
Constraints: {"maximum":5000,"minimum":1}
Restart: controller
Secret: No
Legacy environment variable: VM_AGENT_MAX_STEPS

`agent.keepTasks` #

Bounds retained task artifacts.

Open this option in the local console

Type: integer
Presence: Required
Default: 20
Allowed values: Any value satisfying the constraints
Constraints: {"maximum":1000,"minimum":1}
Restart: controller
Secret: No
Legacy environment variable: VM_AGENT_KEEP_TASKS

`agent.xdotoolPath` #

Provides OS-level browser input.

Open this option in the local console

Type: string
Presence: Required
Default: "xdotool"
Allowed values: Any value satisfying the constraints
Constraints: {"maxLength":4096,"minLength":1}
Restart: controller
Secret: No
Legacy environment variable: VM_XDOTOOL

`agent.scrotPath` #

Captures the virtual desktop.

Open this option in the local console

Type: string
Presence: Required
Default: "scrot"
Allowed values: Any value satisfying the constraints
Constraints: {"maxLength":4096,"minLength":1}
Restart: controller
Secret: No

`agent.convertPath` #

Prepares screenshots for vision.

Open this option in the local console

Type: string
Presence: Required
Default: "convert"
Allowed values: Any value satisfying the constraints
Constraints: {"maxLength":4096,"minLength":1}
Restart: controller
Secret: No

`agent.bashPath` #

Runs bounded local shell tools.

Open this option in the local console

Type: string
Presence: Required
Default: "bash"
Allowed values: Any value satisfying the constraints
Constraints: {"maxLength":4096,"minLength":1}
Restart: controller
Secret: No

`agent.systemManifestPath` #

Grounds the agent in installed capabilities.

Open this option in the local console

Type: string
Presence: Required
Default: "/opt/agent/system-manifest.json"
Allowed values: Any value satisfying the constraints
Constraints: {"maxLength":4096,"minLength":1}
Restart: controller
Secret: No

Mail #

Outbound mail identity, relay, and queue.

Credentials are stored only as environment or file references.

Open Mail in the local console

mail:
  smarthost:
    host: ""

Direct delivery

mail:
  smarthost:
    host: ""

`mail.mailname` #

Sets the outbound mail hostname.

Open this option in the local console

Type: string
Presence: Required
Default: ""
Allowed values: Any value satisfying the constraints
Constraints: {"maxLength":255,"minLength":0}
Restart: mail
Secret: No
Legacy environment variable: VM_MAIL_MAILNAME

`mail.from` #

Sets the default sender identity.

Open this option in the local console

Type: string
Presence: Required
Default: ""
Allowed values: Any value satisfying the constraints
Constraints: {"maxLength":320,"minLength":0}
Restart: controller
Secret: No
Legacy environment variable: VM_MAIL_FROM

`mail.smarthost.host` #

Selects direct or relay delivery.

Open this option in the local console

Type: string
Presence: Required
Default: ""
Allowed values: Any value satisfying the constraints
Constraints: {"maxLength":255,"minLength":0}
Restart: mail
Secret: No
Legacy environment variable: VM_MAIL_SMARTHOST

`mail.smarthost.port` #

Selects the relay submission port.

Open this option in the local console

Type: integer
Presence: Required
Default: 587
Allowed values: Any value satisfying the constraints
Constraints: {"maximum":65535,"minimum":1}
Restart: mail
Secret: No
Legacy environment variable: VM_MAIL_SMARTHOST_PORT

`mail.smarthost.username` #

Authenticates to the relay.

Open this option in the local console

Type: string
Presence: Required
Default: ""
Allowed values: Any value satisfying the constraints
Constraints: {"maxLength":512,"minLength":0}
Restart: mail
Secret: No
Legacy environment variable: VM_MAIL_SMARTHOST_USER

`mail.smarthost.password` #

References relay credentials without persisting bytes.

Open this option in the local console

Type: string
Presence: Required
Default: ""
Allowed values: Any value satisfying the constraints
Constraints: {"maxLength":4096,"minLength":0}
Restart: mail
Secret: Yes (credential)
Legacy environment variable: VM_MAIL_SMARTHOST_PASS

Secret reference policy

Environment references: allowed
File references: allowed
Cache TTL: 300 seconds

Use an environment reference, an absolute file reference, or a file beneath the data directory with ${file:${data}/relative/path}.

`mail.dkimDomain` #

Enables DKIM signing when non-empty.

Open this option in the local console

Type: string
Presence: Required
Default: ""
Allowed values: Any value satisfying the constraints
Constraints: {"maxLength":255,"minLength":0}
Restart: controller
Secret: No
Legacy environment variable: VM_MAIL_DKIM_DOMAIN

`mail.dkimSelector` #

Names the DKIM public key record.

Open this option in the local console

Type: string
Presence: Required
Default: "virtualme"
Allowed values: Any value satisfying the constraints
Constraints: {"maxLength":63,"minLength":1,"pattern":"^[A-Za-z0-9][A-Za-z0-9_-]*$"}
Restart: controller
Secret: No
Legacy environment variable: VM_MAIL_DKIM_SELECTOR

`mail.flushSeconds` #

Controls deferred delivery retries.

Open this option in the local console

Type: integer
Presence: Required
Default: 60
Allowed values: Any value satisfying the constraints
Constraints: {"maximum":86400,"minimum":5}
Restart: mail
Secret: No
Legacy environment variable: VM_MAIL_FLUSH_SEC

`mail.sendmailPath` #

Submits composed messages to dma.

Open this option in the local console

Type: string
Presence: Required
Default: "/usr/sbin/sendmail"
Allowed values: Any value satisfying the constraints
Constraints: {"maxLength":4096,"minLength":1}
Restart: controller
Secret: No
Legacy environment variable: VM_SENDMAIL_PATH

`mail.spoolDirectory` #

Stores queued outbound messages.

Open this option in the local console

Type: string
Presence: Required
Default: "${data}/mail/spool"
Allowed values: Any value satisfying the constraints
Constraints: {"maxLength":4096,"minLength":1}
Restart: mail
Secret: No
Legacy environment variable: VM_MAIL_SPOOL_DIR

Health #

Controller health-probe targets.

Open Health in the local console

health:
  xdotoolPath: xdotool

Defaults

health:
  xdotoolPath: xdotool

`health.llamaURL` #

Checks inference readiness.

Open this option in the local console

Type: string
Presence: Required
Default: "http://127.0.0.1:8081/health"
Allowed values: Any value satisfying the constraints
Constraints: {"maxLength":2048,"minLength":1}
Restart: controller
Secret: No
Legacy environment variable: VM_LLAMA_HEALTH_URL

`health.xdotoolPath` #

Checks desktop input capability.

Open this option in the local console

Type: string
Presence: Required
Default: "xdotool"
Allowed values: Any value satisfying the constraints
Constraints: {"maxLength":4096,"minLength":1}
Restart: controller
Secret: No
Legacy environment variable: VM_XDOTOOL

Integrations #

Optional external integrations.

External integrations explicitly cross the local privacy boundary.

Open Integrations in the local console

integrations: {}

`integrations.telegram.enabled` #

Enabling starts outbound HTTPS long polling after token resolution and allowlist validation.

Open this option in the local console

Type: boolean
Presence: Required
Default: false
Allowed values: Any value satisfying the constraints
Constraints: None
Restart: controller
Secret: No

`integrations.telegram.botToken` #

References the BotFather token without persisting credential bytes.

Open this option in the local console

Type: string
Presence: Required
Default: ""
Allowed values: Any value satisfying the constraints
Constraints: {"maxLength":4096,"minLength":0}
Restart: controller
Secret: Yes (credential)

Secret reference policy

Environment references: allowed
File references: allowed
Cache TTL: 300 seconds
Resolved when integrations.telegram.enabled equals true

A non-empty whole-scalar environment, absolute file, or ${file:${data}/relative/path} reference is required while enabled.

`integrations.telegram.allowedChatIds` #

Required chat allowlist; every inbound and test-send chat must match.

Open this option in the local console

Type: array
Presence: Required
Default: []
Allowed values: Any value satisfying the constraints
Constraints: {"uniqueItems":true}
Restart: controller
Secret: No

Array item

Canonical decimal Telegram chat ID.

Type: string
Default: "1"
Allowed values: Any value satisfying the constraints
Constraints: {"pattern":"^-?[1-9][0-9]*$"}

This list is ANDed with the optional user allowlist.

`integrations.telegram.pollTimeoutSeconds` #

Controls long-poll latency and request cadence.

Open this option in the local console

Type: integer
Presence: Required
Default: 30
Allowed values: Any value satisfying the constraints
Constraints: {"maximum":50,"minimum":1}
Restart: controller
Secret: No

Tradeoffs

Longer timeout: Fewer empty requests. Longer-lived outbound requests.

`integrations.telegram.maxEventLog` #

Bounds the redacted Telegram operator event log.

Open this option in the local console

Type: integer
Presence: Required
Default: 200
Allowed values: Any value satisfying the constraints
Constraints: {"maximum":1000,"minimum":20}
Restart: controller
Secret: No

Selected raw updates may contain inbound message text under the trusted-console model.

Tradeoffs

Larger log: More diagnostics survive. More persistent local metadata.

Configuration, with every tradeoff attached.

Network #

Default console

server.httpAddress #

server.desktopProxyURL #

Desktop #

HD desktop

desktop.display #

desktop.resolution #

desktop.x11SocketDirectory #

desktop.vncAddress #

desktop.noVNCAddress #

desktop.noVNCUpstreamAddress #

desktop.noVNCHealthURL #

desktop.cdpURL #

desktop.chromiumWatchdogGrace #

Services #

Default

valkey.address #

Inference #

Tradeoffs

Local CPU

llama.address #

llama.contextTokens #

Tradeoffs

llama.modelPath #

llama.projectorPath #

llama.threads #

llama.chatCompletionsURL #

Speech #

Default cache

tts.address #

tts.healthURL #

tts.sherpaDirectory #

tts.modelDirectory #

tts.cacheDirectory #

tts.cacheMaxMiB #

tts.maxCharacters #

Agent #

Short tasks

agent.maxSteps #

agent.keepTasks #

agent.xdotoolPath #

agent.scrotPath #

agent.convertPath #

agent.bashPath #

agent.systemManifestPath #

Mail #

Direct delivery

mail.mailname #

mail.from #

mail.smarthost.host #

mail.smarthost.port #

mail.smarthost.username #

mail.smarthost.password #

Secret reference policy

mail.dkimDomain #

mail.dkimSelector #

mail.flushSeconds #

mail.sendmailPath #

mail.spoolDirectory #

Health #

Defaults

health.llamaURL #

health.xdotoolPath #

Integrations #

integrations.telegram.enabled #

integrations.telegram.botToken #

Secret reference policy

Related links

integrations.telegram.allowedChatIds #

Array item

integrations.telegram.pollTimeoutSeconds #

Tradeoffs

integrations.telegram.maxEventLog #

Tradeoffs

`server.httpAddress` #

`server.desktopProxyURL` #

`desktop.display` #

`desktop.resolution` #

`desktop.x11SocketDirectory` #

`desktop.vncAddress` #

`desktop.noVNCAddress` #

`desktop.noVNCUpstreamAddress` #

`desktop.noVNCHealthURL` #

`desktop.cdpURL` #

`desktop.chromiumWatchdogGrace` #

`valkey.address` #

`llama.address` #

`llama.contextTokens` #

`llama.modelPath` #

`llama.projectorPath` #

`llama.threads` #

`llama.chatCompletionsURL` #

`tts.address` #

`tts.healthURL` #

`tts.sherpaDirectory` #

`tts.modelDirectory` #

`tts.cacheDirectory` #

`tts.cacheMaxMiB` #

`tts.maxCharacters` #

`agent.maxSteps` #

`agent.keepTasks` #

`agent.xdotoolPath` #

`agent.scrotPath` #

`agent.convertPath` #

`agent.bashPath` #

`agent.systemManifestPath` #

`mail.mailname` #

`mail.from` #

`mail.smarthost.host` #

`mail.smarthost.port` #

`mail.smarthost.username` #

`mail.smarthost.password` #

`mail.dkimDomain` #

`mail.dkimSelector` #

`mail.flushSeconds` #

`mail.sendmailPath` #

`mail.spoolDirectory` #

`health.llamaURL` #

`health.xdotoolPath` #

`integrations.telegram.enabled` #

`integrations.telegram.botToken` #

`integrations.telegram.allowedChatIds` #

`integrations.telegram.pollTimeoutSeconds` #

`integrations.telegram.maxEventLog` #