Getting started

This page takes you from nothing to a running canvas, a first file and a first agent call.

What you need

• Node 22.18 or newer. Check with node --version.
• A Chromium-based browser: Chromium, Chrome, Brave or Edge. Bogen finds it on your PATH, or in the usual places on a Mac. The server uses it, headless, for screenshots, exports and the checks your agent runs. Without one, the canvas and the MCP tools still work, but nothing can be rendered. Set BOGEN_BROWSER to its path if Bogen does not find it.

Optional:

• ffmpeg, for video export when the browser cannot encode, and for AVIF with transparency.
• Claude Code or Codex, for the prompt bar and for @claude and @codex in comments.
• Tailscale, to sync with your other devices.

Bogen is developed and used on Arch Linux with Omarchy. A macOS install exists but has not run on a real Mac yet; see the FAQ.

1. Install

From npm

npm i -g bogen-design

This puts bogen on your PATH. The package is about to be published; until it is on npm, install from a checkout.

From a checkout

In a checkout of the repository:

npm install
npm run build

The command is then node packages/server/dist/cli.js. The examples in these guides write bogen for it; make an alias, or on Omarchy let integrations/omarchy/install.sh put a bogen wrapper in ~/.local/bin (see Omarchy).

To make the npm package yourself, run npm run release:npm. It prints the path of a bogen-design-<version>.tgz, which npm i -g installs.

2. Open the canvas

bogen open

This starts the server in the background if it is not running, and opens http://127.0.0.1:29990 in your browser. The server only listens on this machine.

Other ways to run it:

--port (or BOGEN_PORT) picks another port. When a user service for Bogen is installed, as on Omarchy, bogen start and bogen open start that service instead of a second server.

Your files live in ~/.local/share/bogen, or $XDG_DATA_HOME/bogen. Set BOGEN_HOME to use another folder. The background server writes its log to server.log there.

3. Make a first file

On the home screen, choose New file (or press N). The file opens with one empty page.

• Press F and drag to draw a frame. A frame is a <div>; frames hold other layers.
• Press T and click to add text.
• Select a frame and press Shift+A to give it flex layout, so that what is inside lines up in a row or column.
• Press Ctrl+/ for every keyboard shortcut, and Ctrl+P for the command palette.

The right panel has the inspector (Design), the code of the selection (Code), Export, History, comments, motion and the Agents tab. The left panel has layers, tokens, assets and the brand.

Canvas goes through all of it.

4. Connect your agent

bogen install claude-code     # or codex, cursor, vscode, opencode, gemini, zed, or --all

Then ask your agent, in its own window: "Design a pricing page in Bogen." Keep the canvas open to watch it draw. Agents explains what it can do, and how to undo what it did.

If you have the claude or codex CLI installed, you can also stay in the canvas: press Ctrl+K, type what you want, and Bogen runs your CLI with only Bogen's tools.

5. Check the setup

bogen doctor

This checks Node, the data folder, the service, the server and its version, the editor, the browser (it renders a test image), Tailscale, the firewall, paired devices, the claude and codex CLIs and each MCP client it finds. Every problem comes with the command that fixes it. It changes nothing. See Troubleshooting.

Updating and removing

• npm: npm i -g bogen-design again updates it, and npm rm -g bogen-design removes it.
• Checkout: pull, then npm install && npm run build, and restart the server with bogen stop && bogen start (or systemctl --user restart bogen with the user service). bogen status says when the running server is another build than the command.

Removing Bogen leaves your designs in the data folder. To take Bogen out of an MCP client, run bogen uninstall <client>.