Lightfast

A cloud-native agent execution engine that abstracts infrastructure complexity, enabling developers to focus on building AI agent applications.

🌐 Website: lightfast.ai
📚 Documentation: lightfast.ai/docs
🎮 Cloud: cloud.lightfast.ai
💬 Chat Demo: chat.lightfast.ai

About

Lightfast is a production-ready agent execution platform that provides the infrastructure layer for the agent economy. We abstract away the complexity of orchestrating AI agents, managing resources, and scaling applications so you can focus on building amazing AI experiences.

Why Lightfast?

• ⚡ Vercel-like DX: Deploy agents in minutes, not days
• 🔧 State-Machine Engine: Orchestrate complex workflows with proper resource management
• 🛡️ Security Layer: Built-in guards, validation, and runtime constraints
• 🏗️ Resource Scheduling: Intelligently manage Linux sandboxes, browser sessions, API quotas
• 🔄 Advanced Capabilities: Human-in-the-loop, pause/resume, ambient agents, infinitely long execution
• 📦 Simple APIs: Hide complexity while maintaining flexibility

Architecture

Lightfast is a comprehensive monorepo built with pnpm workspaces and Turborepo, containing CLI tools, applications, and packages:

Core (core/)

The core contains the complete CLI toolchain and agent framework:

• ⚡ lightfast - Core AI agent framework and execution engine
• 🛠️ cli - Published CLI package (@lightfastai/cli) that bundles everything
• 🧠 cli-core - Core CLI logic and commands (dev, compile, clean)
• ⚙️ compiler - TypeScript compilation engine with caching and hot reload
• 🌐 dev-server - Development server with React UI for agent management
• ☁️ cloud-client - Cloud platform client utilities

Applications (apps/)

Production-ready Next.js applications with modern architecture:

• 🌐 www - Marketing website and landing pages (Next.js 15 + App Router)
• 🔐 auth - Authentication service and user management
• ☁️ cloud - Main platform application for agent orchestration
• 🎮 playground - Interactive agent playground and testing environment
• 🧪 experimental - Experimental features and prototypes
• 💬 chat - AI chat application demo with Convex real-time backend
• 📚 docs - Documentation site with Fumadocs

Database (db/)

Database schemas, migrations, and related utilities:

• 💬 chat - Chat application database schemas and migrations
• ☁️ cloud - Main platform database schemas and migrations

API (api/)

API definitions, schemas, and shared utilities:

• 💬 chat - Chat application API definitions and utilities
• 🛠️ cli - CLI API definitions and client utilities
• ☁️ cloud - Main platform API schemas and utilities

Supporting Directories

Additional directories for project infrastructure:

• 🔌 api - API definitions, schemas, and shared API utilities
• 🗄️ db - Database migrations, schemas, and database-related scripts
• 📚 docs - Additional documentation and guides
• 🛠️ scripts - Build scripts, deployment utilities, and automation tools
• 📁 examples - Example projects and usage demonstrations
  • 💬 1-agent-chat - Simple agent chat implementation
  • 🤖 nextjs-ai-chatbot - Advanced AI chatbot with Next.js
• 🌳 worktrees - Git worktrees for parallel development branches

Tech Stack

Category	Technology	Purpose
Runtime	Node.js 22+	Runtime environment (enforced minimum)
	pnpm 10.5.2	Package management (enforced via packageManager)
Frontend	Next.js 15	React framework with App Router
	React 19	Latest React features and performance improvements
	TypeScript 5.9+	Strict type safety and developer experience
	Tailwind CSS v4	Utility-first styling with new engine
	shadcn/ui	High-quality UI components with Radix UI primitives
	Jotai	Atomic state management
	Zustand	Persistent state management
Backend	Convex	Real-time database and backend (chat app)
	PostgreSQL	Primary database with PlanetScale
	Drizzle ORM	Type-safe SQL toolkit
	Redis/Upstash	Caching, rate limiting, and queuing
AI/ML	Anthropic Claude	Claude Sonnet 4 and Haiku integration
	OpenAI	GPT-4o and GPT-4o-mini integration
	Vercel AI SDK 5.0+	Streaming, tool calling, and AI utilities
	Browserbase	AI browser automation and web scraping
	Exa	AI-powered web search
DevOps	Turborepo 2.5+	Monorepo build system with intelligent caching
	Vercel	Deployment, hosting, and edge functions
	GitHub Actions	CI/CD pipelines
	ESBuild	Fast TypeScript compilation
