bbaas-api

Browser API Layer (BBAAS)

This includes a browser-management API layer that sits in front of my existing CDP manager service.

• User registration/login with secure session cookies
• Dashboard for application registration and API key management
• Scoped API keys (READ, WRITE, DELETE) for browser lifecycle APIs
• Running/completed browser session tracking per user/application
• Go SDK wrapper (/sdk/go/bbaas) for API consumption from Go projects
• Service boundaries/interfaces to support future extension (dashboards, admin tooling, live session views)

Environment Variables

• PORT (default 8080)
• CDP_MANAGER_BASE_URL (default http://127.0.0.1:8081)
• CDP_PUBLIC_BASE_URL (default empty). When empty, API returns manager-provided URLs (local default usually 127.0.0.1:<port>). When set, API rewrites CDP endpoints to your public host and encodes the browser port into the URL path (example: wss://bbaas-manager.b8z.me/50100/devtools/browser/...).
• DATABASE_URL (default postgres://postgres:postgres@127.0.0.1:5432/bbaas?sslmode=disable)

Docker Compose

Local (build API image locally, CDP manager on host network for dynamic ports):

docker compose up --build

Production (prebuilt images, public CDP gateway URL rewriting enabled by default):

docker compose -f compose.prod.yml up -d

Important networking behavior:

• cdp-manager runs in network_mode: host and binds CDP ports to 127.0.0.1 by default.
• cdp-manager allocates CDP ports from a dedicated range (default 20000-29999) so reverse proxies can forward that range without consuming OS ephemeral client ports.
• This allows dynamic browser ports to be reachable by local processes and private reverse proxies, without publicly exposing the manager directly.
• API URL rewriting is controlled by CDP_PUBLIC_BASE_URL:
  • local default: empty (returns raw manager URL, typically http://127.0.0.1:<port>)
  • prod default: https://bbaas-manager.b8z.me (returns path-rewritten CDP URLs such as wss://bbaas-manager.b8z.me/50100/devtools/browser/...)

API Endpoints

Base path: /api/v1

• GET /health (public): health check
• POST /browsers (auth): spawn browser
• GET /browsers (auth): list browsers for API key's application
• GET /browsers/:id (auth): fetch browser details
• POST /browsers/:id/keepalive (auth): extend idle timeout
• DELETE /browsers/:id (auth): close browser

Authentication:

• Authorization: Bearer <api_token> or X-API-Key: <api_token>

Web UI flows:

• GET /register, POST /register
• GET /login, POST /login, POST /logout
• GET /dashboard
• POST /dashboard/applications
• POST /dashboard/applications/:applicationId/api-keys
• POST /dashboard/applications/:applicationId/api-keys/:keyId/revoke

Go SDK Quickstart

Import path:

import "github.com/brian-nunez/bbaas-api/sdk/go/bbaas"

Example:

ctx := context.Background()

client, _ := bbaas.NewClient("http://localhost:8080", bbaas.WithAPIToken("bka_..."))
spawned, _ := client.SpawnBrowser(ctx, bbaas.SpawnBrowserRequest{})
fmt.Println(spawned.Browser.CDPURL)

Features

• Fast startup, zero config needed
• Opinionated folder structure with /cmd and /internal
• Templ components using templ
• Utility-first styling with TailwindCSS
• Templ UI support preconfigured (All components are installed)
• Clean routing with Echo (My favorite Go web framework)
• Centralized error handling
• Graceful shutdown
• Makefile-driven dev workflow

Tool Links

• Echo: A high-performance, minimalist web framework for Go.
• Templ: A Go HTML templating engine that allows you to build reusable components.
• TailwindCSS: A utility-first CSS framework for rapid UI development.
• Templ UI: A collection of prebuilt components for Templ, making it easy to build beautiful UIs.
• Air: A live reloading tool for Go applications, making development faster and smoother.

Project Structure

├── cmd/                # Entrypoint (main.go)
├── internal/           # Application logic
│   ├── handlers/       # HTTP handlers
│   │   ├── errors/     # Centralized error response logic
│   │   └── v1/         # Versioned routing
│   └── httpserver/     # Server wiring & middleware
├── .templui.json       # Templ UI config
├── Makefile            # Dev commands

Get Started

1. Clone the repo

git clone https://github.com/brian-nunez/bbaas-api.git
cd bbaas-api

2. Install dependencies

• Go 1.22+
• templ
• tailwindcss
• air (for live reloading)

3. Run in dev mode

make dev

Reach out if you have questions or just want to chat!

• GitHub
• LinkedIn