Open Design Tutorial: Install It, Connect Codex, and Build an Editable Prototype

Open Design is a local-first AI design workspace. Instead of returning a flat, uneditable image, it lets tools such as Codex, Claude Code, and Cursor generate real HTML, CSS, components, and presentation files inside the project directory, which Open Design can preview, manage, and export.

This guide follows an end-to-end acceptance workflow: install Open Design, confirm that the coding agent is detected, generate a landing page, inspect the generated files, and locate logs and recovery options when something fails.

Select the installation route first

Use the latest version of the desktop package in GitHub Releases as a priority when you want to experience it. Do not download specific historical versions like the old tutorial; Open Design is updated very quickly and should first look at the system requirements and known problems in the distribution instructions.

Install the Windows desktop app and run three checks

After installation and startup, verify the coding agents before generating a project:

1
2
3

Get-Command codex -ErrorAction SilentlyContinue
Get-Command claude -ErrorAction SilentlyContinue
Get-Command cursor-agent -ErrorAction SilentlyContinue

At least one command should return an executable path. If PowerShell can find codex but Open Design reports it as missing, the desktop application probably inherited an incomplete PATH when it started.

The order of processing is as follows:

1. Quits the process in Open Design, including the system tray.
2. Confirm that the agent installation directory is present in the user-level PATH.
3. Reentry Windows, or start Open Design from the same PowerShell window.
4. Execute Rescan in Settings

Do not copy the executable to the system directory to allow it to be identified, which would confuse subsequent upgrades and competency judgements.

Start a reproducible environment with Docker

Docker’s route is appropriate to confirm whether Web UI and local daemon work properly:

1
2
3
4

git clone https://github.com/nexu-io/open-design.git
cd open-design/deploy
cp .env.example .env
openssl rand -hex 32

Fill in the generated random string deploy/.env:

1
2
3

OPEN_DESIGN_PORT=7456
OPEN_DESIGN_MEM_LIMIT=384m
OD_API_TOKEN=replace_with_the_random_string_generated_above

Then start:

1
2
3

docker compose up -d
docker compose ps
docker compose logs --tail 100

The acceptance standard isn’t “container display” and it’s open. http://localhost:7456, confirm that the page can be loaded, that the list of items can be opened and that there are no repeated database migrations, permissions or token errors in the log.

Discontinuation of service but retention of data:

1

docker compose down

docker compose down -v The data in the volume will be deleted and should only be used in determining that existing items are not available.

Run from source code

The source route requires Node.js 24. Check the version first:

1
2
3

node --version
corepack enable
corepack pnpm --version

The project is currently locked at pnpm 10.33.x. Other Organiser

1
2
3
4
5

git clone https://github.com/nexu-io/open-design.git
cd open-design
corepack enable
pnpm install
pnpm tools-dev run web

tools-dev prints the actual address, and the development port may be assigned dynamically rather than always using 3000. If dependency installation fails, check both the Node major version and the pnpm version selected by Corepack; do not delete the lockfile merely to force dependency resolution.

Access Codex or Claude Code

Open Design will scan this machine. After selecting the local CLI, the generation tasks are performed in the managed project directory, so three things need to be confirmed:

• Agent is logged in and can complete the minimum request once at the normal terminal.
• Agent has read and write permission to Open Design project directories.
• The sandbox or approval policy used allows the creation of products such as HTML, CSS and pictures.

You can run read-only checks first at the terminal:

1
2

codex --version
claude --version

A successful version command does not prove authentication works. Use a temporary directory for the first connection test, ask the agent to read it and return a description, and avoid using a real client project.

Generate the first acceptable prototype

When creating a new project, use a border clear brief:

1
2
3
4
5

Create a single-page SaaS status-monitoring landing page.
The audience is small development teams.
Include a top navigation bar, current status, recent incidents, and a pricing section.
Use a dark theme and no remote images.
Output editable HTML/CSS with no horizontal scrolling at a 390px mobile width.

The first generation is followed by the following order of acceptance:

1. Preview if you can load it, instead of stopping in the blank iframe.
2. Is there a real HTML, CSS or component file in the project file?
3. Changes the title text to the preview to be updated simultaneously.
4. Whether or not resources are available in the browser developer tool 404 or JavaScript abnormal.
5. Cuts the view to 390px, confirming that there is no horizontal scroll and button mask.
6. Close and reopen the item to confirm that the file is still in place, rather than in one session.

This group is more important than looking good. It distinguishes between products that can really continue to be developed and one-time previews.

Check plugins and items with CLI

It’s installed. od After CLI, check the state with a structured output:

1
2
3
4

od plugin list --json
od plugin search "landing page"
od plugin info od-default
od project list --json

Example of applying default plugins:

1

od plugin apply od-default --input brief="a one-page status dashboard"

Install MCP access for external Agent:

1

od mcp install codex

Restart the corresponding Agent after installation and check the list of MCP tools. Do not assume that the client has reloaded the configuration because the command returned successfully.

How do you judge a common failure?

The agent reports that Open Design is not installed

Run Get-Command codex first, then compare it with the PATH inherited by the Open Design process. A desktop app started in the login session may not see newly added environment variables until it is restarted.

The page opens, but generation never finishes

Checks whether the daemon log and Agent are waiting for login, directory authorization or command approval. If Agent also fails to run alone, it should fix Agent instead of reloading Open Design.

Docker page prompt requires Bearer Token

Confirm that the access token is written to .env, recreate the container, and verify that the reverse proxy did not strip the Authorization request header.

1
2
3

docker compose config
docker compose up -d --force-recreate
docker compose logs --tail 200

Presentation docker compose config . Do not send the complete output to the public issue.

The generated result is blank

Opens the developer tool to check Console and Network. If an HTML file exists but a preview is blank, check the entry file, relative resource path, CSP and script run error first; if the file is not generated at all, check the Agent tool call.

Backup, upgrade and recovery

Backup project directories and Docker volumes before upgrading. Source installation should retain local modifications:

1
2
3

git status --short
git pull --ff-only
corepack pnpm install

If the upgrade cannot be started, the current submission or releasing version, Node/pnpm version and complete error is recorded, and the decision is taken on the basis of the distribution note. Do not use the deletion of the entire workspace as a first step.

Scope and limitations

Open Design is best suited to developers who want an agent to deliver editable design files. It is not a complete Figma replacement and does not automatically solve brand consistency, accessibility, or real user validation. local-first also does not mean fully offline: cloud agents and APIs may still send prompts and project content to their service providers.

References:

• Open Design GitHub
• Open Design Quickstart
• Open Designers