Qubicl

Give any AI agent a real, private computer on your machine.

Durable files. Terminal access. Web research. A persistent browser and desktop.
Human takeover whenever you want it. No Qubicl account, cloud control plane, or
model lock-in.

Quick start · Why Qubicl · Computers · Clients · Security · Docs

npm install -g qubicl-cli

Qubicl turns local Docker into observable computers for external AI agents.
The agent stays in Codex, Claude, Open WebUI, Cursor, VS Code, or another MCP or
OpenAPI client. Qubicl supplies the machine it works on.

Qubicl 0.6 adds retained tasks, bounded interactive terminals, named client
credentials, normal persistent browsing, scoped internal networking, safer app
previews, and a supported encrypted installation export/import workflow. The
local management dashboard provides private administration,
operation previews, encrypted home backups, and recovery.

your model or agent
        │
        │  MCP / OpenAPI / Open Terminal
        ▼
 local-by-default Qubicl gateway
        │
        ├── terminal + managed processes
        ├── durable, host-visible files
        ├── keyless web search + local extraction
        ├── persistent Chromium + desktop
        ├── packaged, operator-controlled skills
        └── live viewer + human takeover

Why Qubicl

Quick start

Requirements: Linux with Docker Engine or Docker Desktop, macOS with Docker
Desktop, or Windows 11 through WSL 2 and Docker Desktop—plus Node.js 22 or 24
and Docker Compose 2.24+. Native Windows execution and WSL 1 are not supported;
WSL installations must keep Qubicl state and computer homes in the WSL Linux
filesystem under /home. See Platform support before
installing on a best-effort host.

qubicl setup

The setup wizard checks Docker, compares computer presets, previews disk and
resource use, obtains the selected images, and can create the first computer.
Run Qubicl as your normal user, never with sudo.

Create another computer and connect an agent:

qubicl create computer-name --preset computer
qubicl connect computer-name --client codex

connect prints the client configuration; it never edits client files or
prints a bearer token. For local stdio clients, the configuration is token-free.

git clone https://github.com/EldanRing/qubicl.git
cd qubicl
npm ci
npm run images:build
npm install -g --prefix "$HOME/.local" ./packages/cli
export PATH="$HOME/.local/bin:$PATH"
qubicl setup

This recipe builds all six development images for a complete source install.
For ordinary edits, use focused development checks.

Choose a computer

Presets share layers while exposing different capability contracts. Tools that
the selected computer cannot support are absent from discovery.

Every preset includes native keyless web_search, local web_extract, and six
verified Qubicl-native skill baselines with durable, agent-editable working
copies. Operators choose which tools and skills each computer exposes:

qubicl tools computer-name
qubicl skills computer-name

Disabled tools disappear from MCP, OpenAPI, and Open Terminal, and cached calls
fail closed.

Connect any agent

qubicl connect computer-name --client codex
qubicl connect computer-name --client claude-code
qubicl connect computer-name --client cursor
qubicl connect computer-name --client opencode
qubicl connect computer-name --client openclaw
qubicl connect computer-name --client hermes-agent
qubicl connect computer-name --client open-webui

Adapters cover Codex, Claude Code, Claude Desktop, Cursor, VS Code, Open WebUI,
generic stdio and HTTP MCP, and direct OpenAPI. Static profiles can expose a
smaller file, semantic-browser, visual-browser, or desktop catalog.

For Open WebUI, copy the generated configuration into Admin Panel → Settings
→ Integrations → Open Terminal. Qubicl supplies native durable-file browsing
and search, bounded ZIP downloads, retained managed tasks, bounded interactive
terminal sessions, filesystem-backed chat uploads, screenshots, browser tools,
and explicitly published local previews without joining Open WebUI's Docker
network.

See Client setup for exact instructions.

The gateway remains on 127.0.0.1 unless the host operator explicitly enables
a second TLS-only listener with qubicl gateway expose. That opt-in uses the
same gateway container, requires certificate, interface, network, and browser
origin policy, and persists until qubicl gateway revoke. Binding
0.0.0.0 requires the additional --all-interfaces acknowledgement. See
Optional remote access before making it reachable.

Watch and take over

qubicl view computer-name

Observation is passive. Take control fences queued and future agent GUI
input before handing you the keyboard and mouse. Retained tasks and services
continue; lease-scoped session commands and session terminals stop. The
persistent browser and managed desktop applications remain visible so you can
continue the same task.

While the agent is acting, the viewer keeps Qubicl's green pointer at its latest
desktop or managed-browser position and briefly pulses the exact click target.
Semantic browser clicks are mapped from the page element through Chromium and
the live noVNC canvas, so the indicator stays aligned through viewer resizing
and letterboxing. It appears before input dispatch, survives viewer reloads,
and clears when the agent loses its lease or a human takes control. It remains
viewer-only—human input, webpages, and agent screenshots are untouched—and you
can toggle it off from the viewer header. The viewer also identifies Chromium's
profile as durable: cookies, site data, preferences, and browser state remain in
the computer's /home across ordinary restarts and upgrades.