Monitoring	Sentry	Error tracking and performance monitoring
	PostHog	Product analytics and feature flags
	BetterStack	Logging, monitoring, and alerting
	Vercel Analytics	Web vitals and performance metrics
Security	Arcjet	Rate limiting, bot protection, and security
	Clerk	Authentication and user management
	Zod	Runtime type validation
Background Jobs	Inngest	Workflow orchestration and background jobs
	QStash	Serverless message queuing
Development	Changesets	Version management and release automation
	Prettier	Code formatting
	ESLint	Code linting and quality
	Biome	Fast formatter and linter (additional)

Getting Started

Prerequisites

• Node.js: >= 22.0.0 (enforced by engines field)
• pnpm: 10.5.2 (enforced by packageManager field)
• Git: Latest version for worktree and submodule support

Installation

1. Clone the repository

   git clone https://github.com/lightfastai/lightfast.git
   cd lightfast

2. Install dependencies

   pnpm install

3. Set up environment variables

   # Copy environment files for each app you want to run
   cp apps/www/.env.example apps/www/.env.local
   cp apps/cloud/.env.example apps/cloud/.env.local
   # Edit .env.local files with your configuration

4. Start development

   # Start all main apps
   pnpm run dev
   
   # Or start specific apps
   pnpm run dev:www      # Marketing site (port 4101)
   pnpm run dev:cloud    # Main cloud app
   pnpm run dev:playground # Playground
   pnpm run dev:docs     # Documentation

Available Scripts

Development

• pnpm dev - Start main development servers (www, experimental, docs, cloud, auth, chat, playground)
• pnpm dev:www - Marketing website (port 4101)
• pnpm dev:cloud - Main platform application
• pnpm dev:auth - Authentication service
• pnpm dev:experimental - Experimental features
• pnpm dev:playground - Agent playground
• pnpm dev:chat - Chat application
• pnpm dev:docs - Documentation site
• pnpm dev:email - Email development server
• pnpm dev:cloud+playground - Run cloud and playground together
• pnpm dev:cloud+playground+auth+docs - Run multiple apps together

Building

• pnpm build - Build all applications (Turbo orchestrated)
• pnpm build:www - Build marketing site only
• pnpm build:cloud - Build cloud app only
• pnpm build:auth - Build auth service only
• pnpm build:experimental - Build experimental features only
• pnpm build:playground - Build playground only
• pnpm build:chat - Build chat app only
• pnpm build:docs - Build documentation only

Code Quality

• pnpm lint - Lint all packages with caching
• pnpm lint:fix - Fix linting issues automatically
• pnpm format - Check code formatting (Prettier)
• pnpm format:fix - Fix formatting issues automatically
• pnpm typecheck - Run TypeScript type checking across all packages
• pnpm lint:ws - Check workspace dependencies with Sherif

Database

• pnpm db:migrate - Run database migrations
• pnpm db:migrate:generate - Generate migration files
• pnpm db:studio - Open Drizzle database studio

Utilities

• pnpm clean - Clean all build artifacts and caches
• pnpm clean:workspaces - Clean Turbo workspaces only
• pnpm ui - Manage shadcn/ui components
• pnpm brain - Run evaluation scripts
• pnpm vercel:link - Link monorepo to Vercel

Release Management

• pnpm changeset - Create a changeset for versioning
• pnpm version-packages - Version packages using changesets
• pnpm release - Publish packages to npm

Environment Configuration

Each application uses @t3-oss/env-nextjs for type-safe environment variable validation. Environment configurations are defined in each app's src/env.ts file.

Common Environment Variables

# Node Environment
NODE_ENV=development

# Vercel (automatically set in Vercel deployments)
VERCEL_ENV=development  # development | preview | production

# Database (if using database features)
DATABASE_URL=your-database-url

# Authentication (if using auth features)
CLERK_SECRET_KEY=your-clerk-secret
NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY=your-clerk-publishable-key

# Observability
SENTRY_DSN=your-sentry-dsn
NEXT_PUBLIC_POSTHOG_KEY=your-posthog-key
BETTERSTACK_SOURCE_TOKEN=your-betterstack-token

# Security
ARCJET_KEY=your-arcjet-key

App-Specific Configuration

Each application may require additional environment variables. Check each app's README for specific requirements:

