Self-host Squig’s agent tools

Requirements

Use Node.js 22 or newer, pnpm 10, and a Neon Postgres database. The existing offline canvas works without a database. Agent endpoints fail explicitly with 503 until DATABASE_URL is configured. The provisioned database is the durable source of truth; process memory and browser storage are never used as a cloud persistence fallback.

Install and migrate

Create a Neon database through the Vercel Marketplace or your own Neon account. Set DATABASE_URL in .env.local. Set SQUIG_PUBLIC_URL to the public origin of your instance (http://localhost:3000 for local development). The app uses this value for returned canvas links. Keep secrets out of NEXT_PUBLIC_ variables.

pnpm install --frozen-lockfile
pnpm db:migrate
pnpm db:check
pnpm dev

Deployment

Vercel runs pnpm build:hosted: the additive, idempotent migration, then the readiness check, then the app build. This prepares the schema before the deployment can receive traffic; missing storage or a failed migration stops that deployment. Connect the database integration to the deployment environments and configure SQUIG_PUBLIC_URL. Other hosts should also use pnpm build:hosted. Run pnpm test, pnpm test:agent and pnpm lint, then verify a preview with the MCP integration smoke test before promoting it. The ordinary pnpm build and Webxdc package remain database-free. All API and MCP routes use the Node.js runtime. Back up the database and set retention/budget policies suitable for your instance.

Readiness before promotion

Run pnpm db:check with the exact DATABASE_URL and database role used by the target deployment. It reads schema metadata without creating workspaces, consuming signup quotas or changing documents. It checks connectivity, required columns in all five agent tables, table permissions, and the nullable review_hash upgrade. It prints ready: true and exits zero on success; failures exit nonzero with a stable diagnostic code and an operator action. Both db commands accept an injected DATABASE_URL without .env.local; an existing environment variable takes precedence over that file. A passing ordinary build does not prove database readiness. Hosted builds include the check; ordinary local builds and Webxdc remain usable without hosted storage. After the check, run the REST/MCP smoke suite on a preview to verify actual writes before promoting it.

pnpm db:check
# If AGENT_STORAGE_SCHEMA is reported:
pnpm db:migrate
pnpm db:check

Storage and access

agent_workspaces stores hashed workspace keys. agent_documents stores current JSON, revision, hashed canvas capabilities. agent_revisions stores immutable canvas versions. agent_comments stores feedback. agent_limits stores one counter per hashed quota key. Canvas saves and revision records are written in one SQL statement. The revision predicate provides compare-and-swap conflict detection across server instances.

External agents and preview protection

A Vercel SSO-protected preview redirects unauthenticated HTTP and MCP clients before Squig sees their canvas key. A canvas key cannot bypass hosting authentication. Use a public instance, or an explicitly configured Vercel protection bypass for testing. The protected-preview smoke script uses vercel curl with your authorized CLI session. Do not paste a project-wide bypass secret into ordinary canvas invitations. Domain-specific protection exceptions require the Advanced Deployment Protection add-on on Pro. This is a hosting setting, not an MCP installation problem.

Operating an instance

Set signup limits appropriate for your audience, and configure network or platform rate limiting for hostile traffic. This release is capability-based: there are no user accounts, named reviewer identities, email invitations, OAuth, billing or account recovery. Anyone holding a canvas link can edit that canvas. Delete abandoned workspaces administratively with a parameterized SQL query; document, revision and comment rows cascade. There is no automatic expiry. Keys and private links must not appear in logs or analytics.

Offline packaging

The Webxdc build excludes server-only routes and includes the original offline canvas. Agent connections require the hosted Next.js server and are unavailable in the offline package.