Docs · Get started

Install KyoubeAI

Install KyoubeAI with one script and Docker: what you need, what install.sh does, claiming the instance, the first-run wizard and troubleshooting.

KyoubeAI 1.11.0 · · Source on GitHub (opens in a new tab)

What you need

  • Docker Desktop (macOS, Windows) or Docker Engine 24 or later with Docker Compose v2.17 or later (Linux), on amd64 or arm64, with at least 4 GB of memory for Docker. On Windows, run the commands below in WSL2.
  • git.
  • A model for your agents: an API key from Anthropic, OpenAI or OpenRouter, or a subscription you connect after installing (Harnesses).

Install

git clone https://github.com/KyoubeAI/KyoubeAI.git
cd KyoubeAI
./install.sh

The script:

  1. switches the checkout to the newest release;
  2. writes .env with generated secrets, asking one question, the address people will use (Enter keeps http://localhost:3100; if that port is taken it asks for another);
  3. downloads the release's image (about 3 GB);
  4. starts KyoubeAI and waits until it is healthy;
  5. asks you to open that address, create your account and claim the instance (the first account becomes the instance admin);
  6. prints a link that installs the Kyoube plugins: open it in the same browser and approve it;
  7. checks the result with kyoube doctor.

It is safe to run again at any point, and continues where it stopped. Re-running ./install.sh repairs the version you have; moving to another version is ./update.sh (on an install that has data, ./install.sh refuses to change the version, before it changes anything). Keep a copy of .env somewhere safe: restoring a backup onto a new machine needs its secrets.

After you claim the instance, the first-run wizard sets up your company and its first agent. On its Connect a model step an API key works straight away. With only a Claude or OpenAI subscription, choose Skip for now and connect the harness later from the Terminal page, which appears under the step's error: the agent is created anyway. Then install the agent harnesses you want (Harnesses).

Options: --url <address> and --port <n> answer the address question, --name <project> names the Compose project (for a second instance on one machine), --yes accepts every default and asks nothing (a taken port then stops the script, so add --port), --version <x.y.z> installs a particular release (1.1.0 or later), and --edge builds the current branch from source instead (CONTRIBUTING.md). People on other machines, TLS and reverse proxies are covered in docs/operations.md.

Troubleshooting

What you seeWhat to do
"Docker is installed but not reachable"Start Docker Desktop. On Linux, start the daemon and add your user to the docker group, then log in again.
The download fails, or says deniedCheck the network and run ./install.sh again; completed layers are kept. denied means this machine cannot read the image (docs/operations.md).
"did not become healthy"Read the log lines it printed. docker compose logs -f app shows more.
Sign-in fails with a 403 or an origin errorThe address in the browser must match KYOUBE_PUBLIC_URL in .env exactly. Behind a proxy, set TRUST_PROXY (docs/operations.md).
"blocks the browser claim"KYOUBE_DEPLOYMENT_EXPOSURE is public. Set it to private, run ./install.sh, claim, then switch back and run docker compose up -d.
kyoube doctor shows a plugin that is not =readyRead the plugin's log under Settings → Plugins → plugin → Logs, and docker compose logs -f app.