Before you start
- Linux or macOS with Docker and Compose 2.23 or later, plus bash and curl.
- For a virtual machine per agent: x86_64 Linux with
/dev/kvmand/dev/net/tun. Without them, agents run as containers. - A key from OpenAI, Anthropic, Google Gemini, xAI or OpenRouter, or a ChatGPT Plus or Pro plan.
Run the installer
curl -fsSL https://cubebot.io/install.sh | bashIt checks Docker, finds the latest release and asks four questions. Move with the arrows, j/k or a digit, then press Enter.
The four questions
| Question | Choices | Variable |
|---|---|---|
| Where agents run | kvm, a virtual machine each (default on x86_64 Linux with KVM); container, works everywhere; off, console only | CUBEBOT_RUNTIME |
| How the console is reached | This machine at http://localhost:3000, or a public domain on ports 80 and 443 with a certificate obtained for you | CUBEBOT_ACCESS, CUBEBOT_DOMAIN |
| Install directory | ~/.cubebot by default | CUBEBOT_HOME |
| Administrator | Create it now in the terminal, or let the first account made at the console become it | CUBEBOT_ADMIN |
A question whose variable is set is not asked. CUBEBOT_YES=1, or no terminal at all, takes every default; CUBEBOT_VERSIONpicks a release and CUBEBOT_PORT changes the local port.
curl -fsSL https://cubebot.io/install.sh | \
CUBEBOT_RUNTIME=container CUBEBOT_ADMIN=console CUBEBOT_YES=1 bashWith a public domain, the domain must already point at this machine, and creating the administrator now is preselected, since otherwise whoever opens the console first claims it.
Your first agent
- Open the address the installer printed and sign in as the administrator.
- Open the gear beside your name, then AI providers. Paste a key and pick a model, or sign in with your ChatGPT plan.
- Press + and choose New agent. Give it a name, instructions, a voice and a face. It starts right away and sleeps while it has no work.
- Say hello in its conversation. Open Desktop to watch its computer, or Call to talk.
- Connect accounts under Platform › Connections and they are offered to every agent by default.
The cubebot command
The installer leaves a cubebot script in the install directory.
cubebot up | Start everything and wait until it answers |
cubebot down | Stop everything; your data stays in Docker volumes |
cubebot update [version] | Move to the latest release, or the one named |
cubebot logs [-f] | Follow the logs |
cubebot admin [login] | Create the administrator from the terminal while nobody has |
cubebot uninstall [--yes] | Remove every agent, workspace, volume and image this installation created |
Running the installer again updates the installation in place and never replaces its .env.
On Kubernetes
The chart installs one installation into one namespace: the orchestrator, the console, PostgreSQL (bundled, or yours throughexternalDatabase), the shared-files volume, network policies and, for kvm, a device plugin. Bring an ingress controller or a Gateway with TLS; the chart does not install one.
publicOrigin: https://cubebot.example.com
admin: { login: admin, existingSecret: cubebot-admin }
ingress: { className: traefik, host: cubebot.example.com, tlsSecret: cubebot-tls }
sandbox:
dns: [10.96.0.10] # kubectl -n kube-system get service kube-dnskubectl create namespace cubebot
kubectl label namespace cubebot pod-security.kubernetes.io/enforce=baseline # privileged for kvm
kubectl -n cubebot create secret generic cubebot-admin --from-literal=password="$(openssl rand -base64 24)"
helm install cubebot oci://ghcr.io/vicotrbb/charts/cubebot --namespace cubebot --values my-values.yaml- Both volumes use
ReadWriteOncePod, so the storage driver must support it. - Network policy is only as good as your network plugin: plain flannel ignores it; EKS and GKE enforce it once it is turned on.
- Agents reach self-hosted servers on private addresses only when you list them under
sandbox.networkPolicy.privateDestinations. - Back up the database with
pg_dump, together with the shared-files volume and the credentials Secret.