Skip to main content

​
Prerequisites

Before starting, ensure you have the following installed:
  • Node.js 18 or higher
  • npm 8 or higher (comes with Node.js)
  • Supabase CLI (installation guide)
  • Git for cloning the repository
Verify your installations:

​
Quick setup

Follow these four steps to get 8Space running on your local machine.
1

Clone and install dependencies

Clone the repository and install all workspace dependencies from the project root:
This installs dependencies for both the landing page and the main app using npm workspaces.
The monorepo uses npm workspaces to manage dependencies across multiple packages efficiently.
2

Start Supabase and initialize database

Navigate to the app package and start the local Supabase instance:
The supabase start command:
  • Downloads Docker containers for PostgreSQL, Auth, Storage, and more
  • Starts services on predefined ports (API: 54321, DB: 54322, Studio: 54323)
  • Outputs connection details including the anon key
The supabase db reset command:
  • Applies all migrations from packages/app/supabase/migrations/
  • Seeds the database with test data from packages/app/supabase/seed.sql
  • Creates three test accounts with sample project data
Save the anon key and service_role key from the output. You’ll need the anon key for the next step.
3

Configure environment variables

Create environment files for both packages:For the main app (packages/app/.env):
For the landing page (packages/landing/.env.local) - optional:
The landing page environment variables are optional for basic usage. Add Stripe and Resend keys only if you’re testing billing or email features.
You can copy from the example files:
Then edit the files to add your actual anon key.
4

Start the development environment

From the project root, start all services with a single command:
This orchestrator script (scripts/dev-all.mjs) starts:
  • Landing page at http://localhost:3000 (Next.js dev server)
  • Main app at http://localhost:5173/app/ (Vite dev server)
  • Swagger UI at a dynamically-assigned port (printed in console)
The console output will show:
You can also run services separately:

​
Test your installation

Once all services are running, verify your setup:

​
Access the application

  1. Open http://localhost:5173/app/ in your browser
  2. You should see the 8Space login page

​
Log in with test accounts

The seed data creates three test accounts. All use the password: password123

​
Explore the demo project

After logging in, you’ll see the “Product Launch Q2” demo project with:
  • 5 sample tasks across different workflow columns
  • Task dependencies demonstrating the timeline view
  • Labels and priorities for task organization
  • Multiple assignees showing collaboration features
Try switching between the Backlog, Kanban, Timeline, and Dashboard views using the top navigation.

​
Verify database connection

You can also access Supabase Studio to inspect the database:
  1. Open http://localhost:54323 in your browser
  2. Navigate to the Table Editor to see your data
  3. Check the Authentication section for user accounts
  4. View Database > Migrations to see applied schema changes

​
Common issues

If you see “port already in use” errors:For Supabase:
For dev servers: Kill the process using the port or change ports in the respective config files.For Swagger UI: Set a custom port:
If the app can’t connect to Supabase:
  1. Verify Supabase is running:
  2. Check your .env file has the correct URL and anon key
  3. Restart Supabase:
If you can’t log in with the test accounts:
  1. Reset the database to re-seed data:
  2. Verify the email confirmations are disabled in packages/app/supabase/config.toml:
If you encounter errors during npm install:
  1. Clear npm cache:
  2. Delete lock files and node_modules:
  3. Reinstall:

​
Next steps

Now that you have 8Space running locally:

Installation guide

Learn about advanced setup options, production deployment, and troubleshooting.

Configuration

Configure authentication providers, enable billing, and customize settings.

Database schema

Understand the database structure and relationships.

API reference

Explore the API endpoints and integrate with external tools.

​
Development workflow tips

Hot reload: Both Vite and Next.js support hot module replacement (HMR). Changes to source files will automatically reload in your browser.
Database changes: After modifying the schema, create a new migration:
Then apply it with supabase db reset.
Stopping services: Press Ctrl+C in the terminal running npm run dev to stop all services gracefully. Supabase runs in the background and must be stopped separately: