Skip to main content

Quick Start Guide

Get Spatial OS running in 5 minutes.

Prerequisites​

  • Node.js 18+
  • npm or yarn

1. Start the Server​

# Clone the repository
git clone https://github.com/spatial-os/spatial-os-core.git
cd spatial-os-core

# Install dependencies
npm install

# Start local server
npm run dev:local

Server runs at http://localhost:8787

Option B: Deploy to Cloudflare​

# Login to Cloudflare
npx wrangler login

# Deploy
npm run deploy

2. Create an Account​

curl -X POST http://localhost:8787/auth/register \
  -H "Content-Type: application/json" \
  -d '{
    "email": "you@example.com",
    "password": "your-password"
  }'

3. Login and Get Token​

curl -X POST http://localhost:8787/auth/login \
  -H "Content-Type: application/json" \
  -d '{
    "email": "you@example.com",
    "password": "your-password"
  }'

Save the returned JWT token.

4. Create Your First Space​

curl -X POST http://localhost:8787/spatial/space \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -d '{
    "space_id": "my-first-space",
    "name": "My First Space"
  }'

5. Create a Spatial Anchor​

curl -X POST http://localhost:8787/spatial/anchor \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -d '{
    "space_id": "my-first-space",
    "anchor_type": "GPS",
    "position": {"x": 0, "y": 0, "z": 0},
    "rotation": {"x": 0, "y": 0, "z": 0, "w": 1},
    "payload": "hello-world",
    "lat": 37.7749,
    "lon": -122.4194
  }'

Next Steps​