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 = 'your-email@example.com';
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