Self Host · Cloud · Docs

   

Make it — design has never been this simple

zuoge is an open-source AI design workspace with an editable infinite vector canvas and a Design Agent. The product slogan is Make it — design has never been this simple. Use natural language to create and revise shapes, text, layouts, and styles, continue refining directly on the canvas, and self-host with Docker Compose.

Built-in Design Agent (LangGraph): natural language creates layers, draws shapes, restyles, and typesets. Ships with Skills out of the box; you can also add custom Skills / AgentProfile (YAML) / prompt packs for posters, dashboards, landing pages, and more — then keep editing at vector precision.

You can self-host in a few minutes with Docker Compose (default MySQL + Redis + web + API + Yjs collab). For local dev, leave DATABASE_URL empty for SQLite, or switch to PostgreSQL — see docs/postgres-switch.md.

Open source takes time. If zuoge helps you, please hit ⭐ Star in the top-right of the GitHub repo.

→ https://github.com/recombyn/zuoge

Custom infinite canvas: the scene graph is SceneDocument, with a 5%–10000% zoom range. Committed nodes normally paint as per-node SVG; the grid and eligible lightweight far-out nodes use Canvas2D LOD proxies. Hit testing combines the spatial index, AABB checks, and Path2D geometry to keep large documents responsive.

Details: docs/canvas-architecture.md · Scene JSON: docs/scene-json-spec.md.

You can:

• Build frames, shapes, text, images, video, Lottie; draw with pen / pencil (filled-ribbon vector brushes); select & transform
• Run boolean ops (union / subtract / intersect, …)
• Set stroke align: center / inside / outside
• Outline a stroke into an editable filled path, then edit the path
• Fill, corner radius, blend modes, opacity, stacking; export & share
• Turn on Yjs live collab (cursors, selection, undo; apps/collab)

A streaming chat agent: you describe the job; it plans, attaches Skills, calls tools, and writes back onto the same canvas — landings, posters, revisions, and more.

The execution kernel is fixed: LangGraph template canvas_ops_v1. Category and behavior come from config (AgentProfile YAML / prompt packs / Skills / Tools) — you don’t have to touch the kernel.

Typical turn: intent → (chat settle / lean paint / design decide) → paint emits tool_ops → observe → optional Review sub-agent → settle. Full graph: docs/agent-profile.md.

One folder per skill: skills/foundation/<key>/ or skills/domains/<key>/ (_meta.json + SKILL.md; optional schema.json, assets/, …).

• _meta.json — when to use, triggers, preferred_tools, mutex — Decide picks skills from this
• SKILL.md — how to craft that deliverable (landing, poster, resume, dashboard, motion, …)

The repo already ships many (landing, poster, resume, dashboard, motion, ecommerce…). You can keep adding folders — no fixed cap.

Atomic canvas ops live in apps/api/seeds/canvas_actions_seed.json. Paint emits structured tool_ops; the host validates and applies them. Skills may prefer tools; they cannot invent ops outside the registry.

Swap / add an Agent

1. Copy profiles/design.canvas.yaml → profiles/my.agent.yaml; change id: / identity / capabilities
2. Point bindings.yaml at the new id, or set AGENT_PROFILE_ID=my.agent
3. Restart the API (Profiles load from disk, not DB rows)

Add a Skill

1. Create design_skills/my_scene/_meta.json + SKILL.md
2. Fill triggers + preferred_tools
3. Restart / re-ensure seeds — Decide can attach it

Extra skill packs can also live under plugins/skills/ (Compose-mounted). See docs/skill-extensions.md.

Env knobs (Review on/off, timeouts): docs/agent-profile.md § Env knobs. Seeds overview: apps/api/seeds/README.md. Models: docs/self-hosting.md.

Two extension surfaces — don’t mix them up:

Skill pack

1. Drop _meta.json + SKILL.md under plugins/skills/<key>/ (optional handler.py, schema.json, assets/).
2. Compose already mounts ./plugins/skills → API; or set DESIGN_SKILLS_PLUGIN_DIRS.
3. Restart API / wait for hot reload — chat with a trigger (sample: "create a Mid-Autumn festival poster in red").

