Skip to content
View as Markdown

Configuration Reference ​

All Muxit server settings live in workspace/config/server.json. You can edit this file directly or use the Settings panel in the web UI.

File Location ​

server.json lives inside your workspace, not next to the executable:

<workspace>/config/server.json

Not sure where your workspace is? The server logs Workspace: <path> on startup, and the title bar carries a Workspace: <name> menu naming the active one. Typical locations:

CasePath
Default (portable / installed)workspace/ next to muxit.exe
Install directory not writable%LOCALAPPDATA%\Muxit\workspace (Windows), ~/.muxit/workspace (macOS / Linux)
Dev checkout<repo>/workspace
Explicitwhatever you passed to --workspace

The file is created on first run, so a fresh install already has one.

Changes to this file require a server restart to take effect (except where noted).


Server ​

WebSocket ​

json
{
  "websocket": {
    "port": 8765
  }
}
FieldTypeDefaultDescription
websocket.portint8765WebSocket server port. Also serves the web UI

Override at startup: node start.js server --port=9000

Polling Rates ​

json
{
  "polling": {
    "connectorRate": 200,
    "broadcastRate": 50,
    "clientFlushRate": 100
  }
}
FieldTypeDefaultUnitDescription
polling.connectorRateint200msHow often to poll connector properties
polling.broadcastRateint50msHow often to batch state changes for WebSocket
polling.clientFlushRateint100msHow often clients flush pending state updates

Tuning tip: If you have many polled properties and see high CPU, increase connectorRate to 500 or 1000. The default 200ms (5 polls/second) is a good balance for most setups.

Logging ​

json
{
  "logging": {
    "level": "info"
  }
}
FieldTypeDefaultDescription
logging.levelstring"info"Minimum log level: debug, info, warn, error

Connectors ​

json
{
  "connectors": {
    "enabled": ["test-device", "webcam", "mqtt"]
  }
}
FieldTypeDefaultDescription
connectors.enabledstring[](auto)List of enabled connector names. If absent, the first N connectors are auto-selected based on your license tier

Connector names correspond to filenames in workspace/connectors/ (without .js). The TestDevice is always enabled regardless of this list.

Manage this from the Hardware panel — check/uncheck connectors and click Save.


Scripts ​

json
{
  "scripts": {
    "directory": "./scripts",
    "autoStart": []
  }
}
FieldTypeDefaultDescription
scripts.directorystring"./scripts"Path to the scripts directory (relative to workspace)
scripts.autoStartstring[][]Script names to start automatically on server launch

Auto-start example: "autoStart": ["monitor", "mqtt-connect"] runs these scripts when the server starts.


Drivers ​

json
{
  "drivers": {
    "directory": "./drivers"
  }
}
FieldTypeDefaultDescription
drivers.directorystring"./drivers"Path to the drivers directory (relative to workspace). Holds installed .muxdriver packages and (optionally) hand-dropped .driver.js files. Each .muxdriver is extracted on load into a hidden .cache/<id>@<version>/ inside this directory

AI ​

json
{
  "ai": {
    "provider": "muxit",
    "model": "anthropic/claude-haiku-4-5",
    "maxTokens": 2048,
    "instructions": "You are Muxit AI, an assistant for a hardware lab.",
    "historyMaxTurns": 12,
    "deviceSchemas": "adaptive",
    "cacheBreakpoints": false,
    "providers": {
      "ollama":   { "baseUrl": "http://localhost:11434/v1", "model": "llama3.2" },
      "lmstudio": { "baseUrl": "http://localhost:1234/v1", "model": "auto" }
    }
  }
}
FieldTypeDefaultDescription
ai.providerstring"muxit"LLM backend — "muxit" (cloud proxy), "ollama", "lmstudio", or "openai-compatible"
ai.modelstringprovider defaultActive model id. Cloud uses OpenRouter ids (anthropic/claude-haiku-4-5); local providers use the loaded model name (llama3.2, auto)
ai.maxTokensint2048Max output tokens per response, editable as Max response tokens in Settings → AI Services. Raise for code-generation flows; the lower default keeps general-chat replies tight. A tool call that runs past this cap is refused with AI_OUTPUT_TRUNCATED rather than executed with partial arguments — see the AI guide
ai.instructionsstring""Custom system prompt prepended to AI conversations
ai.promptProfilestring"standard""standard" keeps the full safety-confirmation fragment and the decision-tree guidance; "minimal" strips both for local LLMs with 4–8K context windows and forces ai.deviceSchemas = "minimal" regardless of that setting
ai.historyMaxTurnsint12Conversation history is capped at this many user turns; older turns are replaced with a single context-notice line. Set to 0 to disable trimming
ai.deviceSchemasstring"adaptive"How the system prompt presents ## Connected Devices. "full" always inlines the per-device property/action schema (bytes per device); "minimal" always emits a one-line summary and tells the model to call get_connector_schema(name) on demand; "adaptive" (default) picks minimal unless the user's turn looks like a device interaction (verbs like read/write/set/measure, physical-units keywords, or an explicit connector name)
ai.cacheBreakpointsboolfalseAttach Anthropic cache_control: ephemeral markers to the system prompt so the upstream caches it across turns. Default off until the Muxit cloud proxy is confirmed to forward the markers — see docs/reference/ai-token-budget.md. No effect on local OpenAI-compatible providers
ai.favoriteModelsstring[][]Model IDs shown in the model picker (e.g., ["anthropic/claude-sonnet-4-5"])
ai.providers.<id>.baseUrlstringper providerEndpoint for local providers — http://localhost:11434/v1 for Ollama, http://localhost:1234/v1 for LM Studio
ai.providers.<id>.apiKeystring""Optional bearer token for openai-compatible endpoints
ai.providers.<id>.modelstringper providerPer-provider default model — used when the active provider is switched

