Cubebot

A Kubernetes-native home for persistent agents, shared rooms, memories, and skills.

Status: a minimal text-chat MVP runs locally: sign-in, agent management, an encrypted OpenAI connection and one permanent conversation per agent, served by the native Rust runtime. A terminal is implemented but disabled by default. See STATUS for everything not yet qualified.

With Docker (Compose 2.23 or later) and just:

just up      # builds and starts everything, then waits until it answers
just admin   # once: creates the administrator, prompting for a password

Open http://localhost:3000, sign in, and add an OpenAI connection in the console. just down stops everything and keeps your data in Docker volumes; docker compose down -v deletes it. The first just up writes .env with a random database password; set CUBEBOT_PORT there to use another port.

What runs depends on the machine:

• macOS, Windows, or Linux without KVM: PostgreSQL, the orchestrator and the console. You can sign in, manage agents and connections, and browse, but an agent cannot wake, because every agent runs in a KVM guest that needs x86_64 Linux.
• x86_64 Linux with /dev/kvm: the same, plus agents. The first run also builds the guest kernel and root image (make, gcc, flex, bison, bc and the libelf headers), a sandbox image, and a local control CA. The orchestrator then starts each agent as a Docker container on this host, which needs the Docker socket and is therefore root on this machine. Set CUBEBOT_AGENTS=0 in .env to leave agents off, or CUBEBOT_AGENTS=1 to fail instead of falling back.

just up is for running Cubebot on one machine. It is not a production deployment.

Use Rust through rustup, Bun 1.4.0, Node 24.18.0, uv 0.11.26, and just 1.55.1. A C/C++ compiler and linker are needed to build the complexity tool. Rust 1.96.0 and Python 3.14.6 are selected by repository files; Python runs development checks only.

just bootstrap
just check
just smoke

bootstrap installs locked dependencies and pins Mozilla's complexity analyzer into .tools/. check runs formatting, linting, the complexity gate, tests, builds and TypeScript checking. smoke starts the built services, checks them and stops them.

For development, use two terminals:

just dev-api

just dev-web

Open http://localhost:3000. Vite forwards /api to the orchestrator at 127.0.0.1:8080. The orchestrator reads exported CUBEBOT_BIND_ADDR and RUST_LOG; it does not load .env itself.

cp .env.example .env   # choose POSTGRES_PASSWORD
just db-up
export CUBEBOT_DATABASE_URL=...   # your local connection string
CUBEBOT_BOOTSTRAP_LOGIN=admin CUBEBOT_BOOTSTRAP_PASSWORD=... \
  cargo run --locked -p cubebot-orchestrator --bin cubebot-admin -- bootstrap
cargo run --locked -p cubebot-orchestrator

just integration runs the database, HTTP and OIDC tests against a disposable PostgreSQL container. The operator and API reference covers identity, OIDC, agents, lifecycle controller configuration, runtime recovery and container builds.

See repository layout for the module map and dependency rules.

• Manifesto and architecture
• Accepted ADRs
• Status
• Software specification and qualification plan
• Contributing

Licensed under Apache-2.0.