Optional: DESIGN_SKILL_OPS_RUNNER=true lets handler.py emit tool_ops before LLM paint. Details: docs/skill-extensions.md.

Canvas plugin

1. Add manifest.json + index.ts under plugins/canvas/<id>/.
2. Register it in ensureCanvasPlugins() (apps/web/src/plugins/canvas/host.ts).
3. Rebuild / refresh the web app.

Details: docs/canvas-plugins.md.

Packaged install (.recombyn-plugin)

node scripts/pack-recombyn-plugin.mjs plugins/skills/festival_poster
# → dist/plugins/<id>-<version>.recombyn-plugin
# Upload via Skills library, or POST /api/v1/design/plugins/install
# Disk install needs DESIGN_PLUGIN_DISK_INSTALL=true

→ docs/plugin-packs.md · plugins/skills/README.md · plugins/canvas/README.md

git clone https://github.com/recombyn/zuoge.git
cd recombyn
cp apps/api/.env.example apps/api/.env   # add LLM_API_KEY / provider keys
docker compose up -d --build

More options (env, LLM keys, production hardening): docs/self-hosting.md · Postgres: docs/postgres-switch.md

Use docker-compose.yml as the base stack, then layer overrides only when needed:

# 1) Base self-host stack (web + api + collab + mysql + redis + worker)
docker compose -f docker-compose.yml up -d --build

# 2) Base + ClamAV upload scanning
docker compose --profile av \
  -f docker-compose.yml \
  -f docker-compose.av.yml \
  up -d --build

# 3) Base + optional Design Intelligence HTTP provider
docker compose --profile intelligence \
  -f docker-compose.yml \
  -f docker-compose.intelligence.yml \
  up -d --build

# 4) Base stack from pre-built GHCR images (skip local image builds)
docker compose -f docker-compose.yml -f docker-compose.ghcr.yml pull
docker compose -f docker-compose.yml -f docker-compose.ghcr.yml up -d

Tip: if you layer *.av.yml or *.intelligence.yml, keep the matching profile flag (--profile av / --profile intelligence) in the same command.

Env tip: keep Compose variables in repo-root .env (for example RECOMBYN_TAG, RECOMBYN_INTELLIGENCE_*) and API app variables in apps/api/.env; avoid passing env values inline in shell commands.

docker compose up -d redis   # or: mysql redis
npm install
cp apps/api/.env.example apps/api/.env
npm run dev:api              # empty DATABASE_URL → SQLite
npm run dev:collab           # Yjs WS on :1234 (optional; Vite DEV defaults collab on)
npm run dev:web

Canvas Live / WSS setup: docs/self-hosting.md § Canvas multiplayer · apps/collab/README.md

See docs/desktop.md. Needs Rust + platform toolchain.

# Local — bundled API sidecar + SQLite
npm run dev:desktop
npm run build:desktop:sidecar
npm run build:desktop

# Cloud — same API as browser (:8000 / .env)
# Optional: VITE_API_BASE_URL when hosted
npm run dev:desktop:cloud
npm run build:desktop:cloud

Build output: apps/web/src-tauri/target/release/bundle/ (installers); main binary …/target/release/recombyn.exe.

apps/web/          React canvas + Agent UI + Yjs client
  src-tauri/       Tauri v2 desktop shell (zuoge)
apps/api/          FastAPI — Scene, Agent, plaza, wallet, collab tokens
apps/collab/       Yjs WebSocket server (y-websocket)
plugins/           Extensions (skills + canvas) — Compose-mounted
packages/          Shared builders & schemas
docs/              self-hosting, agent-profile, plugins, desktop, canvas
deploy/            Dockerfiles / Nginx
e2e/               Playwright

User docs: recombyn.github.io/recombyn/ (published from this repo’s gh-pages).

• Issues — bug & feature templates under .github/ISSUE_TEMPLATE/
• PRs — see CONTRIBUTING.md
• Security — report privately per SECURITY.md

Official: recombyn.com · Docs: recombyn.github.io/recombyn · Source: github.com/recombyn/zuoge