AI tool-call approval prompts are driven by the global safety level (see the Safety Guide), not by a separate ai config key.

The default Muxit AI cloud provider authenticates with your license key — no separate API keys needed. Local providers (Ollama, LM Studio, OpenAI-compatible) are free on every tier, including Free; once enabled they bypass the cloud entirely so chat, scripts, agents, and vision all run on your own hardware.

For detailed AI setup, see the AI & Voice Guide.


Voice ​

json
{
  "voice": {
    "stt": {
      "provider": "browser",
      "providers": {
        "browser": {
          "language": "en-US"
        }
      }
    },
    "tts": {
      "enabled": false,
      "provider": "browser",
      "providers": {
        "browser": {
          "voice": "Google UK English Male",
          "rate": 1.1,
          "pitch": 0.9
        }
      }
    },
    "wakeWord": {
      "enabled": false,
      "word": "muxit",
      "sensitivity": 0.5
    },
    "autoSend": true
  }
}
FieldTypeDefaultDescription
voice.stt.providerstring"browser"Speech-to-text provider (browser Web Speech API)
voice.stt.providers.browser.languagestring"en-US"STT language code
voice.tts.enabledbooleanfalseEnable text-to-speech for AI responses
voice.tts.providers.browser.voicestringvariesTTS voice name (browser-dependent)
voice.tts.providers.browser.ratenumber1.0Speech rate (0.5–2.0)
voice.tts.providers.browser.pitchnumber1.0Speech pitch (0.5–2.0)
voice.wakeWord.enabledbooleanfalseEnable "Muxit" wake word for hands-free activation
voice.wakeWord.wordstring"muxit"Wake word to listen for
voice.wakeWord.sensitivitynumber0.5Wake word detection sensitivity (0–1)
voice.autoSendbooleantrueAuto-send voice transcription when user pauses

For detailed voice setup, see the AI & Voice Guide.


UI ​

json
{
  "ui": {
    "operatorDashboard": "operator/station.dashboard.json"
  }
}
FieldTypeDefaultDescription
ui.operatorDashboardstring—Dashboard the operator shell opens on (Settings › Accounts › Operator dashboards). Omit to use the first one found

The operator shell's read-only AI chat has no config key: it is a per-dashboard flag, "chat": true at the top level of the dashboard file (Operator chat in the dashboard editor's settings).

Operator mode shows only the dashboards and scripts placed in the operator/ sub-folders of workspace/dashboards/ and workspace/scripts/. There is no switch for it here: a signed-in operator always gets the operator shell, and every anonymous browser gets it when the anonymous-visitor policy in accounts.json is "dashboard" (Settings › Accounts › Anonymous visitors). Under that policy the server enforces it: every anonymous client is held to a write gate that refuses authoring, the marketplace, safety-level changes, AI traffic and the /mcp endpoint (OPERATOR_MODE_RESTRICTED). The editor API and the immediate window are refused per request rather than switched off, so a signed-in engineer or admin still reaches them — and can change the policy from Settings, with no restart. Requires a Pro license (with a 60-day grace if one lapses); a station whose license does not cover it runs unlocked and the startup banner says so.

A single device can opt in without changing config by loading ?view=operator — that is presentation only and enforces nothing.

Who may sign in is not configured here. Accounts and the sign-in policy live in workspace/config/accounts.json — see below.


Accounts — config/accounts.json ​

Written by the server from Settings › Accounts; you do not normally edit it. Requires a Pro license (with the same 60-day grace as operator mode); on a lower tier the file is ignored and the startup banner says so.

