Skip to content
proximaforma
Sign inCreate an account
Documentation / v0.1

Getting started

From an empty canvas to your first agent edit. Start locally, then make the workspace your own.

Already running the app? Open the workspace and skip to your first design.

1. Run the workspace

In the repository, install dependencies and start the app. You need Node.js 22.13 or newer with the built-in SQLite runtime.

Terminal · from the repository
npm ci
npm run dev

Open 127.0.0.1:5173/app. The API and MCP server run on port 4310 by default. Keep both processes running while you work.

Run the built app from one server
Terminal · production build
npm run build
npm start

Open 127.0.0.1:4310/app. The marketing pages, editor, API, and MCP endpoint are served by the same local process.

2. Create your account and canvas

  1. Open the app and choose Create an account.
  2. Enter your name, email, and a password of at least 15 characters.
  3. Save the recovery code in your password manager. Email recovery is not configured.
  4. Choose New canvas. Start blank or with an editable sample.

Your account’s canvases are private. The existing local workspace remains separate and is available only on a local installation.

Create your account

3. Bring your agent into the conversation

Open a canvas and choose Connect agent, then Copy setup instructions. Paste them into your agent. It opens the guide, chooses its own name, and connects to your canvas. The app confirms when it makes its first request. Access defaults to this canvas, with design and comment permission for 30 days.

A first prompt for your connected agent
Read my canvas and its comments. Create a homepage for my product, using the latest project revision. Reply to feedback and mark it handled after addressing it.

See the MCP guide or the API guide. Once a design appears, choose Comment and click the design to leave feedback.

Help & troubleshooting

The workspace cannot connect
Check that the app’s server is running. Open the health endpoint; it should return an “ok” response. Restart the local development process if needed.
A port is already in use
Stop the duplicate app process. To change the API port, set the PORT environment variable before starting the app; use a new setup link from Connect agent.
An agent receives an authentication error
If a setup link expired or was already used, create a new link in Connect agent. For an existing connection, check whether its key expired or was revoked. Local URLs require an agent on the same computer. Manual stdio paths must match your installation.
An edit returns a revision conflict
Read the project again and retry the intended change using its latest revision. Another edit arrived before your request.
An external image does not load
Use a direct HTTPS image URL that the browser can access. Some hosts block external embedding or require authentication.

For reproducible issues, keep the steps, app version, and error message with your repository’s development notes. Remove agent keys before sharing logs.

Your local data

The app stores designs and hashed agent keys in .data/workspace.sqlite. Set PROXIMAFORMA_DATA_DIR to an absolute path to use a different directory. Stop the app before making a simple file-copy backup.

Read Your data for agent access, browser storage, and external image behavior.

Keep exploringCanvas guideMCP connectionREST API