Show HN: Bubble Lab – Code-based agentic workflow platform (open-source)

1 hour ago 1

Open-source agentic workflow automation builder with full observability and exportability.

Bubble Lab is an AI-native workflow automation platform built for developers who need full control, transparency, and type safety. Unlike traditional workflow builders that lock you into proprietary JSON nodes, Bubble Lab compiles everything into clean, production-ready TypeScript that you can own, debug, and deploy anywhere.

Key Features:

Prompt to Workflow: Describe what you want in natural language, and Pearl (our AI Assistant) instantly generates working workflows using our composable bubble system (integrations, tools, and logic nodes)
Full Observability: Built-in execution tracing with detailed logs, token usage tracking, and performance metrics. Debug with complete visibility into every step
Import from n8n: Migrate existing workflows seamlessly. We automatically translate n8n JSON into our bubble architecture
Export as TypeScript: Own your workflows completely. Export clean, production-ready code that runs anywhere—integrate with your codebase, CI/CD pipelines, and existing infrastructure

1. Hosted Bubble Studio (Fastest Way)

The quickest way to get started with BubbleLab is through our hosted Bubble Studio:

Benefits:

No setup required - start building immediately
Visual flow builder with drag-and-drop interface
Export your flows to run on your own backend
Free AI credits

👉 Try Bubble Studio Now

In addition, you can try Bubble Studio in two command, locally (not suited for production):

# 1. Install dependencies pnpm install # 2. Start everything pnpm run dev

Get started with BubbleLab in seconds using our CLI tool:

This will scaffold a new BubbleLab project with:

Pre-configured TypeScript setup with core packages and run time installed
Sample templates (basic, reddit-scraper, etc.) you can choose
All necessary dependencies
Ready-to-run example workflows you fully control, customize

Next steps after creation:

cd my-agent npm install npm run dev

What You'll Get: Real-World Example

Let's look at what BubbleFlow code actually looks like using the reddit-scraper template:

The Flow (reddit-news-flow.ts) - Just ~50 lines of clean TypeScript:

