Built on Bun

One Container.
Everything You Need.

Luca is a runtime container framework that gives your server and browser applications every dependency they need — zero external packages required.

Get Started Explore Features
luca — interactive
// everything is on the container
const container = await createContainer()
 
// features, clients, servers — all built in
const fs = container.feature('fs')
const api = container.client('rest')
const app = container.server('express')
 
// that's it. start building.
await app.start()
0
External Dependencies
20+
Built-in Helpers
2
Runtimes (Node + Browser)
1
Container for Everything
Features

Batteries Included.
All of Them.

Every feature is a first-class citizen of the container — observable state, event-driven, introspectable. No glue code, no boilerplate.

File System

Read, write, watch, and scan your project files. Intelligent file management with fileManager for full project awareness.

Process & VM

Execute shell commands with proc.exec(). Run isolated code in the VM with full module loading and sandboxing.

Networking

Built-in HTTP fetch, port management, and network utilities. Check availability, find open ports, make requests.

Git Integration

Full git awareness — branch info, status, diff, log. Your container knows your repo as well as you do.

REST & WebSocket

Full-featured HTTP client and real-time WebSocket support. Build APIs and consume them from the same container.

Observable State

Every helper has reactive, observable state. Subscribe to changes, bind UI, react to events across the entire system.

Introspection

Every helper self-documents. Auto-generated docs, usage examples, method signatures. Explore your system at runtime.

Express & Endpoints

File-based endpoint discovery, Express server with OpenAPI generation, static file serving, rate limiting — out of the box.

Cross-Runtime

Same API on server and browser. Node container for backends, Browser container for frontends. Shared primitives everywhere.

Philosophy

Docker for Your Runtime

Like Docker gives you a complete, reproducible environment for deployment — Luca gives you a complete, consistent runtime for development.

01

Zero Dependencies

The container provides everything. File system, networking, git, servers, clients, process execution — no npm install needed.

02

Compose, Don't Configure

Features, clients, and servers are composable building blocks. Request what you need from the container, wire it together, ship it.

03

Know Thyself

Every component is introspectable. Auto-generated documentation, observable state, full event system. Your app explains itself.

Architecture

Everything Lives
in the Container

A singleton per process. Event bus, state machine, dependency injector, and registry — all in one coherent object.

container
Registries
Registry
features
fs, git, proc, vm, grep...
Registry
clients
rest, websocket
Registry
servers
express, websocket
Registry
commands
file-based discovery
Registry
endpoints
HTTP handlers
primitives
Core
Event Bus
emit, on, once
Core
State Machine
observable, reactive
Core
Paths
resolve, join, cwd
Core
Introspection
self-documenting
Developer Experience

Write Less. Build More.

Clean, expressive APIs that feel natural. Everything you need is one method call away.

// spin up an Express server with endpoints
const app = container.server('express')
 
// endpoints are auto-discovered from your files
await app.mountEndpoints()
 
// WebSocket server alongside HTTP
const ws = container.server('websocket')
ws.on('connection', socket => {
socket.send('welcome to luca')
})
 
await app.start() // that's it
const fs = container.feature('fs')
 
// read any file
const data = await fs.readFile('config.json')
 
// search content across your project
const grep = container.feature('grep')
const results = await grep.run('TODO', {
include: ['**/*.ts']
})
 
// intelligent project-wide file awareness
const fm = container.feature('fileManager')
const files = fm.fileIds // every file, indexed
// scripts have the full container at their fingertips
const git = container.feature('git')
const proc = container.feature('proc')
 
// check git status
console.log(git.branch) // "main"
console.log(git.status) // { modified: [...] }
 
// run shell commands
const { stdout } = await proc.exec('ls -la')
 
// isolated VM execution
const vm = container.feature('vm')
const result = await vm.run('return 2 + 2')
// endpoints/hello.ts — file-based routing
export default {
method: 'GET',
path: '/hello/:name',
 
async handler(req, res, container) {
// full container access in every handler
const fs = container.feature('fs')
const template = await fs.readFile('greeting.html')
 
res.json({ hello: req.params.name })
}
}
Command Line

A CLI That
Understands Your Code

Run code, generate docs, serve apps, explore registries — all from your terminal.

luca eval "container.features.available"
Run arbitrary JavaScript against the live container. Inspect state, test features, explore registries interactively.
luca describe fs
Auto-generated documentation for any feature, client, or server. Methods, options, state, events — all introspected.
luca serve
Start an Express server that auto-discovers your endpoints/ folder. OpenAPI docs, static files, and hot reload included.
luca describe servers
Explore entire registries at once. See every available server, client, or feature with their full documentation.
luca console
Drop into an interactive REPL with the full container in scope. Every feature, client, and server at your fingertips.
luca run scripts/deploy.ts
Execute scripts with the container pre-loaded. No imports needed — your script gets the full runtime automatically.

Start Building with Luca

One container. Every feature. Zero dependencies.

$ bun add luca click to copy
View on GitHub Explore Docs