Open-source application platform for your infrastructure.
Cloud bundles a set of apps that cover the common operational needs of an organisation — accounts, settings, observability, notifications, files, notebooks, calendars, OAuth — and is built around the custom apps you write yourself. Custom apps get the same session, UI kit, search hooks, and admin pages as the apps in the box.
- Built around your own apps. Adding an app is one config file plus a Dockerfile. The platform picks it up at runtime.
- Per-app deployment. Every feature is a separate Bun container, started, updated and scaled on its own.
- Horizontal scaling. Apps are stateless and discovered through a NATS-backed registry —
docker compose up --scale notebooks=3and the gateway routes across all instances. - Bun + Hono + SolidJS + Postgres + NATS + Redis. End-to-end TypeScript.
- Admin surface for everything. Per-app admin pages, settings managed in the UI, requests route-traced through the gateway.
| Group | Apps |
|---|---|
| Platform | core — auth, profile, settings, legal pages, transactional email • gateway — routing and app registry |
| Identity & access | accounts — users + groups, FreeIPA and local • oauth — OAuth2 issuer • proxy-auth — Traefik forward-auth • ipa-hosts — FreeIPA host management |
| Operations | gateway-ops — app registry, routes, logs, telemetry, webhooks, notifications |
| Productivity | assistant — general-purpose AI chat • mail — collaborative email • notebooks — collaborative notes (Yjs) • spaces — kanban / list / calendar with iCal • files — shared storage • contacts — directory views |
| Content & misc | faq • venue • weather • quotes • tools |
| Development | api-docs — Scalar UI aggregating every running app's OpenAPI spec • Fibel UI catalog — component showcase |
Build an independent application with @k2b/cloud from npm. Your application
owns its repository and image and connects to the shared Cloud deployment.
Follow Create the first application for the package setup, application declaration, and first verified endpoint. Then use Standalone development to connect it to the gateway and shared services.
HTTPS
│
▼
┌───────────────┐
│ Gateway │ routes /app/<id>/* by URL prefix
└───┬───┬───┬───┘
│ │ │
┌───────────┘ │ └───────────┐
▼ ▼ ▼
┌─────────┐ ┌─────────┐ ┌─────────┐
│ core │ │ files │ │ ... │ each app:
│ │ │ │ │ │ Bun + Hono + SolidJS SSR
└────┬────┘ └────┬────┘ └────┬────┘ one container per app
└───────────────┴────────────────┘
│
┌───────────────┼───────────────┐
▼ ▼ ▼
┌─────────┐ ┌─────────┐ ┌──────────┐
│ NATS │ │ Valkey │ │ Postgres │
│JetStream│ │ │ │ │
└─────────┘ └─────────┘ └──────────┘
registry, jobs, caches, per-app
schedules, live rate limits schemas
Each app boots, registers itself with the gateway through NATS, and starts handling requests at its declared URL prefix. The gateway holds no per-app code — adding an app touches only that app's own files and the compose file.
Apps share Postgres (each owns its own schema), NATS JetStream (registry, jobs, schedules and live events), and Redis/Valkey (rate limits, caches and short-lived authentication flows). Browser sessions use JWTs. Per-app traffic, latency and route-trace data live in the gateway and are visible in the admin UI.
bun install --frozen-lockfile
bun run dev # infrastructure + core 6-container set
open http://localhost:3000Development requires Bun 1.x, Docker, and Docker Compose v2. The base Docker development stack gets its local database, Redis, app-secret, and admin-token values from compose.dev.yml; no .env file is required for that base stack. .env.example is a per-process reference for running directly on the host or building a custom local setup. Production uses .env.prod.example as its companion template.
Development Compose supplies a local-only CLOUD_OAUTH_BROKER_SECRET exclusively to Core and OAuth; no OAuth credential provisioning is needed. Production requires your own independently generated broker secret. Mail incoming automations still need a provisioned CLOUD_MAIL_APP_CREDENTIAL, passed only to Mail. See Runtime configuration for secret ownership and private service origins.
Dev admin login: open /auth/login?method=admin and paste dev-admin into the token field (the ADMIN_LOGIN_TOKEN baked into app-core).
| Command | What it does |
|---|---|
bun run dev |
Start infrastructure and the core 6 services |
bun run dev:full |
Start infrastructure, core, and all 17 extras |
bun run dev:infra |
Start Postgres, Valkey, three-node NATS JetStream, Geo, Filegate, and Gotenberg |
bun run dev:infra:down |
Stop the development infrastructure |
bun run dev:start <app...> |
Add one or more extra apps to the running stack |
bun run dev:stop <app...> |
Stop one or more apps |
bun run dev:restart <app...> |
Reload mounted source without rebuilding images |
bun run dev:restart --running |
Reload all currently running app services |
bun run dev:rebuild <app...> |
Rebuild image + restart (parallel for multiple) |
bun run dev:logs <app> |
Follow one app's logs |
bun run dev:status |
Plain-text inventory of all apps (state, uptime, image age) |
bun run dev:help |
Catalog of every dev command |
bun run dev:cld -- <args> |
Run the current checkout's CLI against the local development server |
bun run dev:down |
Tear down the app stack while keeping infrastructure running |
bun run typecheck |
skills + boundaries + cycles + biome + tsc |
After a fresh clone, install the workspace, start the containerized documentation, and install its current developer skill. Docker with Compose v2 is required on macOS and Linux.
bun install --frozen-lockfile
bun run dev:fibel
bunx skills add http://localhost:4187bun run dev:fibel returns after the Fibel health endpoint is ready. Use
bun run dev:fibel:logs to follow its output and bun run dev:fibel:down to
stop only the documentation service.
Connect the same local documentation as an MCP server. Use the command for your agent:
# Codex
codex mcp add cloud-dev-mcp --url http://localhost:4187/_fibel/mcp
# Claude Code
claude mcp add --transport http cloud-dev-mcp http://localhost:4187/_fibel/mcpFor another code agent, configure a streamable HTTP MCP server named
cloud-dev-mcp with the same URL and load AGENTS.md as repository guidance.
The Agents dialog in the Fibel footer shows additional client-specific
setup.
If port 4187 is occupied, start with FIBEL_PORT=4199 bun run dev:fibel and
replace 4187 in the skill and MCP URLs. Restart the agent session after adding
the connection. The agent should see the Apps, Docs, and UI collections through
list_collections, search_docs, and read_doc.
Repository-wide agent instructions live in AGENTS.md. Claude
Code loads the same instructions through CLAUDE.md. The
canonical contribution rules are in
Document Cloud core changes.
Install the CLI operator skill directly from the repository:
bunx skills add github.com/k2b-dev/cloudcloud-dev— public application contract for standalone and built-in Cloud apps; repository maintainers also followAGENTS.mdcloud-cli— using a Cloud instance from the terminal withcld
GNU Affero General Public License v3.0 or later — see LICENSE.
Commercial use, hosting, modification, and redistribution are permitted under the AGPL. If you modify Cloud and let users interact with it over a network, you must provide those users access to the corresponding source code under the same license.
Separate commercial licenses for proprietary, reseller, managed-service, white-label, or embedded product use are available by contacting the maintainer.