json
{
  "anonymous": "full",
  "idleTimeoutMinutes": 15,
  "accounts": [
    { "id": "root",    "name": "Root",     "role": "admin",    "pinHash": "…", "salt": "…" },
    { "id": "m.chen",  "name": "M. Chen",  "role": "engineer", "pinHash": "…", "salt": "…" },
    { "id": "j.smith", "name": "J. Smith", "role": "operator", "pinHash": "…", "salt": "…" }
  ]
}
FieldTypeDefaultDescription
anonymousstring"full"What a connection that has not signed in gets. full: everything, signing in adds a name. dashboard: the operator shell only, held to the operator gate — this is what turns operator mode on (Pro license). login: may read but not act, and the full interface asks for an engineer or admin first. Anything else reads as full
idleTimeoutMinutesnumber15Sessions end after this long with no activity (1–480)
accounts[].idstring—Letters, digits, dots, dashes, underscores. Appears in audit rows
accounts[].namestringidDisplay name
accounts[].rolestring"operator"admin, engineer or operator. Anything else is an operator
accounts[].pinHash, saltstring—PBKDF2-SHA256, 100 000 iterations, base64. Never the PIN itself

Lives here rather than in server.json because server.json is writable by any engineer through config.set, and the sign-in policy must be an admin's to change. No file means no accounts and no sign-in. A corrupt file loads as no accounts. Deleting the file is the recovery path when the last admin's PIN is lost. See the Accounts guide.


Security ​

json
{
  "security": {
    "editorMode": true,
    "remoteAccess": false,
    "https": false,
    "bindAddress": "127.0.0.1"
  }
}
FieldTypeDefaultDescription
security.editorModebooleantrueFile explorer, code editor, and immediate window. On by default; set to false for a read-only workspace
security.remoteAccessbooleanfalseBind to all interfaces (0.0.0.0) for LAN access
security.httpsbooleanfalseEnable HTTPS with auto-generated self-signed certificate
security.bindAddressstring"127.0.0.1"Override bind address (advanced). Set to 0.0.0.0 for all interfaces
security.hostnamesstring[][]Extra host names a browser may use to reach Muxit — a Tailscale MagicDNS name, a tunnel or reverse-proxy name. Exact names, or *.example.com for every subdomain of a domain you control. A bare * is ignored. Restart after changing it. See Host names
security.allowExternalTransportsbooleanfalseLet connector and driver JS open TCP transports to hosts outside the local network. Off by default: createTcpTransport() reaches loopback and private ranges (10/8, 172.16/12, 192.168/16, 169.254/16) only. Prefer a connector's allowedHosts for a single endpoint

Editor mode is enabled by default — a fresh install can create and edit connectors and scripts straight away. It is also togglable from Settings › Server › Editor Mode (restart the server afterwards). When it is off, the file explorer shows a notice, /api/editor/* is not registered, and scripts.execute (the immediate window) is rejected.

The config/ directory is never readable or writable through the editor API, and drivers/ is never writable, in either mode. Paths are resolved before they are checked, so scripts/../config/server.json and ./config/server.json are refused the same way config/server.json is, and nothing outside the workspace is reachable at all.

Host names. Muxit answers only to the names it knows are its own: localhost, 127.0.0.1, [::1], the address a connection arrived on, the names in security.hostnames, and — with remote access on — this machine's host name, <host>.local and the mDNS name. Any other Host header gets 403 with code: "HOST_NOT_ALLOWED". That is what stops a website from reaching Muxit by DNS rebinding.

Remote access password is stored separately in workspace/config/security.json (hashed, never plaintext). With remote access on and no password set, other computers are refused until one is set.

For detailed remote access setup, see the Remote Access Guide.


Complete Example ​

Here's a fully annotated server.json:

json
{
  "websocket": {
    "port": 8765
  },
  "polling": {
    "connectorRate": 200,
    "broadcastRate": 50,
    "clientFlushRate": 100
  },
  "logging": {
    "level": "info"
  },
  "scripts": {
    "directory": "./scripts",
    "autoStart": []
  },
  "drivers": {
    "directory": "./drivers"
  },
  "connectors": {
    "enabled": ["test-device", "webcam"]
  },
  "ai": {
    "provider": "muxit",
    "model": "anthropic/claude-haiku-4-5",
    "maxTokens": 2048,
    "instructions": ""
  },
  "voice": {
    "tts": { "enabled": false },
    "wakeWord": { "enabled": false },
    "autoSend": true
  },
  "security": {
    "editorMode": true,
    "bindAddress": "127.0.0.1"
  }
}

Muxit — Hardware Orchestration Platform