A.1 Install Commands

Three primary installation routes are available. Select the workflow that fits your target environment: desktop execution, source development, or server deployment. Each route provisions release 0.21.1. Alternatively, a one-line CLI installer combines binary retrieval and agent wiring into a single command for headless environments. See Chapter 02 for the complete first-run walkthrough and build diagnostics.

# From-source install
$ git clone https://github.com/nexu-io/open-design.git
$ cd open-design
$ corepack enable
$ pnpm install
$ pnpm tools-dev run web
# Daemon and Next.js frontend start in foreground
# Open http://localhost:7456 in your browser

# Docker Compose install
$ cd deploy
$ cp .env.example .env
$ openssl rand -hex 32
# Paste output into .env at OD_API_TOKEN=
$ docker compose up -d
# Open http://localhost:7456

# One-line installer — example: wire Claude Code
$ curl -fsSL https://open-design.ai/install.sh | sh -s claude-code

A.2 The od Command Surface

While coding agents drive generation through the Model Context Protocol (MCP), the od binary manages the underlying system lifecycle, handling environment configuration, status diagnostics, and agent connections. Commands such as od mcp install register client profiles, whereas utility checks like od status and od plugin list surface real-time background health. The primary subcommands are indexed below; consult /docs/cli-reference.md within the codebase for comprehensive flag descriptions.

Query the HTTP health endpoint directly to verify background service availability without invoking the od CLI:

# Daemon health check (from-source or Docker, port 7456)
$ curl -s http://localhost:7456/health
# Expected output:
{"status":"ok","version":"0.21.1"}

The optional flags work consistently across all agents. Use them to manage the full lifecycle:

# Inspect what will be written before committing
$ od mcp install cursor --print

# Output as JSON for scripting or CI
$ od mcp install cursor --json

# Remove the MCP config for an agent
$ od mcp install cursor --uninstall

When background services are active, od status reports connected agents alongside runtime uptime, while od plugin list details installed extensions and operational status:

$ od status
# daemon: running (uptime 2h14m)
# agents: claude-code (connected), cursor (connected)
# port: 7456

$ od plugin list
# figma-migration    active
# code-refresh       active
# linear-brand       active
# (261 official plugin packages available; ~280 total catalog entries across marketplace; run od plugin install  to add)

A.3 MCP Install per CLI

Starting in release 0.19.1, the utility also supports od mcp install claude-desktop to generate configuration blocks for Claude Desktop on macOS and Windows --- matching the connection profiles displayed under Settings → OpenDesign MCP. The equivalent environment plumbing (OD_DATA_DIR, OD_SIDECAR_IPC_PATH, OD_MCP_BOOTSTRAP_COMMAND) is identical across targets. For long-lived stdio sessions, OD_MCP_STDIO_IDLE_EXIT_MS (0.21.0) extends the idle lifetime up to 24 hours, or disables idle exit entirely with 0.

The od mcp install command supports 26+ coding-agent CLIs as of September 2026 (Chapter 11 tracks the growth from the 21 this appendix’s first edition routed across). The 17 slugs verified for the reference table below are retained for stability; consult the agent registry at github.com/nexu-io/open-design for the live roster. The command writes the required server parameters directly to client settings files. Re-run after upgrading to refresh configurations. See Chapter 10 for details on multi-agent orchestration. Select your CLI slug below to install.

The full command block for all named slugs:

# od mcp install — CLI slugs
$ od mcp install claude-code     # Claude Code
$ od mcp install codex           # OpenAI Codex CLI
$ od mcp install cursor          # Cursor
$ od mcp install copilot         # GitHub Copilot CLI
$ od mcp install gemini          # Google Gemini CLI (announced sunset ~2026-06-18 — verify current status)
$ od mcp install opencode        # OpenCode (MIT)
$ od mcp install hermes          # Hermes
$ od mcp install kimi            # Kimi CLI
$ od mcp install openclaw        # OpenClaw
$ od mcp install antigravity     # Google Antigravity
$ od mcp install vibe            # Mistral Vibe
$ od mcp install pi              # Pi
$ od mcp install cline           # Cline
$ od mcp install trae            # Trae
$ od mcp install qwen            # Qwen
$ od mcp install deepseek        # DeepSeek
$ od mcp install ollama          # BYOK / local Ollama

A.4 File Layout and Config

The application stores state in a .od/ directory within the user's home directory. This layout separates persistent configuration, project databases, and execution logs. app.sqlite and artifacts/ contain project state and should be included in routine backups. The sessions/ folder holds temporary UI data. Daemon configuration resides in .od/config.json, whereas individual projects maintain local overrides. Set OD_DATA_DIR to relocate the data root in Docker or daemon environments.

.od/
├── config.json              # Daemon config: design system, skills, mode
├── app.sqlite               # SQLite project database (back this up)
├── artifacts/               # Saved renders and one-off exports
│   └── 2026-06-11T12-34-56-landing/
│       ├── artifact.json    # Metadata: skill, prompt, parent artifact
│       ├── index.html       # Primary output
│       └── assets/          # Generated images and fonts
├── history.jsonl            # Append-only action log
├── sessions/                # Ephemeral UI state (safe to delete)
│   └── <session-id>.json
└── media-config.json        # Auto-created; auto-gitignored

Prioritize two targets during backups. app.sqlite retains project metadata alongside generation history, while artifacts/ stores rendered assets. In contrast, sessions/ is transient --- clearing it resolves UI glitches without risking project work.

BYOK Proxy Routes

Open Design incorporates a built-in BYOK (Bring Your Own Key) proxy that routes inference to configured providers across the following local paths on port 7456:

Docker Environment Config

For Docker Compose deployments, the deploy/.env.example file documents the required environment variables. Copy it to .env before running docker compose up.

# deploy/.env.example (relevant fields, v0.21.1)
OD_API_TOKEN=           # Required: generate with: openssl rand -hex 32
# Optional: override default port
# OD_PORT=7456
# Optional: relocate data directory
# OD_DATA_DIR=/data/od

To configure BYOK providers in a Docker deployment, set the relevant provider env vars in the same .env file:

# Add to deploy/.env for BYOK provider access
ANTHROPIC_API_KEY=sk-ant-...
OPENAI_API_KEY=sk-...
GOOGLE_API_KEY=...
# For local Ollama (fully local inference):
OPENAI_BASE_URL=http://localhost:11434/v1

config.json Snippet

Configuration in .od/config.json sets the active design system, default skill, and process execution mode. A minimal configuration enabling standalone service mode:

{
  "designSystem": "acme",
  "defaultSkill": "web-prototype",
  "mode": "daemon"
}

Version Pin Reference