Install KyoubeAI

These steps take you from nothing to a running instance with its first agent. You can run the published image, which Docker downloads from GHCR, or build the image from source on your own machine. The published image is the tested release, built for amd64 and arm64, and it is the right choice unless you want to run your own changes or main between releases. Where the steps differ, both ways are shown.

What you need

• Docker Engine 24 or later with Docker Compose v2 (Docker Desktop includes both), on amd64 or arm64.
• At least 4 GB of RAM.
• git and openssl.
• Access to a model: an API key from Anthropic, OpenAI or OpenRouter, or a subscription you sign in to from the Terminal page in step 8.

Step 1. Download KyoubeAI

Published image: clone the release you will run.

git clone --branch v1.0.0 https://github.com/jknigel/KyoubeAI.git
cd KyoubeAI

Git reports a "detached HEAD" here. That is expected, because the checkout is pinned to the release tag.

From source: clone main.

git clone https://github.com/jknigel/KyoubeAI.git
cd KyoubeAI

Step 2. Create your settings file

.env holds your settings and secrets. Create it from the template and fill the three required secrets with random values:

cp .env.example .env
for key in BETTER_AUTH_SECRET POSTGRES_PASSWORD KYOUBE_DB_PASSWORD; do
  sed -i.bak "s/^$key=\$/$key=$(openssl rand -hex 32)/" .env
done
rm .env.bak

The loop only fills empty values, so running it twice is safe. To do it by hand instead, run openssl rand -hex 32 three times and paste one result after each of the three keys. The two database passwords must contain only letters and digits, which is what that command produces.

Keep a copy of .env somewhere safe. Restoring a backup onto a new machine needs the same BETTER_AUTH_SECRET and database passwords.

Two optional settings are worth adding while the file is open:

• A model provider key (ANTHROPIC_API_KEY, OPENAI_API_KEY or OPENROUTER_API_KEY), so agents can work as soon as KyoubeAI starts.
• KYOUBE_PUBLIC_URL, if people will open KyoubeAI from other machines (Reaching KyoubeAI from other machines).

Step 3. Point .env at the published image

Skip this step if you build from source.

Near the bottom of .env, under "Optional: prebuilt image", uncomment the two lines so they read:

KYOUBE_IMAGE=ghcr.io/jknigel/kyoubeai
KYOUBE_VERSION=1.0.0

This command does the same:

sed -i.bak -e 's/^# KYOUBE_IMAGE=/KYOUBE_IMAGE=/' -e 's/^# KYOUBE_VERSION=/KYOUBE_VERSION=/' .env && rm .env.bak

The version must match the tag you cloned.

Step 4. Start KyoubeAI

Published image: download the image, then start.

docker compose pull
docker compose up -d

Run the pull on its own and read how it ends. If it reports denied, stop there: the image is not public, or this machine has to log in to GHCR first (the published image on GHCR). A docker compose up -d after a failed pull quietly builds the image from source instead.

From source: build and start in one go.

docker compose up -d --build

Then watch the services come up:

docker compose ps

Wait until app reads healthy. The first start runs the database migrations, and the health check allows up to three minutes for them.

Step 5. Sign up and claim the instance

Open http://localhost:3100 (or the KYOUBE_PUBLIC_URL you set), sign up, and claim the instance. Whoever claims it becomes the instance admin.

The first-run wizard then sets up your company and its first agent. On its Connect a model step, an API key works straight away. A Claude or OpenAI subscription cannot be signed in from the wizard on a KyoubeAI server, so if you have no key, choose Skip for now and connect the harness later from the Terminal page. The agent is created anyway, and it starts working once its harness is connected in step 8.

The browser claim only works while KYOUBE_DEPLOYMENT_EXPOSURE=private, which is the default. For an instance on the internet, claim it first and switch to public afterwards.

Step 6. Install the Kyoube plugins

Run this once:

docker compose exec app kyoube setup

It prints a link and asks you to approve the command-line login as an instance admin. Open the link in the browser where you are signed in and approve it before it expires. From then on the plugins install and upgrade themselves every time KyoubeAI starts.

Step 7. Check the installation

docker compose exec app kyoube doctor

Every check should pass, and each kyoube.* plugin should read =ready. The harness credential lines at the end only report what is signed in, so they say "not found" until the next step.

Step 8. Connect the agent harnesses

Agents work through Claude Code, pi or Hermes Agent, and each harness needs access to a model. Use either way, or both:

• API keys: put ANTHROPIC_API_KEY, OPENAI_API_KEY or OPENROUTER_API_KEY in .env, then run docker compose up -d to apply them.
• Signing in from the browser: open the Workspace page at the bottom of the sidebar, then Terminal, and run claude login for Claude Code, pi for pi, or hermes setup for Hermes Agent. The credentials are stored on the kyoubeai-home volume, so they survive restarts and updates.

Run kyoube doctor again to see the harnesses you connected.

To let an agent work with company data, enable the Kyoube Data and Kyoube Apps skills on its Skills tab and give it an access level under Company Settings → Data access. Data explains the levels.

Reaching KyoubeAI from other machines

KyoubeAI listens on every network interface, so other machines can already reach it on port 3100. Tell it the address people will use:

1. Set KYOUBE_PUBLIC_URL in .env to the exact address people type, such as http://192.168.1.10:3100 or https://kyoube.example.com. Sign-in and the kyoube setup link are built from it, so a wrong value sends people to the wrong host.
2. Behind a reverse proxy or tunnel on the same Docker network (Caddy, Traefik, nginx or cloudflared), also set TRUST_PROXY=uniquelocal.
3. For an instance on the internet, put TLS in front and set KYOUBE_DEPLOYMENT_EXPOSURE=public. kyoube doctor fails a public instance whose address does not start with https://.
4. Apply the changes with docker compose up -d.

To use a port other than 3100, set KYOUBE_PORT and put the same port in KYOUBE_PUBLIC_URL. On a localhost or 127.0.0.1 address, also set BETTER_AUTH_TRUSTED_ORIGINS to that origin (for example http://localhost:3199). The core maps a loopback address back to its internal port and would otherwise reject sign-ins from the new one.

Troubleshooting