Skip to main content
Run your own control plane, database, and ingress with your own cloud Sandbox/model accounts. The repository provides source startup and local compiled distribution; this guide does not assume published Docker images, Helm charts, or SaaS onboarding.

Choose a mode

Use local mode and the managed launcher on a trusted single-user machine; see local workspace operations. Use hosted mode for an explicitly addressed deployment with configured identity, storage, and stable credential ingress. Publicly binding local management is not a substitute for hosted identity setup. A deployment needs Node 22.19+, PostgreSQL, the matching encryption key, API/Console, worker, separate preview ingress, and a separate credential listener. The current main entry assembles API and worker together; there is no assumed separate worker CLI.

Source and compiled distribution

Install source dependencies with npm ci. Maintainers can build:
In that directory, npm ci --omit=dev installs production dependencies. Local-mode management uses the included local scripts. The artifact includes compiled code, Runtime/Console assets, and locked dependencies, not your database or credentials. Building does not publish it.

Hosted prerequisites

Supply secrets through private deployment configuration. Do not put actual values in examples or shell history. The bootstrap Token is not an arbitrary string: startup authenticates its existing owner identity. Hosted mode has no complete organization/login provisioning service; prepare identity through an appropriate supported migration or deployment process. An empty database and random Token are insufficient. With identity, key, ingress, and database prepared, a source deployment runs:
The foreground dev entry does not provide process management, TLS, or backup. Configure those in your deployment environment and retain database/key storage. Configure separate ingress before exposing services. SDKs use explicit URLs and Tokens.

Start and check in dependency order

  1. Prepare the intended database, matching encryption key and existing owner identity. Run migrations against that target before serving traffic.
  2. Route the stable credential origin to the credential listener. Keep API/Console and preview origins separate; do not expose management through the credential route.
  3. Start the entry under your process supervisor. Check authenticated health for database, worker and credential-backend state, not merely whether a socket listens.
  4. Configure and validate Sandbox/model connections, then run the required cloud task with each SDK. Check required preview behavior and retained artifacts separately.
  5. After settling work and confirming cloud cleanup, restart the same deployment and verify retained records and credential decryption. Keep backup and recovery records before upgrades.
The local compiled-distribution acceptance exercised production-only dependency installation, independent cloud tasks, workspace restore and subsequent tasks. It establishes one concrete local-mode deployment path. It does not establish a hosted identity bootstrap service, hosted production topology, multi-replica operation or a Kubernetes deployment. Hosted prerequisite validation is a narrower configuration contract; obtain deployment-specific evidence before claiming that topology is accepted.

Acceptance

Verify migrations, authentication, API/worker health, Sandbox-to-credential connectivity, model execution, private previews, retained artifacts, and confirmed cleanup. Verify records and decryption after restart. Test multi-replica, high availability, and capacity in the actual topology rather than inferring them from lease support. Before upgrades, settle work and back up matching database/key material. SaaS organizations, billing, and managed operations are not automatically supplied by hosted mode. Sources: mode validation, entry, distribution. Next: networking, identity and Tokens, monitoring.