• apps/www/README.md - Marketing site configuration
• apps/cloud/README.md - Main cloud app configuration
• apps/playground/README.md - Playground configuration
• apps/chat/README.md - Chat app configuration

Project Structure

lightfast/
├── core/                      # Core CLI toolchain and agent framework
│   ├── cli/                  # Published CLI package (@lightfastai/cli)
│   ├── cli-core/             # Core CLI logic and commands
│   ├── compiler/             # TypeScript compilation engine
│   ├── dev-server/           # Development server with React UI
│   ├── lightfast/            # AI agent framework and execution engine
│   └── cloud-client/         # Cloud platform client utilities
├── apps/                      # Next.js applications
│   ├── www/                  # Marketing website (port 4101)
│   ├── auth/                 # Authentication service and user management
│   ├── cloud/                # Main platform application
│   ├── playground/           # Interactive agent playground
│   ├── experimental/         # Experimental features and prototypes
│   ├── chat/                 # AI chat application with Convex
│   └── docs/                 # Documentation site with Fumadocs
├── db/                        # Database schemas and migrations
│   ├── chat/                 # Chat application database schemas
│   └── cloud/                # Main platform database schemas
├── api/                       # API definitions and shared utilities
│   ├── chat/                 # Chat application API definitions
│   ├── cli/                  # CLI API definitions and utilities
│   └── cloud/                # Main platform API schemas
├── packages/                  # Shared packages (@repo/*)
│   ├── ui/                   # UI component library (shadcn/ui + Radix)
│   ├── lib/                  # Shared utilities and helper functions
│   ├── ai/                   # AI SDK integrations and utilities
│   ├── ai-tools/             # AI browser automation with Browserbase
│   ├── email/                # Email templates and utilities
│   ├── site-config/          # Site configuration utilities
│   ├── url-utils/            # URL manipulation and validation
│   └── vercel-config/        # Vercel deployment configurations
├── vendor/                    # Third-party service integrations (@vendor/*)
│   ├── analytics/            # PostHog and Vercel Analytics
│   ├── clerk/                # Authentication with Clerk
│   ├── db/                   # Database layer (Drizzle + PlanetScale)
│   ├── email/                # Email services with Resend
│   ├── inngest/              # Background job processing
│   ├── next/                 # Next.js configuration and utilities
│   ├── observability/        # Sentry and BetterStack monitoring
│   ├── security/             # Arcjet rate limiting and security
│   ├── storage/              # File storage with Vercel Blob
│   └── upstash/              # Redis, KV, and QStash integration
├── internal/                  # Development tooling configurations
│   ├── eslint/               # ESLint configurations (@repo/eslint-config)
│   ├── prettier/             # Prettier configurations (@repo/prettier-config)
│   └── typescript/           # TypeScript configurations (@repo/typescript-config)
├── docs/                      # Additional documentation and guides
├── examples/                  # Example projects and demonstrations
│   ├── 1-agent-chat/         # Simple agent chat implementation
│   └── nextjs-ai-chatbot/    # Advanced AI chatbot with Next.js
├── scripts/                   # Build scripts and automation tools
├── worktrees/                 # Git worktrees for parallel development
├── .changeset/                # Changesets configuration for releases
├── .github/                   # GitHub Actions and CI/CD workflows
├── .lightfast/                # Lightfast configuration and cache
├── .turbo/                    # Turborepo cache and metadata
├── .vercel/                   # Vercel deployment configuration
├── package.json               # Root workspace configuration
├── pnpm-workspace.yaml        # pnpm workspace definition
├── turbo.json                 # Turborepo task configuration
├── CLAUDE.md                  # Development instructions for Claude
├── SPEC.md                    # Product specification and vision
└── README.md                  # This file

Development Workflows

Working with the Monorepo

1. Install dependencies: pnpm install (installs all workspace dependencies)
2. Run specific app: pnpm dev:www or pnpm dev:cloud
3. Build specific app: pnpm build:www (uses Turbo filters)
4. Add dependency to specific app: pnpm add package-name --filter @lightfast/www
5. Run script in specific app: pnpm --filter @lightfast/www run script-name

Package Naming Conventions

The monorepo uses consistent naming conventions across workspaces:

