Product and setup documentation

How Nocta works, what it needs, and what it does not do.

What Nocta does

Nocta turns a brief, a public website, a public GitHub repository or a screenshot into a working React + TypeScript + Vite project. Every run moves through five visible stages: Reference, Plan, Code, Test and Preview. One orchestrator does the work; the stages are how it reports progress.

A run is marked complete only when the production build passes and a headless browser loaded the result without uncaught errors. “Build passed”, “Browser check passed”, “Tests not configured” and “Tests failed” are reported separately.

References

  • Brief. Plain language. Links inside the brief become references automatically.
  • Website. Public http/https pages are rendered in a constrained browser inside the sandbox: visible text, headings, navigation, computed styles, a screenshot and the retrieval time are recorded. Private, loopback, link-local and metadata destinations are blocked for the page and every subresource. Login walls are reported, not guessed; attach a screenshot or paste a description instead. Nocta never claims knowledge of a site’s backend or source.
  • GitHub repository. The tree is listed and a bounded set of text files is fetched at a pinned commit (80 files, 200 KB each, 1.5 MB total, 60 s). Binaries and dependency directories are skipped. The framework is detected before execution or modification is offered; explanations cite path:L10-L20 ranges that are checked against the fetched files.
  • Screenshot. PNG, JPEG, WebP or GIF up to 5 MB, passed to the model as an image.

Workspace

  • Preview is the real build output served from a separate origin under a one-hour scoped link. Reload issues a fresh link. Desktop, tablet (768 px) and mobile (390 px) viewports.
  • Files shows the head snapshot. Saving an edit creates a new snapshot that the next run starts from.
  • Changes lists snapshots with diffs against their parent. Restoring an older version creates a new head and keeps history.
  • Checks and the execution log show each command with exit code, duration and real output.
  • Stop prevents new model calls, aborts in-flight requests and kills sandbox processes; the run shows “Stopping” until the worker acknowledges. Resume starts a new run from the last durable checkpoint.
  • Download ZIP contains the source, manifest, lockfile, assets, README, build instructions, the snapshot id and an .env.example when variables are referenced. Secrets, dependencies and caches are excluded; secret-looking values are redacted and listed in NOCTA-EXPORT.md.

API keys and usage

Add your Anthropic API key in Settings. It is validated against the configured model, sealed with AES-256-GCM using the deployment’s encryption key, and decrypted only by the worker for provider calls. It never appears in logs, prompts, generated files, exports or sandbox environments. Removing or rotating the key takes effect on the next run.

Usage records store the provider, model, input/output/cache tokens from each response and measured sandbox time. Cost figures are estimates from a dated price table and are labeled as such; when a model is not in the table the UI shows “Unavailable”. Model usage is billed by Anthropic; sandbox compute is a separate platform cost.

Local setup

Requirements: Node.js 22+, pnpm 9. Copy .env.example to .env.local and generate the two secrets. Then, in a VS Code terminal:

pnpm install
pnpm db:local          # embedded PostgreSQL on 127.0.0.1:15970 (or: docker compose up -d)
pnpm dev               # web app on http://localhost:27100
pnpm worker            # the run worker (separate terminal)

With Docker Desktop (or Docker in WSL) docker compose up -d starts PostgreSQL, Redis and MinIO; set REDIS_URL, NOCTA_QUEUE_DRIVER=bullmq and the S3_* values from .env.example to use them. Without Docker, the PostgreSQL polling queue and the filesystem storage driver work out of the box.

Real model execution needs an Anthropic key (added per user in Settings, or NOCTA_PLATFORM_ANTHROPIC_API_KEY). Real sandboxes come from one of two drivers: NOCTA_SANDBOX_DRIVER=docker (one unprivileged container per run on the worker's Docker host, image from Dockerfile.sandbox, build sandboxes behind an allow-listing egress proxy) or NOCTA_SANDBOX_DRIVER=e2b (an E2B key with the template built by pnpm sandbox:build). The local sandbox driver and the test model provider are development adapters and are refused in production.

Deployment

  • Web app on Vercel (Next.js). Set NOCTA_APP_ORIGIN to the production URL and NOCTA_PREVIEW_ORIGIN to a second domain attached to the same project (previews are refused on the app origin). Register the GitHub OAuth callback at /api/auth/callback/github.
  • Worker on a Docker host: docker compose -f deploy/docker-compose.vps.yml --env-file deploy/worker.env up -d --build runs pnpm worker with the same database and secrets, the Docker sandbox driver (socket + session directory mounted, internal sandbox network, egress proxy) and the sandbox image from --profile tools build sandbox. Alternatives: NOCTA_SANDBOX_DRIVER=e2b with E2B_API_KEY, Redis (REDIS_URL) for the BullMQ queue, S3-compatible storage. The API enqueues jobs and returns a run id immediately; the worker continues independently and the browser restores progress from persisted events after reconnecting.
  • Sandbox cleanup: sandboxes are killed when a run ends; NOCTA_SANDBOX_TIMEOUT_MS is the backstop. Stalled runs (no heartbeat for 2 minutes) are re-queued up to three attempts and resume from their checkpoint.
  • Migrations: pnpm db:migrate against the production database before the first deploy (automatic in development only).

Limits and non-goals

  • Generated projects are React + TypeScript + Vite. Imported Vite + React (TypeScript) projects can be edited; other frameworks are explained only.
  • Defaults: 15 minutes per run, 40 model calls, 150k output tokens, 400 files, 512 KB per file, 5 minutes per command, 3 repair attempts, 1 concurrent run per user, 30 runs per day. All configurable.
  • No GitHub push, no public deployment, no payments: these are planned integrations and no button pretends otherwise.
  • Wallet support is optional and read-only; Nocta is not affiliated with Robinhood. The $NOCTA contract address is published only in the landing page's Token section and at /api/token (CA: Soon until then); it is not required to use Nocta.
  • The landing page's workspace and how-it-works panels show one real run featured by the operator (pnpm showcase:set <runId>, served by /api/showcase with file contents and secrets stripped). Without one they show an empty state, never example data.