FormaSpec

FormaSpec is a self-hosted, AI-first product and UI design workspace. FormaSpec is the product and primary agent-facing identity: a product manager can describe a web, phone, or tablet experience to Codex, review a rendered preview, and continue editing the same structured document in the browser.

The supported agent identity is exactly [@FormaSpec](plugin://formaspec@formaspec). Upgrades remove installer-owned legacy identities after FormaSpec 0.4.0 has been installed and verified.

The application does not embed the OpenAI API and does not require an OpenAI API key. Codex connects through the local FormaSpec MCP bridge. Your Codex subscription or API usage remains separate.

Current release status: the enterprise upgrade is in active development. Core design, persistence, MCP, product-specification, planning, and Codex connection foundations exist, but the repository is not production-ready. See Implementation status for the verified gaps and release blockers.

Install and start

Run one installer command from the repository root. It checks the operating system and requirements, prepares the selected runtime, starts FormaSpec and the loopback bridge, and—when Codex is detected—configures the token-free formaspec MCP server and the managed FormaSpec 0.4.0 plugin.

Docker is the easiest source installation:

./designer --yes install docker

For a local Node.js installation:

./designer --yes install local

The Docker installer and container-local security mode are implemented. The current schema-16 local checkpoint uses image sha256:620d231484044701403ff688493492ff5f8d12d7b09db3de6f00be83cbc658a1. It reaches renderer readiness without fallback, renders the same real PNG before and after an API restart, and denies renderer DNS, direct-TCP, and external-interface egress. The same image passes Firefox/WebKit alignment 12/12 and same-machine copied-bundle recovery into an independent clean Compose project. Evidence is retained at artifacts/ci/docker-schema11/summary.json, artifacts/ci/cross-browser-docker/summary.json, and artifacts/ci/offhost-restore-simulation/NO-GO-SUMMARY.json; the compatibility directory name docker-schema11 is intentionally unchanged. These are local uncommitted-source NO-GO checkpoints, not hosted provenance, a real remote- host/TLS recovery exercise, or production qualification.

The compatibility designer launcher preserves existing .designer state and delegates supported commands to formaspecctl. Remove --yes if you want one explicit authorization prompt before setup and Codex configuration.

After startup, open:

• FormaSpec: http://127.0.0.1:4310

• Local MCP bridge: http://127.0.0.1:4312/mcp

For source development after dependencies are installed:

pnpm dev

Development uses the Vite editor at http://127.0.0.1:4311, the API at port 4310, and the local bridge at port 4312.

Related MCP server: @designjs/mcp-server

Use FormaSpec from Codex

The installer normally performs this connection automatically. To connect or repair it later, run:

./designer --yes agent connect codex

Then start a new Codex task with any of these:

Use FormaSpec to design this product flow.
Design this with FormaSpec.
Refine this selection with FormaSpec.
[@FormaSpec](plugin://formaspec@formaspec) create a professional mobile onboarding flow.

FormaSpec 0.4.0 is the only managed plugin. Start a new Codex task after an installation or upgrade because an already-open task retains its original plugin inventory.

The connection is intentionally token-free in Codex configuration. Codex talks to the loopback bridge; the bridge holds the short-lived upstream scoped grant in macOS Keychain, Linux Secret Service, or a Windows current-user DPAPI blob. The installer sets automatic tool approval only on the trusted local [mcp_servers.formaspec] entry, so Codex does not prompt for every FormaSpec tool call. doctor and status verify that this entry still targets the exact active credential-free loopback bridge before reporting it trusted. Global Codex approval and sandbox settings remain unchanged. Windows code-level DPAPI tests pass; a real packaged Windows lifecycle test is still required before release.

FormaSpec’s MCP server is named formaspec.

The website does not create agent tasks. Start work from Codex or the CLI; after the exact Product, Design, base version, and selection are confirmed, FormaSpec creates the durable MCP task. Codex claims it, reads its authorized context, creates the exact preview, inspects its PNG, runs linting, and transitions it to awaiting_approval with the previewId. The agent must not commit the preview or complete the task. A human reviews the exact preview in FormaSpec and chooses Commit or Discard.

For a direct, non-task request, the agent creates a task first and uses the same human approval boundary:

1. Read project, product-specification, version, and editor-selection context.

2. Read the Product, canonical product specification, effective design-system release, reusable components, tokens, and connected repository mappings.

3. Create a bounded preview without changing history.

4. Inspect the exact rendered PNG, lint diagnostics, accessibility, RTL, responsive variants, interaction states, and engineering feasibility.

5. Publish the task as awaiting_approval; only the website's Commit button may save the exact preview.

6. Return the exact rendered PNG and secret-free review links for human approval.

Archive operations use their own destructive preview and commit tools. A VERSION_CONFLICT requires a fresh read and preview; V1 never auto-merges. See Codex configuration for the manual fallback.

Current control commands

Run the CLI through pnpm while developing:

pnpm formaspecctl -- help
pnpm formaspecctl -- doctor auto
pnpm formaspecctl -- ensure-running --json
pnpm formaspecctl -- status
pnpm formaspecctl -- start docker
pnpm formaspecctl -- stop
pnpm formaspecctl -- restart
pnpm formaspecctl -- migrate status
pnpm formaspecctl -- backup create
pnpm formaspecctl -- backup list
pnpm formaspecctl -- backup schedule show
pnpm formaspecctl -- backup schedule enable --at 02:00
pnpm formaspecctl -- backup schedule run
pnpm formaspecctl -- backup prune preview
pnpm formaspecctl -- backup verify /path/to/formaspec-backup.tar
pnpm formaspecctl -- backup restore /path/to/formaspec-backup.tar --yes
pnpm formaspecctl -- backup restore --backup-id backup_<id> --yes
pnpm formaspecctl -- backup restore offline /safe/path/formaspec-backup.tar --yes
pnpm formaspecctl -- backup restore status
pnpm formaspecctl -- backup restore resume --yes
pnpm formaspecctl -- backup restore resume --offline-bundle /safe/path/formaspec-backup.tar --yes
pnpm formaspecctl -- backup restore rollback --yes
pnpm formaspecctl -- backup restore abort --yes
pnpm formaspecctl -- backup restore clear-stale-lock --yes
pnpm formaspecctl -- agent config generic --format json
pnpm formaspecctl -- support-bundle preview

Currently implemented formaspecctl workflows are:

Automatic supervisor installation/alerting, native package installation, autostart, and full upgrade/uninstall workflows are not complete CLI features yet. Launcher-pinned Docker/server restore now has two separately authorized paths: HEALTHY_PLANNED_RESTORE_ONLY by managed backup ID, and offline recovery from an explicitly selected verified bundle. The offline path does not depend on a healthy current API/database, but it still lacks a retained real Docker/ server corrupt-database lifecycle exercise. Backup create/list/schedule/prune still require the local loopback service, while bundle verification, source-local restore, and support-bundle creation remain separate.

What is implemented

• Structured V1 design documents with stable IDs, typed operations, tokens, assets, prototype links, immutable revisions, PNG rendering, and JSON handoff.

• Content-addressed Brotli snapshots, SHA-256 revision chains, persisted exact previews, idempotent atomic commits, archive-only destructive paths, and replayable organization-scoped SSE.

• Organizations, principals, roles, project ownership, expiring scoped agent grants, audit records, and service-layer project authorization foundations.

• A shared ViewportTransform, untransformed interaction overlay, coalesced Moveable geometry refresh, memoized node views, selection normalization, and an automated Chrome DPR/zoom/pan/LTR/RTL alignment foundation.

• Strict V2 schemas and deterministic V1-to-V2 migration utilities, plus the FormaSpec Foundation System model.

• Product-specification preview/commit, the 22-section planning model, agent tasks/connections, and revision-pinned inspection. The inspect API/view keeps the requested revision separate from the current head and exposes integrity, resolved tokens, assets, components, rules, acceptance criteria, mappings, stable IDs, and JSON paths.

• Checksum-validated portable export, read-only validation, and administrator- authorized mutating import with idempotent preserve-ID conflict failure or deterministic clone remapping, isolated raster normalization, local-version rebasing, and immutable migration-10 provenance.

• Streamable HTTP MCP tools/resources under the formaspec identity and formaspec:// resource scheme.

• A separate bounded Unix-socket Playwright renderer service in Docker with a non-root user, no network, read-only root, dropped capabilities, deterministic contexts, resource limits, and fail-closed health.

• Schema 11 persistent render-job records for rendering and raster normalization. The API owns the database lifecycle (queued → running → terminal), uses owner leases and heartbeats for rolling-process recovery, retains only bounded hashes/versions/dimensions/warnings/safe errors, and performs permit-guarded 30-day terminal-record retention. The renderer worker remains database-free and output image bytes are not stored in the job row.

• PNG/JPEG/WebP decode and deterministic normalization with byte/pixel limits, generated content-addressed files, integrity verification, and legacy-BLOB fallback.

• A read-only Workspace Bridge foundation with explicit expiring/revocable repository grants, secret/symlink/generated-file exclusion, supported-platform detection, bounded inventories, and path-free upload mappings.

• Automatic managed Codex grant reconciliation: authorized startup reuses a stored credential only when its exact scopes and project restrictions match current organization policy, otherwise it rotates through one-time pairing; Codex configuration remains token-free.

• Approval-gated selected-workspace Codex launch. A grant is bound to the exact central inventory, the handoff must carry the exact immutable approved → implementing start_implementation transition, Codex starts with the selected repository as its exact working directory, one secret-free task argument, shell: false, and a minimal environment. POSIX process-group monitoring terminates the launch after revocation, expiry, policy withdrawal, handoff closure, or inventory change; packaged Windows descendant containment still requires a Job Object or equivalent.

• Persisted organization design systems with append-only token/component versions, immutable releases, project pins, exact upgrade previews, REST/MCP interfaces, and initial Administration UI.

• Central path-free repository inventories, immutable design/spec/source mappings pinned to exact revision and inventory hashes, and revision-pinned engineering handoffs with reviewed mapping UI, human approval/implementation gates, replayable events, and no central filesystem-path input.

• A persisted seven-stage Redesign Studio with independent scopes, immutable stage history, design-version CAS, a planning-only one-click entry, REST/MCP, and a dedicated browser workspace. Future-state entry requires current repository inventory and verified exact-revision mapping evidence.

• A deterministic 1,000-node core/service performance comparison harness.

• Fixed 7-daily/4-weekly/12-monthly managed backup planning with supervisor-run UTC scheduling, preview-first revalidated pruning, and permanent manual-backup exemption.

• Organization Administrator audit retention with exact expiring previews, 30-day minimum enforcement, bounded 2,000-row/8-MiB-per-kind batches, guarded atomic deletion, replay gaps, and immutable SHA-256 chained run evidence.

• Externally supervised launcher-local Docker restore with a mode-0600 exact runtime binding, fail-closed maintenance, shared non-expiring worker lock, crash-resumable journal states, verified safety backup, database/render checks, O_NOFOLLOW source pinning on /backups, committed-journal retention on cleanup failure, restored credential revocation, and explicit recovery commands. Source-local restore passes its exact verified tar-stream hash/size into the same pinning engine.

• A bounded deterministic support bundle with read-only preview, adjacent local manifest, redacted logs/config-key inventory, and explicit creation approval.

These foundations do not close the release gates listed below.

Important current limitations

• Windows renderer named pipes, native lifecycle proof, and continuous egress/failure/load proof remain unfinished beyond the verified Docker network-denied worker. Render and raster-normalization jobs persist a bounded hash-only, owner-leased lifecycle with exact 30-day retention, but organization-configurable retention dashboards and packaged load evidence remain open.

• Current schema-16 local evidence passes editor/Administration 5/5, release E2E 1/1, preview integration 2/2, Chromium alignment 12/12, Firefox/WebKit alignment 12/12, visual regression 7/7, and all 1,000-node browser budgets. The Docker restart/egress and copied-bundle recovery gates also pass locally. Hosted supported-OS repetition, the current security/ SBOM/image scans, signed native lifecycle evidence, and real remote-host/TLS recovery remain open.

• Five repository-native least-privilege workflows now cover frozen source gates, browser alignment/visual/performance/release suites, historical Docker smoke, deterministic SBOM/license evidence, unsigned Linux packages, and the non-installing macOS extracted-runtime gate. The local evidence helpers pass workflow contracts 8/8, cross-browser runner tests 2/2, off-host simulation tests 7/7, release-evidence tests 8/8, macOS package-evidence tests 12/12, and macOS runtime-smoke contract tests 11/11; no GitHub-hosted run or real Ubuntu DEB/RPM artifact has yet been retained.

• Complete component/release authoring and upgrade-review UI, framework-aware Workspace Bridge mapping/upload/implementation launch, and full Redesign Studio artifact/E2E coverage remain unfinished. Portable import now streams the multipart upload into a private mode-0700 staging directory, pins the archive by hash/size, validates its central/local headers from bounded reads, and inflates each entry in 16 KiB chunks into private files. It no longer retains the multipart body or all extracted entries in memory. Individual JSON/raster entries are still read under the 64 MiB per-entry cap when parsed or normalized; broader concurrent/adversarial and packaged evidence remains.

• Verified backup creation/list/verification/download and portable validation/ import are exposed in /administration; source-local restore, supervisor-callable schedule/prune, launcher-pinned planned restore, and the explicitly authorized offline bundle path exist. Installed supervision/ alerting, signed provenance, an isolated end-to-end formaspecctl offline lifecycle, and broader failure-recovery evidence remain unfinished. A real unique-project formaspecctl smoke now exercises the offline worker/control path through the validated persisted Compose identity. Server-mode proxy lifecycle, packaged-runtime, real remote-host/network/TLS/off-site recovery, and broader proof remain open. A separate same-machine copied-bundle smoke now passes against an independent clean target without claiming those remote guarantees.

• A retained pre-current-SSE-authorization unsigned schema-12 macOS ARM64 engineering checkpoint is stored at artifacts/candidates/schema12-current/installers/FormaSpec-0.2.0-macos-arm64-unsigned.pkg (185,279,180 bytes; SHA-256 9724f2874c520b5b2b2fa99419978c392a22ee2f534ec9c1ca6e6c49db3fea18). It was not installed. Package integrity passes with 349 components, seven exact workspace trees, two bundled runtimes, and no workspace-output drift; the private extracted-runtime smoke also passes schema-12 health, a real Playwright PNG, and the exact 51-tool/25-resource MCP inventory. Its checksum-bound runtime summary hashes to c1719a9ebab5c7d241fa329df1d3bb6b19bb34b252c063abc276818e48c41964. The candidate-root SHA256SUMS manifest verifies all 14 retained package, sidecar, source, runtime, reproducibility, and documentation entries. Its original evidence remains valid for the frozen bytes, but the current verifier now reports expected source drift: packaged apps/server/dist predates the exhaustive event-authorization policy and the project/revision- bound historical design-system release interface. It is not a package of the current source tree. Release remains NO-GO: Chromium LGPL notices lack policy approval, the package is unsigned and unnotarized, vulnerability scans are missing, clean native lifecycle proof is absent, and reproducibility is unresolved. A same-host repeat produced a different outer PKG (SHA-256 2c49f45a6840218b995cc969576f4209d0c94802a160c679ad02483ed5ba4dd0, 185,279,075 bytes) even though the payload and workspace-tree hashes were identical; the diagnostic summary hashes to 570d1fb98fb61bc8b2f56b75a4a4379575d7ef2c6bf10bb2a1000ad69a2de710. The preserved schema11-current and schema10-current candidates are historical only. Deterministic Linux DEB/RPM builders and a Windows WiX v4 unsigned-MSI foundation exist in source, but no release-qualified native lifecycle evidence exists. Windows tests use fake PE/CFB/WiX fixtures and do not establish a real WiX compile or MSI validity. See Linux packaging, Windows packaging, and macOS PKG evidence.

• New server initializer output includes the strict server-mode, proxy, allowlist, CORS, and container-boundary contract, and the CLI/server migration readers both recognize version 16. Migration 9 adds bounded, preview-first audit/published-outbox retention with immutable hash-chained execution evidence; migration 10 adds immutable portable-import provenance; migration 11 adds persistent bounded render-job lifecycle records; migration 12 adds append-only, independently authorized handoff execution decisions; migration 13 persists canonical component sources and exact upgrade snapshots; migration 14 adds browser-session authentication; migration 15 adds bounded write-once exact preview-render evidence; and migration 16 canonicalizes the legacy bootstrap-credential trigger without rewriting credential rows. Genuine schema 1 and schema 7–12 fixtures are verified to upgrade without changing V1 revision bytes, hashes, IDs, or assets; clean reverse-proxy deployment and real customer planned/offline backup-restore fixtures remain unproven. Server mode now also requires a separate internal proxy hop secret on every non-health request; focused server/launcher tests pass. A controlled actual-TCP-socket lifecycle test also proves header replacement, direct-peer denial, ambiguous append rejection, and restart- bound secret rotation; real Nginx/TLS, identity-provider, firewall/routing, and public-port evidence remains open.

The recorded local-Docker evidence used an isolated Compose project on port 4397: backup backup_0dda1a60c54c5805557426a428739e505e089425 restored design A only, then safety backup backup_7697fb29100b0bc8adc22707114c50947ed3a668 restored A and B. Original design/revision IDs were preserved, restored grant/connection/nonce state was revoked, and the disposable containers, volumes, and network were deleted. This does not change the overall NO-GO release status.

A separate disposable offline-recovery smoke exercised the production worker/ control path on a unique Compose stack: it restored a verified schema-11 bundle after replacing the live database with corrupt marker bytes, reproduced the exact design and PNG, revoked one grant/connection/nonce, then restored the exact corrupt pre-state bytes with durable rolled_back/recovery=offline evidence and removed the stack. The earlier worker/control smoke manually cleared its forensic fence only for disposable cleanup; product semantics keep maintenance active and the API stopped. A subsequent real unique-project formaspecctl smoke validated persisted Compose ownership end to end, closing the former hardcoded-project isolation gap.

Do not expose a source build as an enterprise production service until Implementation status changes the release decision.

Data and compatibility

Source/native data defaults to ./data. Launcher state, logs, and generated runtime configuration remain under the ignored .designer/ directory. Docker persists /data in its Compose volume.

The migration ledger upgrades existing databases in place and keeps the V1 document/history model readable. V2 conversion utilities preserve project, page, frame, node, token, asset, and prototype IDs, but automatic V2 head migration is not enabled as a general operator workflow.

Before an upgrade or restore, follow Backup and restore.

Development verification

Current schema-16 source verification passes the seven-package suite 842/842 (core 59, server 467, web 91, CLI 96, local bridge 20, Workspace Bridge 37, installer 72), launcher 225/225, and all workspace typechecks/builds. Current local evidence also passes editor/Administration 5/5, release E2E 1/1, preview integration 2/2, Chromium and Firefox/WebKit alignment 12/12 each, visual regression 7/7, macOS runtime contracts 11/11, and the 1,000-node browser budgets. Schema-16 Docker restart/egress, exact-image cross-browser, and clean-project copied-bundle recovery checkpoints are retained under artifacts/ci/; the exact schema-13 SBOM/license result remains historical.

pnpm test:run
pnpm typecheck
pnpm build
pnpm test:launcher
pnpm test:e2e:alignment
pnpm test:e2e:alignment:cross-browser
pnpm test:e2e:editor
pnpm test:e2e:visual
pnpm test:e2e:performance
pnpm test:e2e:release
pnpm test:performance
pnpm test:release-evidence
pnpm test:macos-pkg-evidence
pnpm test:macos-pkg-runtime-smoke
pnpm release:evidence:macos:verify
pnpm package:linux:deb
pnpm package:linux:rpm
docker compose config --quiet

pnpm ci:release-evidence is the strict source-workspace production dependency gate. Historical linked-0.45.2 schema-13 source evidence passed with 342 third- party components and zero policy violations after Sharp/libvips was removed; current schema-16 source-workspace and target-artifact evidence must be regenerated. The retained schema12-current unsigned PKG passed its frozen package/workspace integrity check and the non-installing extracted-runtime smoke, but the current verifier now records expected source drift and it remains an engineering checkpoint: the outer PKG was not byte-for-byte reproducible even on the same host, and legal approval, signing, notarization, vulnerability scanning, and privileged native lifecycle proof remain open. The preserved schema11-current and schema10-current candidates are historical; container, Windows, and Linux artifacts still require their own target-specific evidence.

Passing unit/build checks alone does not establish production readiness. The browser, security, performance, backup/restore, installer, and release-evidence gates in Implementation status remain authoritative.

More detail:

• Getting started

• Visual regression testing

• Local installation

• Architecture

• Document schema

• Design system

• Product specification

• Retained CI and release evidence

• MCP

• Agent connections

• Workspace Bridge

• Redesign Studio

• Operations

• Server deployment

• Security

• Threat model

• Troubleshooting

• Support bundles

• Upgrading

• Licensing

• Release checklist

• Enterprise implementation report