Local Development

Setting Up the Repository

Clone your fork and install the workspace dependencies with Vite+:

git clone https://github.com/your-org/void.git
cd void
vp install
vpr install:void-dev
void-dev --help

Use the Node.js version recorded in .node-version. The workspace uses public npm packages; a GitHub Packages token is not required.

install:void-dev builds the CLI, shared packages, and platform runtime, then makes this checkout's built CLI globally available as void-dev. Public packages export their built files, so run vp run build:core after later source changes to refresh the alias. The installer refuses to replace an unrelated global command. Remove only this checkout's alias with vpr uninstall:void-dev. The commands on these development pages run from the repository root.

Finding the Implementation

Directory	Purpose
packages/void	Framework, application runtime, and CLI
packages/platform	Installer contracts, packaged Workers, and platform migrations
packages/deploy-core, packages/deploy-cloudflare	Shared deployment contracts and Cloudflare upload code
platform/packages/api	Users, projects, deployments, provisioning, and administrator API/UI
platform/packages/dispatch	Application routing and static assets
platform/packages/proxy	AI, remote bindings, and revalidation
platform/packages/email-gateway	Inbound mail routing and tenant delivery
platform/packages/tail	Runtime log ingestion
platform/packages/dashboard	Dashboard source and local UI components in ui/

The @voidcloud/* names identify workspace implementation packages. Their private: true flags prevent publishing those packages to npm. Deployable core Workers are bundled into the public @void/platform package.

The core installer creates the API, dispatch, proxy, and tail Workers. The dashboard and managed GitHub build services are available in the source tree but are not included in that installation. Adding an optional service requires its infrastructure, bindings, authentication, and capability configuration together.

Running the API Locally

Start a local PostgreSQL server and make psql and pg_isready available on your path. Then create the development database, apply its migrations, and seed an administrator:

vp run --filter @voidcloud/api setup --admin-email dev@example.com
vp run --filter @voidcloud/api dev --local --enable-containers=false --host localhost --port 8787

The command disables the optional build containers, so basic API and admin work does not require Docker. To develop managed builds, install Docker and run the API with containers enabled.

Open http://localhost:8787/admin/. Setup writes local development values to the API and dashboard .dev.vars files, including the development authentication bypass and local database connection. Those files are ignored by Git. Production installations get separate credentials through the installer.

The API's development bypass lets you work on the browser admin UI without setting up OAuth. Operator CLI sessions still require administrator authentication; they do not use the browser bypass.

Running the Dashboard Locally

The dashboard is a separate source app. After API setup, start it in another terminal:

vp run --filter @voidcloud/dashboard dev

Its local .dev.vars should point to the API you started:

API_URL=http://localhost:8787
SITE_DOMAIN=apps.example.com

Open the Vite URL and choose Dev login (local API). That button appears for a localhost API and uses the local development sign-in endpoint.

You can also point the dashboard at an API that you operate. If Cloudflare Access protects that API, install cloudflared and opt into the dashboard's local token helper with matching origins:

API_URL=https://platform.example.com
CF_ACCESS_APP_URL=https://platform.example.com
SITE_DOMAIN=apps.example.com

The helper refreshes an Access session before the dev server starts. Human dashboard requests require the user's Access session as well as their Void login; a service token does not represent that user. Service-token pairs are for scoped machine operations. This is dashboard development configuration; Access credentials are separate from platform login credentials.

For a deployed dashboard, bind its API service to your platform API, configure DASHBOARD_URL on both the dashboard and API, and include that exact dashboard origin in the platform's Access protection application. The dashboard passes the browser's company identity to the API using that service binding. Its login page shows the platform's currently enabled methods, and Account supports adding an additional login identity.

Testing Changes

Run tests for the area you changed while developing:

vp test run platform/packages/api/test/integration/operator-auth.test.ts
vp run check

Before preparing a release, build the packages and run the complete checks:

vp run build:all
vp run check
vp lint
vp run lint:platform
vp fmt --check
vp test run
vp run build:docs

Platform integration tests use their local test database by default. To test against PostgreSQL, set VOID_TEST_DATABASE_URL to a disposable database: these tests clear tables between cases.

To exercise a deployed application, deploy a disposable copy of playground/kitchen-sink and pass its URL as SMOKE_URL to the smoke test described in platform/scripts/kitchen-sink-smoke-test.md. That test creates and removes application data.