Skip to main content

​
Quickstart Guide

This guide walks you through setting up Umbra locally, including both the frontend web interface and the backend CVM (Confidential Virtual Machine) services.
Prerequisites: Ensure you have Node.js 22+, pnpm 10.15.1+, Python 3.11+, Docker, and Docker Compose installed on your system.

​
Frontend Setup

The frontend is a Next.js application that provides the user interface for interacting with the Confidential AI platform.
1

Clone and navigate to the frontend directory

cd frontend
2

Install dependencies

pnpm install
pnpm is pinned to version 10.15.1 in package.json. The Makefile falls back to npm, but pnpm matches the CI environment.
3

Configure environment variables

cp .env.example .env.local
Fill in the following required variables in .env.local:
# Supabase Configuration
NEXT_PUBLIC_SUPABASE_URL=your-project-url
NEXT_PUBLIC_SUPABASE_ANON_KEY=your-anon-key
SUPABASE_SERVICE_ROLE_KEY=your-service-role-key

# Security
FORM_TOKEN_SECRET=$(openssl rand -hex 32)

# Attestation Service
NEXT_PUBLIC_ATTESTATION_BASE_URL=https://localhost

# vLLM Provider Defaults
NEXT_PUBLIC_VLLM_BASE_URL=https://localhost
NEXT_PUBLIC_VLLM_MODEL=your-model-name
Never commit .env.local to version control. Generate a strong FORM_TOKEN_SECRET using openssl rand -hex 32.
4

Set up Supabase

  1. Create a Supabase project at supabase.com
  2. Add http://localhost:3000/auth/callback to Authentication → URL Configuration
  3. Run the schema from supabase/schema.sql to create the waitlist_requests table
  4. Create an admin user and grant the admin role:
update auth.users
set raw_app_meta_data = jsonb_set(
  coalesce(raw_app_meta_data, '{}'), 
  '{roles}', 
  '["admin"]'::jsonb, 
  true
)
where email = '[email protected]';
5

Start the development server

pnpm dev
Or use the Makefile for convenience:
make dev
The frontend will be available at http://localhost:3000

​
CVM Services Setup

The CVM (Confidential Virtual Machine) services handle attestation, authentication, and certificate management for the TEE.
1

Navigate to the CVM directory

cd cvm
2

Start all services in development mode

make dev-up
This command starts all services using Docker Compose with development overrides:
  • attestation-service - FastAPI service for TDX attestation (port 8000)
  • auth-service - Token-based authentication (port 8001)
  • cert-manager - Nginx with Let’s Encrypt and EKM
  • mock-vllm - Mock vLLM service for testing (development mode only)
In development mode, the services run with NO_TDX=true, which bypasses actual TDX hardware requirements. This allows you to develop and test locally without Intel TDX hardware.
3

Verify services are running

Wait for services to be ready and run health checks:
make wait-services
This uses the test_cvm.py script to verify all services are responding.
4

Run integration tests

make test-all
This runs the full integration test suite, including:
  • Health endpoint checks
  • Attestation service validation
  • vLLM/mock vLLM endpoint testing
  • HTTP to HTTPS redirect verification
  • ACME challenge endpoint testing
  • SSL certificate validation
  • CORS configuration checks
  • EKM header forwarding (dev mode)
To test in production mode (without dev endpoints), run: DEV=false make test-all

​
Verify Your Setup

1

Access the frontend

Open your browser and navigate to http://localhost:3000
2

Check the CVM services

The Nginx proxy is available at https://localhostTest individual endpoints:
  • Health: make test-health
  • Attestation: make test-attestation
  • vLLM: make test-vllm
3

Try the Confidential AI workspace

  1. Navigate to /confidential-ai on the frontend
  2. The UI will establish an RA-TLS connection to the TEE
  3. Wait for attestation verification to complete
  4. Once verified, you can submit prompts and upload documents
In development mode with NEXT_PUBLIC_ATTESTATION_TEST_MODE=true, real attestation verification is skipped. Remove this variable to test actual attestation flows.

​
Development Workflow

​
Frontend Commands

# Run development server
make dev

# Production build
pnpm build

# Start production server
pnpm start

# Run linter
pnpm lint

# Run unit tests (Vitest)
pnpm test:unit

# Run E2E tests (Playwright)
pnpm test:e2e

# Run all tests (used in CI)
make test

​
CVM Commands

# Start services in development mode
make dev-up

# Stop services
make dev-down

# Run all integration tests
make test-all

# Test in production mode
DEV=false make test-all

# Full development workflow (build, up, test, down)
make dev-full

​
Individual Service Development

To work on a specific CVM service: 
cd cvm/attestation-service

# Start FastAPI with hot reload
make dev

# Run unit tests
make pytest

# Run specific test file
uv run pytest tests/test_specific.py -v

​
Stopping Services

1

Stop the frontend

Press Ctrl+C in the terminal where the dev server is running
2

Stop CVM services

make dev-down

​
Environment-Specific Notes

​
Development Mode Features

  • NO_TDX=true - Bypass TDX hardware requirements
  • Mock vLLM - Test vLLM integration without running actual models
  • Dev endpoints - Additional debugging and testing endpoints enabled
  • Test attestation mode - Skip real DCAP verification in E2E tests

​
Production Mode

For production-like testing locally: 
DEV=false make test-all
This tests without development endpoints and validates production configurations.

​
Troubleshooting

Common Issues:
  • Port conflicts: Ensure ports 3000 (frontend), 8000 (attestation), 8001 (auth), and 443 (nginx) are not in use
  • Docker permissions: Make sure your user has permission to run Docker commands
  • Supabase connection: Verify your Supabase credentials are correct in .env.local
  • pnpm version: Ensure you’re using pnpm 10.15.1 or higher

​
Next Steps

Architecture Overview

Understand how Umbra’s components work together

Security Guide

Learn about Umbra’s security mechanisms in depth

Build docs developers (and LLMs) love

Get started for freeTalk to us