Skip to main content

Local Development

Two options for running osqueue locally: SST dev mode (provisions real S3 bucket) or manual mode (in-memory storage).

Option 1: SST Dev Mode​

SST creates a real S3 bucket in your AWS account and runs all services locally.

bunx sst dev

This starts:

  • A broker on http://localhost:8080 (backed by S3)
  • The web dashboard on http://localhost:3001

To run producers and workers:

# In a new terminal
bun run --cwd apps/osqueue producer

# In another terminal
bun run --cwd apps/osqueue worker

SST automatically injects the S3 bucket name via the Resource.QueueBucket binding.

Option 2: Manual with Memory Backend​

No AWS account needed. Uses in-memory storage (data lost on restart).

# Terminal 1: Broker
STORAGE_BACKEND=memory bun run --cwd apps/osqueue broker

# Terminal 2: Producer
BROKER_URL=http://localhost:8080 bun run --cwd apps/osqueue producer

# Terminal 3: Worker
BROKER_URL=http://localhost:8080 bun run --cwd apps/osqueue worker

Web Dashboard​

The web dashboard runs separately:

# Terminal 4: Dashboard
cd apps/web
VITE_BROKER_URL=http://localhost:8080 bun run dev

Open the URL shown in the Vite output (typically http://localhost:5173) to see the dashboard.

Environment Variables​

Key environment variables for local development:

VariableDefaultDescription
STORAGE_BACKENDmemoryStorage backend: memory, s3, or gcs
BROKER_HOST0.0.0.0Broker bind address
BROKER_PORT8080Broker listen port
BROKER_URLhttp://localhost:8080Broker URL for clients/workers
GROUP_COMMIT_INTERVAL_MS50Group commit interval (low for dev)
BROKER_HEARTBEAT_INTERVAL_MS3000Broker heartbeat interval

See Configuration for the full reference.