> ## Documentation Index
> Fetch the complete documentation index at: https://opencanvas.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Get started with DesignJS

> Clone the repo, install dependencies, and have the HTML/CSS canvas running locally in under five minutes — no cloud account required.

DesignJS runs entirely on your machine. The canvas is a local Vite app you run from the cloned repo; agents connect to it over a WebSocket bridge on `127.0.0.1:29170`. Getting set up is two steps — **start the canvas**, then **scaffold (or wire up) a project for your agent**.

<Info>
  The canvas itself (the React + GrapesJS app) is not yet distributed as an npm package — you run it from the repo. The MCP server and the project scaffolder **are** published on npm (`@designjs/mcp-server`, `create-designjs`), so your agent's project doesn't need a clone.
</Info>

## Prerequisites

* **Node.js 20 or later** — [nodejs.org](https://nodejs.org)
* **pnpm 9 or later** — install via [Corepack](https://nodejs.org/api/corepack.html):

```bash theme={null}
corepack enable
corepack install -g pnpm@9
```

## Step 1 — Start the canvas

<Steps>
  <Step title="Clone the repository">
    ```bash theme={null}
    git clone https://github.com/rubychilds/DesignJS.git
    cd DesignJS
    ```
  </Step>

  <Step title="Install dependencies">
    From the repository root, install all workspace packages at once:

    ```bash theme={null}
    pnpm install
    ```
  </Step>

  <Step title="Start the development server">
    ```bash theme={null}
    pnpm dev
    ```

    This command builds the `@designjs/bridge` package (so protocol types are up to date) and then boots the Vite dev server with the React canvas app. The WebSocket bridge starts automatically as part of the same process.
  </Step>

  <Step title="Open the canvas">
    Navigate to **[http://localhost:3000](http://localhost:3000)** in your browser. You should see the three-pane editor — block palette on the left, the GrapesJS canvas in the center, and the style/layer panels on the right.

    The connection status indicator in the top-right corner of the editor shows whether an AI agent is currently connected. It will show disconnected until you complete step 2.
  </Step>
</Steps>

## Step 2 — Scaffold a project for your agent

Leave the canvas running in its own terminal. In a **second terminal**, scaffold a new project wired up to the MCP server:

```bash theme={null}
npm create designjs@latest my-app
cd my-app
```

This drops three files in `my-app/`:

* `.mcp.json` — tells Claude Code / Codex-style clients to spawn `npx -y @designjs/mcp-server`
* `CLAUDE.md` — agent guidance biasing tool choice toward DesignJS (and away from other design MCPs you may have configured globally)
* `README.md` — project-level quickstart + troubleshooting

Now start your agent **from inside `my-app`** (not its parent):

```bash theme={null}
claude          # or cursor . / code .
```

On the first tool call, the agent runs `npx -y @designjs/mcp-server`, connects to the canvas, and the bridge dot in the editor topbar turns green.

<Tip>
  **Already have a project?** `create-designjs` refuses to scaffold into a non-empty directory. For existing projects, write `.mcp.json` by hand — see [Connect an agent](/connect-agent) for the three-line config and troubleshooting for the most common discovery issues.
</Tip>

## What's running

Once `pnpm dev` is up, two services are active:

| Service          | Address                                | Purpose                                         |
| ---------------- | -------------------------------------- | ----------------------------------------------- |
| Canvas UI        | `http://localhost:3000`                | The visual editor you open in your browser      |
| WebSocket bridge | `ws://127.0.0.1:29170/designjs-bridge` | The relay between the MCP server and the canvas |

<Info>
  Both services are started by a single `pnpm dev` command. You do not need to start them separately.
</Info>

## Keyboard shortcuts

Once the canvas is open, a few shortcuts are worth knowing right away:

| Action              | Mac     | Windows / Linux |
| ------------------- | ------- | --------------- |
| Save                | `Cmd+S` | `Ctrl+S`        |
| Duplicate selection | `Cmd+D` | `Ctrl+D`        |

The canvas also auto-saves every 30 seconds to `.designjs.json` in the project root.

## Next steps

<Card title="Connect an AI agent" icon="plug" href="/connect-agent">
  Wire Claude Code, Cursor, or VS Code to the canvas so your agent can read and write designs directly.
</Card>