qubicl

<div align="center"> <picture> <source media="(prefers-color-scheme: dark)" srcset="assets/brand/qubicl-mark-dark.svg"> <img alt="Qubicl" src="assets/brand/qubicl-mark.svg" width="180"> </picture> <h1>Qubicl</h1> ### 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. [](https://www.npmjs.com/package/qubicl-cli) [](LICENSE) [](package.json) [](https://www.docker.com/) [Quick start](#quick-start) · [Why Qubicl](#why-qubicl) · [Computers](#choose-a-computer) · [Clients](#connect-any-agent) · [Security](#security-boundary) · [Docs](#documentation) </div> --- ```sh 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](docs/dashboard.md) provides private administration, operation previews, encrypted home backups, and recovery. ```text 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 | Capability | What it gives you | | --- | --- | | **Bring your own model** | One computer works with any compatible client. Switch models without rebuilding the workspace. | | **See the work** | Watch the live desktop, take control, finish a task yourself, and hand the same session back. | | **Keep the files** | The computer's `/home` is visible on the host and survives restarts, upgrades, and runtime recreation. | | **Do more than code** | Terminal, Git, web research, browser automation, desktop apps, office workflows, previews, backups, and SSH. | | **Control every computer** | Choose its resources, network policy, exposed tools, active skills, credentials, and lifecycle. | | **Stay local** | No Qubicl account, telemetry backend, database, hosted daemon, or Docker socket inside the computer. | ## 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](docs/platforms.md) before installing on a best-effort host. ```sh 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: ```sh 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. <details> <summary><strong>Build from source</strong></summary> ```sh 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](docs/development.md#choose-checks-for-the-change). </details> ## Choose a computer Presets share layers while exposing different capability contracts. Tools that the selected computer cannot support are absent from discovery. | Preset | Includes | Viewer | Suggested limit | | --- | --- | :---: | ---: | | `file-system` | Shell, processes, Git, durable files, web research | — | 1 CPU / 512m | | `browser` | Everything above plus persistent Chromium, OCR, PDF inspection | ✓ | 2 CPU / 2g | | `computer` | Browser plus a lightweight XFCE desktop, editors, document tools, SSH | ✓ | 2 CPU / 3g | | `workstation` | Development and office environment with LibreOffice Writer, Calc, and Impress | ✓ | 2 CPU / 4g | 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: ```sh 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 ```sh 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](docs/clients.md) 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](docs/remote-access.md) before making it reachable. ## Watch and take over ```sh 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: ```sh 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: ```sh 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](docs/security-model.md#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](docs/security-model.md) before relying on the boundary. ## Release status The [0.6 design](docs/decisions/0002-v0.6-capabilities-and-constraints.md) 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](docs/platforms.md) matrix is authoritative. Back up important computer homes before upgrades. ## Documentation Start with the workflow you want to complete: | Goal | Guide | | --- | --- | | Create a computer and connect an agent | [Quick start](#quick-start) · [Client setup](docs/clients.md) | | Browse, work with documents, and hand off control | [Browser and document handoff](docs/daily-driver.md#browser-and-document-handoff) | | Develop an app and open its preview | [Ports](docs/daily-driver.md#ports) · [SSH and editors](docs/daily-driver.md#ssh-and-editors) · [Devcontainers and Git](docs/daily-driver.md#devcontainers-and-git) | | Back up or recover work | [Backup, checkpoint, clone](docs/daily-driver.md#backup-checkpoint-clone) · [Persistence](docs/persistence.md) | | Manage computers or access remotely | [Dashboard](docs/dashboard.md) · [Remote access](docs/remote-access.md) | | Understand an unavailable action | [Find the blocker](docs/troubleshooting.md#find-what-is-blocking-the-action) · [Constraints and reasons](docs/constraints.md) | | Topic | Guide | | --- | --- | | Architecture and boundaries | [Architecture](docs/architecture.md) · [Security model](docs/security-model.md) · [Optional remote access](docs/remote-access.md) | | Persistence and recovery | [Persistence](docs/persistence.md) · [Troubleshooting](docs/troubleshooting.md) | | Host platforms | [Platform support](docs/platforms.md) · [Windows Subsystem for Linux](docs/wsl.md) | | Clients and workflows | [Client setup](docs/clients.md) · [Daily-driver workflows](docs/daily-driver.md) | | Skills and research | [Skills](docs/skills.md) · [Web research](docs/web-research.md) | | Custom environments | [Custom images](docs/custom-images.md) | | Roadmap | [Public product direction](ROADMAP.md) | | Development and releases | [Development](docs/development.md) · [Release process](RELEASING.md) · [Verification](VERIFYING.md) · [Vulnerability evidence](security/README.md) | **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](BRANDING.md) for permitted brand use and attribution. Contributions are welcome—start with [CONTRIBUTING.md](CONTRIBUTING.md), and report vulnerabilities through the repository's private security-reporting form described in [SECURITY.md](SECURITY.md).