OpenKBS

An open-source CLI that lets you build and deploy full-stack applications using Claude Code as your IDE. Write code locally, deploy functions, static sites, and databases — either to a local environment (LocalStack + PostgreSQL) or to the OpenKBS cloud (AWS Lambda, S3, CloudFront, Neon PostgreSQL).

Same code, same commands, two targets.

Quick Start

Prerequisites

• Node.js v20+
• Docker
• A LocalStack auth token (free tier works)

1. Clone and install

git clone https://github.com/open-kbs/openkbs.git
cd openkbs
npm install

2. Configure LocalStack

cp .env.example .env

Edit .env and add your LocalStack auth token:

LOCALSTACK_AUTH_TOKEN=your-token-here

3. Start infrastructure

docker compose up -d

This starts:

• LocalStack (port 4566) — local AWS services (Lambda, S3, CloudWatch, EventBridge)
• PostgreSQL (port 5432) — local database

4. Launch the UI

npx tsx src/index.ts ui

Your browser opens http://localhost:3000 with the development UI.

The screenshot above shows example apps that can be built with OpenKBS. You start with a blank slate — create your first app from the UI.

5. Build your app

From the UI:

1. Create App — enter a name, scaffolds a new project with React + Vite
2. Install Dependencies — installs npm packages
3. Start Building — launches Vite dev server with hot reload, opens your app in a new tab
4. Deploy Locally — deploys functions and site to LocalStack

Edit your code — the browser updates instantly via hot reload.

Project Structure

When you create an app, it generates:

my-app/
├── src/                  # React source code (edit here)
│   ├── index.html
│   ├── main.jsx
│   └── App.jsx
├── build/                # Vite build output (auto-generated, deployed)
├── functions/            # Lambda functions (each folder = one endpoint)
│   └── api/
│       ├── index.mjs     # Handler: export const handler = async (event) => { ... }
│       └── package.json
├── openkbs.json          # Project config
├── vite.config.js        # Vite + API proxy config
└── package.json

CLI Commands

Functions

openkbs fn create <name>          # Scaffold a new function
openkbs fn deploy <name>          # Deploy a function
openkbs fn list                   # List deployed functions
openkbs fn invoke <name> -d '{}'  # Test a function
openkbs fn destroy <name>         # Delete a function
openkbs fn logs <name>            # View function logs

Site

openkbs site deploy               # Deploy build/ to S3

Storage

openkbs storage ls [prefix]       # List objects
openkbs storage upload <file>     # Upload a file
openkbs storage download <key>    # Download a file
openkbs storage rm <keys...>      # Delete objects

Database

openkbs postgres info             # Show connection details
openkbs postgres connection       # Output connection string

Deployment

openkbs deploy                    # Deploy all services from openkbs.json

UI

openkbs ui                        # Start the local development UI
openkbs ui -p 8080                # Use a custom port
openkbs ui --no-open              # Don't auto-open browser

Local vs Cloud

The target field in openkbs.json controls where deployments go:

	Local	Cloud
Functions	LocalStack Lambda	AWS Lambda
Storage	LocalStack S3	AWS S3 + CloudFront
Database	Docker PostgreSQL	Neon PostgreSQL
Target	"target": "local"	"target": "cloud"

Apps created from the UI default to "target": "local". To deploy to cloud:

openkbs login
# Change "target" to "cloud" in openkbs.json
openkbs deploy

Environment Variables

Lambda functions automatically receive:

Variable	Description
DATABASE_URL	PostgreSQL connection string
STORAGE_BUCKET	S3 bucket name
OPENKBS_PROJECT_ID	Project identifier

Development

To work on the CLI itself:

npm install
npm run dev -- <command>    # Run CLI in dev mode
npm run build               # Build ESM bundle

License

MIT