• Apps: @lightfast/[app-name] (e.g., @lightfast/www, @lightfast/cloud)
• Packages: @repo/[package-name] (e.g., @repo/ui, @repo/lib)
• Vendor: @vendor/[service-name] (e.g., @vendor/db, @vendor/auth)
• Core: @lightfastai/[tool-name] (e.g., @lightfastai/cli, @lightfastai/compiler)

Workspace Dependencies

All workspace dependencies use workspace:* protocol for internal packages:

{
  "dependencies": {
    "@repo/ui": "workspace:*",
    "@vendor/db": "workspace:*"
  }
}

Catalog Dependencies

The workspace uses pnpm's catalog feature for consistent versioning across packages:

# pnpm-workspace.yaml
catalog:
  '@tanstack/react-query': ^5.80.7
  'next': ^15.4.0
  'react': 19.1.0
  'typescript': ^5.8.2
  # ... more packages

Packages can reference catalog versions:

{
  "dependencies": {
    "next": "catalog:",
    "react": "catalog:react19"
  }
}

Adding New Components

# Add shadcn/ui component to the UI package
pnpm ui add button

# Generate new React component with Turbo
pnpm --filter @repo/ui generate:component

# The component will be available across all apps

Code Quality Workflow

# Before committing
pnpm lint:fix     # Fix linting issues
pnpm format:fix   # Fix formatting
pnpm typecheck    # Check types

CLI Development

The @lightfastai/cli package provides the main CLI tool for agent development:

# Install the CLI (when published)
npm install -g @lightfastai/cli

# Or use it directly from the monorepo
cd core/cli
pnpm build  # Build the complete CLI bundle
node dist/index.js --help

# CLI commands
cli dev      # Start development server
cli compile  # Compile agent configuration
cli clean    # Clean build artifacts

The CLI includes:

• TypeScript compiler with hot reload and caching
• Development server with React UI for agent management
• Agent configuration compilation and validation

Deployment

Vercel Deployment

Each application can be deployed separately to Vercel:

1. Connect to Vercel

   pnpm vercel:link

2. Configure build settings (in Vercel dashboard or vercel.json):

   • Build command: pnpm build:www (or specific app)
   • Output directory: apps/www/.next (or specific app)
   • Root directory: ./ (monorepo root)

3. Set environment variables in Vercel dashboard

4. Deploy

   vercel --prod

Environment-Specific Deployments

• Development: Local development servers
• Preview: Vercel preview deployments (pull requests)
• Production: Vercel production deployments (main branch)

API Documentation

Lightfast provides several APIs for agent execution and management:

• Agent API: Create, manage, and execute agents
• Workflow API: Orchestrate complex multi-step workflows
• Resource API: Manage sandboxes, browser sessions, and quotas
• Webhook API: Handle real-time events and notifications

Full API documentation is available at lightfast.ai/docs/api.

Contributing

We welcome contributions! Please see our Contributing Guide for details.

Development Setup

1. Fork and clone the repository
2. Install dependencies: pnpm install
3. Set up environment variables for the apps you're working on
4. Create a feature branch: git checkout -b feature/amazing-feature
5. Make your changes and test thoroughly
6. Run code quality checks: pnpm run lint && pnpm run typecheck
7. Submit a pull request

Code Style

• ESLint: Configured with @repo/eslint-config
• Prettier: Configured with @repo/prettier-config
• TypeScript: Strict mode enabled across all packages
• Conventional Commits: Use conventional commit messages

Community

• Website: lightfast.ai
• Documentation: lightfast.ai/docs
• GitHub: github.com/lightfastai/lightfast
• Discord: Join our community
• Twitter: @lightfastai

License

Lightfast uses a dual licensing approach:

• Open Source Components (Apache-2.0): Core runtime, CLI tools, and most applications are licensed under Apache License 2.0
• Commercial Components (FSL-1.1): The Cloud platform (apps/cloud) is licensed under Functional Source License 1.1

For Users: If you're using Lightfast's runtime (lightfast), CLI (@lightfastai/cli), or building applications with Lightfast, you're covered by Apache-2.0 - a permissive open source license.

For Cloud Platform: The Cloud platform restricts competitive commercial use but allows internal use, education, and research. It converts to Apache-2.0 after 2 years.

See LICENSING.md for complete details.

Support

If you find this project helpful, please consider:

• ⭐ Starring the repository
• 🐛 Reporting bugs and issues
• 💡 Suggesting new features
• 🤝 Contributing code or documentation

---

Built with ❤️ by the Lightfast team