Construct

Control Plane for Governed AI Software Execution

Construct lets AI create and operate software inside explicit authority, execution, validation, release, and observability boundaries.

The project is advancing along two connected product directions:

1. Governed application variants. Host applications integrate the Construct SDK and expose controlled surfaces and capabilities. Operators can create safe, custom versions of an application without moving every variation into the host's core codebase. Today this works as host-reviewed trusted-same-realm restricted React; broader or less-trusted authorship requires distinct-origin iframe isolation and principal-aware capability enforcement.
2. Executable topology mirrors. Construct will discover and realize isolated copies of complete service topologies, capture generated cross-service telemetry, and govern optimization experiments against those mirrors. Construct itself is the first dogfood topology. The general mirror model and optimizer integration are target architecture, not shipped capabilities.

These directions share the same foundation: declared authority, isolated execution, deterministic policy, immutable artifacts, explicit approvals, provenance, reversible releases, and evidence that never grants authority by itself.

Construct is in the blueprint phase. The repository favors clear current contracts and product direction over backward compatibility with weak scaffolding.

Current system

Boundary	Responsibility	Runtime
platform/web	Contributor-facing setup, workspace, review, preview, and runtime-target UI	Next.js on Vercel
platform/api	Public control-plane API, auth, product orchestration, projects, secrets, previews, and runtime targets	Node on Railway
apps/sandbox-factory	Repository preparation, reusable workspaces, sandboxes, version previews, and execution leases	Private Node service
apps/gatekeeper	Authority compilation, permission review, run authorization, dependency policy, and artifact validation	Private Node service
apps/agent-runtime	Durable threads and runs, model execution, tool mediation, repair, and finalization	Private Node service
apps/artifact-registry	Immutable surface versions, compiled delivery objects, validation receipts, and artifact resolution	Private Node service
apps/preview-proxy	Public, revocable preview-capability edge over exact sandbox versions	Cloudflare Worker
apps/simulation-lab	Local qualification journeys, fault injection, and cross-service evidence checks	Operator CLI

Platform Web talks only to Platform API. Internal services communicate through typed service clients with operation-scoped Ed25519 identity and independent W3C trace propagation. See Construct Architecture for the complete ownership and call graph.

Documentation

Start with the documentation index.

• Mission — the canonical product mission and two directions.
• Governed application variants — the variant lifecycle, trust profiles, and current limits.
• Architecture — current services, packages, providers, and cross-service ownership.
• Roadmap — future work across the two directions.
• Security model and auth model — authority and identity boundaries.
• Environment — local and deployed configuration ownership.
• Terminology — canonical product and engineering terms.

Quick start

Prerequisites

• Node 24 and pnpm 10.11.0
• Docker or another reachable MySQL 8.x server
• Cloudflare CLI access for the named development tunnel

1. Bootstrap the machine

On a new machine:

./scripts/bootstrap

For an existing checkout:

pnpm run setup

The explicit run is required because pnpm setup is a pnpm shell command. Setup installs the pinned toolchain, installs dependencies, creates or reconciles the single developer-maintained root .env.local, and creates the local tunnel and service identity state.

There are no required package-level .env.local files. Generated topology and Ed25519 identity live under .construct/dev-infra/; they are owned by setup and must not be copied into the root file.

2. Start MySQL

docker run -d --name construct-mysql \
  -e MYSQL_ROOT_PASSWORD=password \
  -e MYSQL_DATABASE=construct \
  -p 33067:3306 \
  mysql:8.0

The safe local default is:

DATABASE_URL=mysql://root:password@127.0.0.1:33067/construct

3. Configure the root environment

Edit only the root .env.local with the developer credentials required for the surfaces you are running. Reconcile legacy values and verify the complete local contract with:

pnpm env:init
pnpm env:doctor

The doctor reports variable names and owning services, never values. See Environment configuration for ownership and precedence.

4. Apply the blueprint schema

pnpm db:push

The TypeScript Drizzle schema is the only schema source of truth while product data remains disposable. Do not add migration files during this phase. See Database Schema Workflow.

5. Start the local stack

pnpm dev

Root dev supervises the five Node backends, Platform Web, Workspace Board build watcher, Drizzle Studio, and the named Cloudflare Tunnel:

• Platform Web: http://localhost:4200 and https://app-dev.thejesselee.com
• Platform API: http://127.0.0.1:4100 and https://api-dev.thejesselee.com
• Sandbox Factory: http://127.0.0.1:4101
• Agent Runtime: http://127.0.0.1:4102
• Artifact Registry: http://127.0.0.1:4103
• Gatekeeper: http://127.0.0.1:4104
• Drizzle Studio: http://localhost:4983

Only Platform Web and Platform API are exposed through the development tunnel. Internal services remain loopback-only. Ctrl+C stops the supervised tree and tunnel; recover an interrupted tree with:

pnpm dev:stop
# or
pnpm kill

Use pnpm dev:services for the active service set without public ingress, or pnpm dev:all for every package with a dev script.

Common commands

pnpm env:doctor                  # value-safe environment preflight
pnpm typecheck                   # workspace typecheck
pnpm lint                        # Biome checks
pnpm check                       # typecheck + lint
pnpm build                       # all package build scripts
pnpm smoke:project-setup         # Sandbox Factory setup smoke
pnpm smoke:project-workspace     # production-shaped workspace smoke
pnpm simulation:test            # Simulation Lab tests
pnpm db:push                     # interactive local schema convergence
pnpm db:apply                    # automated disposable-environment apply
pnpm db:studio                   # Drizzle Studio
pnpm db:nuke                     # drop, recreate, and verify database tables
pnpm nuke                        # broad local reset; also removes .construct

pnpm nuke is intentionally broader than pnpm db:nuke: it removes the local Construct state directory after resetting the database. Re-run setup before the next full local session.

Deployment

The intended production graph is:

• Platform Web on Vercel.
• Platform API as the only publicly reachable Railway service.
• Sandbox Factory, Gatekeeper, Agent Runtime, and Artifact Registry on Railway private networking.
• Preview Proxy on Cloudflare Workers.
• Shared MySQL for the current blueprint deployment.

All five Railway services use railway.json; scripts/railway-service selects the package from RAILWAY_SERVICE_NAME. Platform API alone applies the schema during predeploy. Platform Web uses NEXT_PUBLIC_PLATFORM_API_URL; it does not call Sandbox Factory directly.

See Railway Deployment for the deployment contract. Checked-in configuration describes intended provider wiring; it is not proof of current provider dashboard state.