Private desktops

A private desktop gives each bot a containerized Linux desktop on the same machine as Brainwrite. It is useful for browser work, downloads, and repeatable automation that should not run directly on your host desktop.

Requirements

• Docker Desktop, Docker Engine, or a supported Podman setup
• Enough local memory and disk for the desktop image
• A healthy container runtime available to the Brainwrite process

Run two bot desktops

1. Open Settings → Private desktops, prepare the managed desktop image, and choose Per bot.
2. Set Maximum per-bot desktops to 2.
3. Give two bots Private desktop as their computer and create each desktop from that bot's Computer panel.
4. Choose Open two desktops from either bot to watch both in one workspace.

Both desktops may keep running, but only one pane can hold interactive control at a time. Switching control releases the previous pane first; opening the two-up workspace never creates or starts a VM.

The equivalent source configuration is:

{
  "localVm": {
    "mode": "per-bot",
    "maxInstances": 2
  }
}

Private desktops always run on the Mac that runs Brainwrite. To give a bot a desktop on another machine, use your own VPS: an x86_64 Linux server with Docker.

Memory and CPU

Each desktop gets 4 GiB of memory, with no swap beyond it, and 2 CPUs. To change that, set memoryGb and cpus in config.json. Both are whole numbers: memoryGb from 2 to 128, and cpus from 1 to 64 but no more than your container runtime has (on Docker Desktop, its VM's CPU setting). A value outside those rules makes Brainwrite ignore the whole file, so check the server log after editing.

{
  "localVm": {
    "memoryGb": 8,
    "cpus": 4
  }
}

A new desktop is created with these limits. On Docker and Podman, Brainwrite also applies them to a stopped desktop when it next starts; if the runtime refuses the change, the desktop starts with its old limits. On Apple container, remove and recreate the desktop to apply them. Every running desktop counts against the machine's memory, so leave room for Brainwrite itself.

Installing packages

A bot can install system packages in its desktop with sudo apt-get install. Packages installed this way live in the desktop's own filesystem, not the durable workspace, so recreating the desktop (or an update that recreates it) removes them. User-level installs such as pip install --user or anything under ~/.local are stored in the workspace and survive recreation.

On Linux with Docker Engine, or with Podman when Brainwrite runs as root, a desktop's root account is the host's root account. Those desktops therefore run with no-new-privileges: sudo is off and system packages cannot be installed. User-level installs still work. Use rootless Podman, with Brainwrite running as a regular user, when a bot needs sudo in its desktop.

Desktops made before this change keep their old capabilities until they are recreated. Where the desktop's root is the host's root (as above), Brainwrite recreates them once automatically. Elsewhere, remove and recreate a desktop from App Settings to let it install packages. Recreating keeps the durable workspace and browser sign-ins, but files elsewhere in the desktop, such as ~/Downloads, are lost.

Linux accounts

On Linux with Docker Engine, the desktop's cua account takes the user ID and group ID of the account running Brainwrite, so files the bot writes in its workspace belong to you on the host. The first start of a new desktop takes longer while it does this. If Brainwrite runs as root, the workspace is handed to user ID 1000 instead, which is the desktop's own cua account. Rootless Podman maps the IDs itself. Rootless Docker is not covered: its user IDs inside containers do not match the host's.

Persistence

The bot's workspace and browser profile live in a durable mounted directory. Recreating the desktop can repair stale runtime state without deleting the durable workspace.

Ownership and reuse

A private desktop's ownership uses a renewable lease. Brainwrite validates the resolved image and container safety contract before reuse instead of trusting only a mutable image tag.