Installation
Complete setup guide for running the Vectreal Platform locally.
1. Clone the repository
git clone https://github.com/Vectreal/vectreal-platform.git
cd vectreal-platform2. Install dependencies
pnpm installpnpm workspaces will install dependencies for all apps and packages in a single pass.
3. Configure environment variables
Copy the example environment file and fill in the required values:
cp .env.development.example .env.developmentThe key variables you must configure for local development:
| Variable | Description |
|---|---|
SUPABASE_URL | Local Supabase API URL (default http://localhost:54321) |
SUPABASE_KEY | Supabase anon key (from supabase status) |
DATABASE_URL | PostgreSQL connection string (default uses local Supabase port) |
GOOGLE_CLOUD_STORAGE_CREDENTIALS_FILE | Path to a GCS service account key JSON file |
GOOGLE_CLOUD_STORAGE_PRIVATE_BUCKET | GCS bucket name for model assets |
Google Cloud Storage is required for uploading and serving 3D model files. Create a bucket and service account via the GCP console for local testing.
4. Start the local Supabase stack
pnpm supabase startThis starts a local Supabase instance (Postgres, Auth, Storage, Studio) via Docker.
After first start, run:
pnpm nx run vectreal-platform:supabase-db-resetThis applies all migrations and creates the baseline schema.
You can view the local Supabase Studio at http://localhost:54323.
5. Start the platform app
pnpm nx dev vectreal-platformThe app will be available at http://localhost:4200.
6. Verify the setup
- Open http://localhost:4200 — you should see the Vectreal home page.
- Navigate to
/sign-upand create an account. - You should be redirected to the onboarding flow, then to the dashboard.
- Upload a model in the Publisher to confirm the full GCS pipeline works.
Running other projects
The monorepo uses Nx. To run any project:
pnpm nx run <project-name>:<target>
# e.g. pnpm nx run vectreal-platform:build
# e.g. pnpm nx run vctrl/viewer:storybookTo list all available targets for a project:
pnpm nx show project vectreal-platform --webTroubleshooting
supabase start fails — make sure Docker Desktop is running and you have at least 4 GB of RAM allocated to Docker.
Database URL connection errors — check that SUPABASE_DB_PORT in .env.development matches the port shown in supabase status.
GCS PERMISSION_DENIED errors — verify the service account key file path in GOOGLE_CLOUD_STORAGE_CREDENTIALS_FILE is correct and the account has Storage Object Admin on the bucket.
Next steps
- Your First Model — upload, optimize, and publish a 3D model
- Guides — deep-dive into individual platform features
- Package Reference — jump to
@vctrl/viewer,@vctrl/hooks, and@vctrl/coreAPIs