Install

Building from source on Windows: see BUILD_WINDOWS.md

macOS (Homebrew):

brew tap zseven-w/openpencil
brew install --cask openpencil

Windows (Scoop):

scoop bucket add openpencil https://github.com/zseven-w/scoop-openpencil
scoop install openpencil

Linux / Windows direct download: GitHub Releases — .exe (Windows), .AppImage / .deb (Linux)

The Windows .exe installer, both Scoop packages, and the install-op.ps1 CLI installer check and, when needed, service the pinned, Microsoft-signed Visual C++ v14 runtime during every install or upgrade. The portable Windows .zip archives and Windows VSIX packages do not run an elevated system installer; install Microsoft's latest supported Visual C++ Redistributable before using those artifacts directly.

Antivirus flagged the Windows installer? That's a known heuristic false positive on new, low-prevalence releases — see how to verify your download.

Nix (Linux x86_64):

nix develop
nix run .                         # launch the desktop app
nix build .#openpencil            # native web host + CanvasKit web bundle
nix build .#op-cli                # the `op` CLI
nix build .#prebuilt              # use the matching upstream desktop archive
nix build .#prebuilt-cli          # use the matching upstream CLI archive
nix build .#web-server            # native GL-free web server + web bundle
nix build .#runtime-prebuilt      # prebuilt desktop + `op` CLI runtime
nix build .#web-sdk-packages      # npm tarballs for the web SDKs
nix build .#appimage              # portable desktop AppImage

The flake uses the pinned Rust toolchain from rust-toolchain.toml and is currently published for x86_64-linux. A Debian package is not produced by the flake yet; use the upstream release artifacts when a .deb is required. The prebuilt outputs use the release version and hashes pinned in nix/release-manifest.json, independently of the workspace source version. After a release is published, the release workflow opens a PR to refresh that manifest. Until it is merged, the prebuilt outputs continue to use the prior published release; the source-built outputs always build the checked-out source.

CLI (op):

brew install zseven-w/openpencil/op

Or use the install script (macOS / Linux):

curl -fsSL https://raw.githubusercontent.com/ZSeven-W/openpencil/main/scripts/install-op.sh | bash

To allow the newest pre-release:

curl -fsSL https://raw.githubusercontent.com/ZSeven-W/openpencil/main/scripts/install-op.sh | OP_PRERELEASE=1 bash

Windows PowerShell:

irm https://raw.githubusercontent.com/ZSeven-W/openpencil/main/scripts/install-op.ps1 | iex

To allow the newest pre-release:

$env:OP_PRERELEASE = "1"; irm https://raw.githubusercontent.com/ZSeven-W/openpencil/main/scripts/install-op.ps1 | iex

Web dev server (builds the CanvasKit wasm bundle, then runs the headless web host)

bash scripts/start-web-rust.sh

Browser-entered built-in provider, image-generation, and Openverse credentials
are kept in same-origin `localStorage`
(`openpencil-rust-web-credentials`) by default,
separate from ordinary web preferences. A credential needed by an AI request is
sent with that request, but the daemon does not write the browser snapshot to
`settings.json`.

Private deployments can opt into server persistence with
`OPENPENCIL_PERSIST_WEB_CREDENTIALS_SERVER=true`. This setting is
deployment-wide; each accepted browser snapshot replaces the shared
browser-owned copy. Enable it only for a trusted, access-controlled deployment
with one active administrator profile, behind HTTPS. Turning the setting off
removes previously persisted browser-owned credentials at the next startup
while preserving operator-owned configuration. As with all `localStorage`,
same-origin scripts can read these values, so the web origin must be protected
from untrusted scripts and XSS. Before downgrading to a release that predates
this switch, turn it off and start the current release once to scrub the
browser-owned copy.

The web host supports built-in API-key agents only. CLI and ACP agents remain
native-only: they are not shown in the web model picker, stored in browser
credential snapshots, synchronized to the server, or exposed through web
connect routes. Browser requests to credential and AI endpoints allow
loopback/localhost origins by default. A public reverse proxy must separately set
`OPENPENCIL_WEB_ALLOWED_ORIGINS` to a comma-separated list of exact origins,
for example `https://demo.openpencil.dev`.

Server persistence does not permit browser-controlled requests to loopback,
private, link-local, metadata, or reserved provider endpoints. A trusted private
deployment that intentionally uses an internal provider must separately set
`OPENPENCIL_WEB_AI_ENDPOINT_ALLOWLIST` to a comma-separated list of exact URL
origins, for example `http://127.0.0.1:11434,https://llm.internal.example`.

Or run as a desktop app:

Prerequisites: Rust (stable) to build the product. Bun >= 1.0 and Node.js >= 18 are only needed for the web SDK under packages/.

Docker

Tagged Rust releases publish a single web-host image. The retired TypeScript images with bundled AI CLIs are no longer published.

The web UI exposes built-in agent profiles only; Claude/Codex/OpenCode/Copilot CLI tooling is not bundled into Docker images.

