Workspaces

A workspace is a self-contained folder that holds everything Muxit needs to run your lab: device connectors, automation scripts, dashboards, drivers, and configuration.

What's Inside a Workspace

my-workspace/
  config/         Server settings (server.json, ai-memory.json)
  connectors/     Device configurations (.js files)
  scripts/        Automation scripts (.js files)
  dashboards/     Dashboard layouts (.dashboard.json)
  agents/         AI agent configs (.agent.json)
  drivers/
    community/    Free extension drivers (.dll)
    premium/      Licensed drivers (.dll)
  data/           Sandboxed file storage

First-Run Setup

When you start Muxit for the first time, you'll see a setup screen with two options:

1. Create New Workspace --- Pick a location and name for your workspace. Muxit creates the folder structure automatically.
2. Open Existing Workspace --- Point Muxit at an existing workspace directory.

After setup, Muxit restarts and opens your workspace.

The Workspace Menu

The titlebar shows a Workspace: <name> menu (replacing what used to live under File). Every workspace operation hangs off this one menu:

• Rename Workspace… --- change the display name of the current workspace. The folder on disk is untouched and no restart is needed.
• Switch to (inline list) --- one click switches to any other workspace in your catalog. No dialog.
• Open Workspace… --- open the picker dialog to browse to a workspace that isn't in the catalog yet.
• New Workspace… --- create a new workspace folder + register it.

Creating a New Workspace

From the Workspace menu in the titlebar, select New Workspace…. This opens a dialog where you can specify:

• Location --- The filesystem path where the workspace will be created (e.g., /home/user/my-lab or C:\Users\me\Documents\my-lab).
• Name (optional) --- A friendly name for the workspace. Defaults to the folder name.

Muxit creates the standard directory structure and a minimal server.json configuration file.

Opening an Existing Workspace

From the Workspace menu, select Open Workspace…. The dialog shows:

• A list of all previously opened workspaces, sorted by last-opened time
• The currently active workspace (highlighted with a "current" badge)
• An option to create a new workspace

Click any workspace in the list to switch to it. Muxit will restart automatically with the selected workspace.

Renaming a Workspace

The default name of a workspace is the folder name — so if your workspace lives in ~/workspace/ you'd see "Workspace: workspace" in the titlebar, which isn't very informative. From the Workspace menu, select Rename Workspace… to give it a clearer label (e.g. "Optics Lab", "Robot Cell 3"). The rename only touches the catalog (workspaces.json); your folder on disk keeps its original name.

Switching Workspaces

When you switch workspaces, the server performs a graceful restart:

1. All running scripts and agents are stopped
2. All connector connections are closed
3. The server shuts down
4. The launcher restarts the server with the new workspace path

This process takes a few seconds. The browser will automatically reconnect when the server is back up.

Managing the Workspace List

• Workspaces are automatically added to the list when you create or open them
• Click the X button on any workspace entry to remove it from the list (this does not delete the workspace folder)
• Missing workspaces (deleted folders) are shown as dimmed with a "missing" badge

EULA Acknowledgement & Sandbox Mode

Every Muxit workspace must have an accepted workspace acknowledgement before the server will let any driver perform a hardware write (setting a property, calling an action, or running a script). Until the acknowledgement is accepted the workspace loads in Sandbox mode: reads and polling continue, but every write is refused with error code EULA_NOT_ACCEPTED.

What gets stored

Acceptance produces two files inside the workspace:

my-workspace/
  .muxit/
    EULA-ACCEPTED.md     # Human-readable acknowledgement + signed footer
    eula-history.jsonl   # Append-only audit trail of accept events
    workspace.json       # Stable workspace ID used in the footer

The accepted file is a full copy of the current canonical EULA followed by a footer that identifies who accepted which version, when, for which workspace, and the SHA256 hash of the canonical body text.

Accepting via the UI

When the server reports Sandbox mode the web UI replaces the main view with a blocking modal that shows the EULA text, asks for an identifier (name or email), and requires a checkbox before the Accept button is enabled. On accept the server writes .muxit/EULA-ACCEPTED.md atomically, appends a history entry, and unlocks the workspace.

Accepting from the command line

Headless installs (--cli / --mcp modes, CI pipelines) accept the EULA one of two ways:

# Explicit subcommand — writes the acceptance file and exits
muxit eula accept --user "Jane Doe" --workspace /path/to/workspace
muxit eula status --workspace /path/to/workspace
muxit eula show                # prints the canonical text

# Or set environment variables before launching the server
MUXIT_EULA_ACCEPT=1 MUXIT_EULA_USER="ci-bot" muxit --workspace /path/to/workspace

The env-var flow is logged with action: "accepted_ci" in the history file so CI-initiated acceptances are distinguishable from human ones.

When re-acceptance is required

The server treats EULA versions as semver (1.0.0, 1.1.0, 2.0.0):

• Patch bump (1.0.0 → 1.0.1) — formatting / typo fix only, prior acceptance remains valid.
• Minor / major bump — requires re-acceptance; the modal shows the new version and notes the previous accepted version in the history.

Re-acceptance is also required if the accepted file is edited outside Muxit (hash mismatch → EulaTampered) or if only the footer is present (EulaCorrupt).

Shared workspaces (Git)

The .muxit/ folder commits with the workspace, so a team-shared Git repository carries the accepted EULA with it. The hash check still runs per user so any tampering is detected.

Workspace Catalog

Muxit stores the list of known workspaces in a catalog file outside any workspace: %LOCALAPPDATA%\Muxit\workspaces.json. This file persists across workspace switches and server restarts.

Command-Line Usage

You can also specify a workspace directly when starting the server:

node start.js server --workspace=/path/to/my-workspace

Or with the compiled binary:

muxit --workspace=/path/to/my-workspace

The specified workspace is automatically registered in the catalog.