Skip to content
Vercatus

Running your own instance

This section is for people running Vercatus itself: the hosted service’s operators, or an enterprise self-hosting it. Customers of the hosted product never need any of it — the workspace, the vercatus CLI and the API are the product.

The repository

Section titled “The repository”

A TypeScript monorepo: packages/* (core, fetch, extract, knowledge, simulator, agents, workflow, report), apps/api (Hono), apps/web (the workspace), apps/site (this site) and apps/cli. Postgres 17 with pgvector is the only service dependency; Playwright supplies Chromium.

Terminal window
npm install && npm run db:push && npm run seed
npm run api        # http://localhost:4180
npm run web        # http://localhost:4181

AUTH_MODE=single (the default) makes every request act as the default workspace with no login — right for development and for a single-tenant install. AUTH_MODE=multi turns on tenants, sessions, invites and API keys. See Configuration.

Where runs execute

Section titled “Where runs execute”

RUN_MODE=inline (the default) runs workflows inside the API process — simplest for development, and a restart interrupts whatever is crawling (the run is marked interrupted and can be resumed).

RUN_MODE=worker makes the API only queue runs; one or more worker processes claim and execute them:

Terminal window
RUN_MODE=worker npm run api
RUN_MODE=worker npm run worker      # as many of these as you want; WORKER_CONCURRENCY runs each

The queue is Postgres itself (status = queued, claimed with FOR UPDATE SKIP LOCKED, held by a heartbeat), so there is no broker to operate. A worker that dies mid-run loses nothing but the step in progress: the next worker requeues runs whose heartbeat has gone stale and continues from the last completed step. Deploys are therefore safe at any time — stop the old worker (it finishes what it holds and claims no more), start the new one.

The ca command

Section titled “The ca command”

ca works directly against the database and the pipeline, so it can do what the API does not expose to customers: re-run named steps, preview a sitemap without creating a run, generate the crawler’s key.

Terminal window
npm run ca -- run https://example.com/sitemap.xml -n 200
npm run ca -- resume <workflowId> --from deterministic
npm run ca -- discover https://example.com/sitemapindex.xml
npm run ca -- status <workflowId>
npm run ca -- report <workflowId> -o report.html
npm run ca -- keygen ./crawler.key
npm run ca -- steps

npm run estimate -- 500 2500 10000 prints cost and crawl time by page budget under the current profile; npm run eval runs the frozen regression suite (--llm includes the agent steps).

What a run costs to serve

Section titled “What a run costs to serve”

The crawl is nearly free; model calls are the cost, and they scale with pages and intents. Measured on a full-profile run: about $17 for 500 pages, $80 for 2,500, $310 for 10,000 — half that through the Batches API. The plans are priced so that a site’s monthly full run and weekly change runs sit well inside its fee. Cost levers lists what changes the number.

In AUTH_MODE=single, the workspace shows model spend on Usage and on each run — the operator’s cost of goods. In multi-tenant mode that section is hidden from platform customers and shown only to workspaces that bring their own model provider.