Run:

VERSION="$(scripts/workspace-version.sh)"
docker run -d -p 3100:3100 "ghcr.io/zseven-w/openpencil-web:v${VERSION}"

Then open http://localhost:3100/.

Build locally:

docker build -f Dockerfile.web-rust -t openpencil-web-rust .
docker run -p 3100:3100 openpencil-web-rust

Install Rust toolchain (rust-toolchain.toml auto-pins 1.94)

rustup toolchain install 1.94 rustup target add wasm32-unknown-unknown

build / test / lint

cargo check --workspace cargo test --workspace cargo clippy --workspace --all-targets -- -D warnings cargo check --target wasm32-unknown-unknown -p op-collab --no-default-features cargo check --target wasm32-unknown-unknown -p op-host-web --no-default-features --features web # kickoff §1.2 wasm32 invariant cargo deny check && cargo deny --target wasm32-unknown-unknown check bans # cargo-deny (native + wasm32 bans; CI uses cargo-deny-action@v2) ```

Entry crates (crates/ — build targets):

Shared library crates: op-editor-core (canonical .op state), op-editor-ui (platform-free widgets + RenderBackend), op-editor-host-core (transport-free host state machines), op-collab (open, transport-free collaboration protocol/hash/exact apply), op-collab-transport (native Noise/TCP, bounded admission, and optional LAN discovery), op-mcp, op-ai, op-ai-skills, op-codegen, op-orchestrator, op-figma, op-git, op-opmerge, op-pen-loader, op-design-lint, op-config-store, op-process-io, op-acp, op-i18n, op-rpc-transport — plus op-collab-smoke (authenticated two-process collaboration/recovery matrix) and op-smoke (headless design-turn test runner). The mobile players live in packaging/ (ios + android shells over op-engine-ffi / op-engine-jni). The browser bundle renders through the official CanvasKit skia WASM (loaded separately), so the retired skia-safe-op wasm fork + wasm-libc-shim no longer exist.

Submodule: vendor/agent → github.com/ZSeven-W/agent-rs (cross-product Rust agent runtime).

🎨 Style Guides

Built-in style guide library with tag-based fuzzy matching. Apply visual styles (glassmorphism, brutalist, retro, etc.) to AI-generated designs. MCP tools for external agent access.

</td> <td width="50%">

Quick Start (Development)

```bash

⌨️ CLI — `op`

Control the design tool from your terminal. op design, op insert — batch design DSL, node manipulation. Pipe in from files or stdin. Works with desktop app or web server.

</td> </tr> <tr> <td width="50%">

🧩 Embeddable SDK

op-web-sdk (vanilla) + op-web-sdk-react / op-web-sdk-vue adapters — embed a read-only .op viewer in your own app, powered by the same wasm renderer the editor ships.

</td> </tr> <tr> <td width="50%">

CLI — `op`

Install via Homebrew or the install script, then control the design tool from your terminal:

brew install zseven-w/openpencil/op

curl -fsSL https://raw.githubusercontent.com/ZSeven-W/openpencil/main/scripts/install-op.sh | bash

curl -fsSL https://raw.githubusercontent.com/ZSeven-W/openpencil/main/scripts/install-op.sh | OP_PRERELEASE=1 bash

irm https://raw.githubusercontent.com/ZSeven-W/openpencil/main/scripts/install-op.ps1 | iex

$env:OP_PRERELEASE = "1"; irm https://raw.githubusercontent.com/ZSeven-W/openpencil/main/scripts/install-op.ps1 | iex

op start                     # Launch desktop app
op start --headless --file design.op # Launch headless file-backed server
op design @landing.txt       # Batch design from file
op design @ui.js             # Sandboxed JavaScript with loops
op insert '{"type":"rectangle"}' # Insert a node
op import:figma design.fig   # Import Figma file
cat design.dsl | op design - # Pipe from stdin

Supports three input methods: inline string, @filepath (read from file), or - (read from stdin). Works with the desktop app, web server, or headless file-backed server. See the CLI command reference for all commands.

LLM Skill — install the OpenPencil Skill plugin to teach AI agents how to design with op. Run op install for detected agents, or target one explicitly with op install --target codex.

Web SDK / JS tooling (run from packages/)

cd packages && bun run lint # Lint the web SDK (oxlint); also: bun run format cd packages && bun run generate-iconify-catalog # Regenerate the Rust icon catalog assets

Cloning (with submodules)

```bash git clone --recurse-submodules https://github.com/ZSeven-W/openpencil.git

Or already cloned — sync first so stale submodule URLs pick up .gitmodules changes:

git submodule sync --recursive && git submodule update --init --recursive ```

Three submodules live under vendor/, all public and fetched over HTTPS (no SSH key needed): jian (GPU-Skia UI framework — widgets/render/events), casement (winit fork), and agent (agent-rs — cross-product Rust agent runtime, shared by OP + Zode). vendor/anthropic-agent-sdk is tracked in-tree, not a submodule.