Agent-facing browser_reset is labeled Reset tabs and keeps that profile.
To deliberately remove cookies, local storage, history, preferences, and
sessions while preserving Downloads and every file outside the managed profile,
the host operator uses an explicit preview and confirmation:

qubicl browser profile wipe computer-name

Viewer tickets and cookies terminate at the shared gateway. Current viewer
images additionally require a gateway-injected internal credential for both
noVNC files and WebSocket traffic; the computer exposes no raw TCP VNC listener,
and that internal credential is not passed to workload child processes.

If a controlling viewer disappears, Qubicl shows the reconnect countdown and
releases control after the configured grace period (10 seconds by default).
Change it from 5 to 300 seconds with qubicl config set --viewer-reconnect-grace SECONDS. The operator can always recover explicitly:

qubicl control release computer-name

Built for daily use

• Publish an agent-started web app through an authenticated local preview and,
  when explicitly configured, a separately isolated remote preview origin.
• Back up, verify, encrypt, restore, clone, and checkpoint durable homes.
• Export, inspect, and import a stopped full installation as a mandatory
  passphrase-encrypted bundle without overwriting the source installation.
• Run reconnectable retained tasks, bounded interactive terminals, declared
  restartable services, and explicit tasks stop-all cleanup.
• Create named client credentials with observe/files/tasks/interactive/publish
  scopes, one-time display, last-use attribution, and selective revocation.
• Inspect home, cache, download, task, audit, and backup storage with honest
  warning thresholds instead of pretending Docker provides portable quotas.
• Preview and deliberately wipe one durable Chromium profile without deleting Downloads.
• Apply offline, web-only, developer, or custom egress policies.
• Broker narrowly scoped credentials without placing the secret in the workload.
• Import bounded devcontainer definitions and run Git workflows inside the computer.
• Enable loopback-only SSH for editors and ordinary ssh/scp.
• Inspect private operation metadata and diagnose topology with doctor; review
  audit exports and the current limitations before sharing them.
• Preview pending curated image updates with status, or explicitly compare the
  installed CLI/catalog with npm using qubicl update check.
• Upgrade one computer or use confirmed upgrade --all while preserving IDs,
  tokens, policies, resources, homes, and prior running/stopped/absent state.
• Preview exact cleanup candidates; ambiguous daemon-global images and Docker
  volumes remain manual because one installation cannot prove exclusive ownership.

Use qubicl help or qubicl <command> --help to explore the full CLI.

Automatic update notices are local, default off, and compare only against the catalog
bundled with the installed CLI. Enable or disable them explicitly with
qubicl config set --update-notifications on|off; they perform no network
check, telemetry, image pull, or automatic mutation. qubicl update check
performs one explicit bounded registry lookup unless --offline is supplied;
it never downloads or applies an update.

Security boundary

Qubicl keeps every computer inside one explicit Docker resource and filesystem
boundary. Computers run without privileged mode, a Docker socket, host
namespaces, arbitrary mounts, or passwordless elevation. The gateway listens
only on 127.0.0.1 by default; an operator can deliberately add a distinct
TLS-only listener for gateway traffic. Separately enabled SSH publishes only on
host loopback. Chromium retains its Linux namespace and renderer
seccomp-BPF sandboxes; model-facing files are confined to the durable home.
Controller and workload processes share the computer container, so human
takeover is a cooperative managed-process fence rather than a hostile-code boundary.

Qubicl is a Docker-based computer for trusted or operator-supervised workloads,
not a VM boundary against hostile custom images, kernel exploits, Docker
compromise, or another user who controls the host account. The default
developer network profile permits outbound access. Read the complete
security model before relying on the boundary.

Release status

The 0.6 design is
implemented in this source tree. A public 0.6 release still requires a frozen
reviewed commit and its separately approved candidate, security, client,
platform, accessibility, mobile, and publication evidence.

Qubicl 0.6.x is a pre-1.0 series intended for real use, but its
interfaces and state format may still evolve before 1.0. The supported-host
policy covers Linux x64, Apple Silicon macOS with Docker Desktop, and Windows 11
x64 through Ubuntu 24.04 on WSL 2 with Docker Desktop. Their directly tested
classifications record historical v0.1.0 evidence baselines; they do not mean
every current candidate repeats the full macOS and Windows matrices. The 0.6
initial release uses Linux x64 for general platform acceptance and separately requires
dashboard-specific native Linux x64, Apple Silicon macOS, and physical iPhone
Safari evidence. Linux ARM64, Intel macOS, Windows on ARM, and other WSL 2
distributions remain best-effort. Native Windows and WSL 1 are unsupported;
Qubicl computers remain Linux containers on every host. The versioned
Platform support matrix is authoritative. Back up important
computer homes before upgrades.

Documentation

Start with the workflow you want to complete:

Licensing: source code and documentation are Apache-2.0; the designated
Qubicl logo and official brand artwork are CC BY 4.0. See
BRANDING.md for permitted brand use and attribution.

Contributions are welcome—start with CONTRIBUTING.md, and
report vulnerabilities through the repository's private security-reporting
form described in SECURITY.md.