export class RedditNewsFlow extends BubbleFlow<'webhook/http'> { async handle(payload: RedditNewsPayload) { const subreddit = payload.subreddit || 'worldnews'; const limit = payload.limit || 10; // Step 1: Scrape Reddit for posts const scrapeResult = await new RedditScrapeTool({ subreddit: subreddit, sort: 'hot', limit: limit, }).action(); const posts = scrapeResult.data.posts; // Step 2: AI analyzes and summarizes the posts const summaryResult = await new AIAgentBubble({ message: `Analyze these top ${posts.length} posts from r/${subreddit}: ${postsText} Provide: 1) Summary of top news, 2) Key themes, 3) Executive summary`, model: { model: 'google/gemini-2.5-flash' }, }).action(); return { subreddit, postsScraped: posts.length, summary: summaryResult.data?.response, status: 'success', }; } }

What happens when you run it:

$ npm run dev ✅ Reddit scraper executed successfully { "subreddit": "worldnews", "postsScraped": 10, "summary": "### Top 5 News Items:\n1. China Halts US Soybean Imports...\n2. Zelensky Firm on Ukraine's EU Membership...\n3. Hamas Demands Release of Oct 7 Attackers...\n[full AI-generated summary]", "timestamp": "2025-10-07T21:35:19.882Z", "status": "success" } Execution Summary: Total Duration: 13.8s Bubbles Executed: 3 (RedditScrapeTool → AIAgentBubble → Return) Token Usage: 1,524 tokens (835 input, 689 output) Memory Peak: 139.8 MB

What's happening under the hood:

RedditScrapeTool scrapes 10 hot posts from r/worldnews
AIAgentBubble (using Google Gemini) analyzes the posts
Returns structured JSON with summary, themes, and metadata
Detailed execution stats show performance and token usage

Key Features:

Type-safe - Full TypeScript support with proper interfaces
Simple - Just chain "Bubbles" (tools/nodes) together with .action()
Observable - Built-in logging shows exactly what's executing
Production-ready - Error handling, metrics, and performance tracking included

Learn how to use each bubble node and build powerful workflows:

👉 Visit BubbleLab Documentation

The documentation includes:

Detailed guides for each node type
Workflow building tutorials
API references
Best practices and examples

BubbleLab is built on a modular architecture with the following core packages:

@bubblelab/bubble-core - Core AI workflow engine
@bubblelab/bubble-runtime - Runtime execution environment
@bubblelab/shared-schemas - Common type definitions and schemas
@bubblelab/ts-scope-manager - TypeScript scope analysis utilities
create-bubblelab-app - Quick start with bubble lab runtime

bubble-studio - Visual workflow builder (React + Vite)
bubblelab-api - Backend API for flow storage and execution (Bun + Hono)

Bun - Required for running the backend API server
pnpm - Package manager for monorepo management
Node.js - v18 or higher

Run Bubble Studio locally in 2 commands:

# 1. Install dependencies pnpm install # 2. Start everything pnpm run dev

That's it! The setup script automatically:

✅ Creates .env files from examples
✅ Configures dev mode (no auth required)
✅ Sets up SQLite database
✅ Builds core packages
✅ Starts both frontend and backend

Open http://localhost:3000 and start building workflows!

Frontend: http://localhost:3000 (Bubble Studio)
Backend: http://localhost:3001 (API Server)

Development Mode (Default)

By default, the app runs in development mode with:

🔓 No authentication required - Uses mock user [email protected]
💾 SQLite database - Auto-created at apps/bubblelab-api/dev.db
🎯 Auto-seeded dev user - Backend creates the user automatically

Production Mode (Optional)

To run with real authentication:

Get your Clerk keys at clerk.com
Update .env files:

Frontend (apps/bubble-studio/.env):

VITE_CLERK_PUBLISHABLE_KEY=pk_test_... VITE_DISABLE_AUTH=false

Backend (apps/bubblelab-api/.env):

BUBBLE_ENV=prod CLERK_SECRET_KEY=sk_test_...

Restart with pnpm run dev

The setup script creates these files with sensible defaults:

apps/bubble-studio/.env:

VITE_API_URL=http://localhost:3001 VITE_CLERK_PUBLISHABLE_KEY= VITE_DISABLE_AUTH=true # Dev mode: no auth needed

apps/bubblelab-api/.env:

BUBBLE_ENV=dev # Creates mock user automatically DATABASE_URL=file:./dev.db # SQLite

The following API keys are optional but enable specific features. Add them to apps/bubblelab-api/.env:

# AI Model Providers (both required for AI-powered flow generation) OPENAI_API_KEY= # OpenAI API key for GPT models GOOGLE_API_KEY= # Google AI API key for Gemini models (required for flow generation) OPENROUTER_API_KEY= # OpenRouter API key for multi-model support (required for flow generation) # Communication & Storage RESEND_API_KEY= # Resend API key for email notifications FIRE_CRAWL_API_KEY= # FireCrawl API key for web scraping # Authentication (optional, only needed for production mode) CLERK_SECRET_KEY_BUBBLELAB= # Clerk secret key for authentication # OAuth (optional) GOOGLE_OAUTH_CLIENT_ID= # Google OAuth client ID GOOGLE_OAUTH_CLIENT_SECRET= # Google OAuth client secret # Cloud Storage (optional) CLOUDFLARE_R2_ACCESS_KEY= # Cloudflare R2 access key CLOUDFLARE_R2_SECRET_KEY= # Cloudflare R2 secret key CLOUDFLARE_R2_ACCOUNT_ID= # Cloudflare R2 account ID # Other PYTHON_PATH= # Custom Python path (optional) CREDENTIAL_ENCRYPTION_KEY=8VfrrosUTORJghTDpdTKG7pvfD721ChyFt97m3Art1Y= # Encryption key for storing user credentials BUBBLE_CONNECTING_STRING_URL= # Database connection string (optional, defaults to SQLite)

Note: AI-powered flow generation requires both GOOGLE_API_KEY and OPENROUTER_API_KEY to be configured. Without these, you can still use Bubble Studio to manually build workflows, but the AI assistant features will be unavailable.

# Run only the setup script pnpm run setup:env # Build for production pnpm run build # Run tests pnpm test # Lint code pnpm lint

🤝 Contributing & Self-Hosting Bubble Studio

Documentation for contributing to BubbleLab and self-hosting the platform is coming soon!

In the meantime, feel free to:

Explore the source code
Open issues for bugs or feature requests about Bubble Studio or add more bubbles
Submit pull requests
Join our Discord community for discussions and support

Apache 2.0

Read Entire Article