Before you start

You need a machine that can run Linux containers (linux/amd64 or linux/arm64) with Docker, and a little disk for the /data volume. See Platform support for the details.

Start Kumo.io

docker run -d --name kumo \
  -v kumo:/data \
  -p 9500:9500 \
  kumoio/kumo:<version>

Replace <version> with a release version. The image is also tagged by minor line (for example kumoio/kumo:0.6) and latest, which always points at the newest release. Pin an exact version in production so an upgrade is something you choose — see Upgrades.

On first boot the container:

1. creates a PostgreSQL database cluster on the /data volume and starts it inside the container,
2. brings the database schema up to date,
3. starts Kumo.io and prints ✓ Kumo.io is ready with the address to open.

Watch it with docker logs -f kumo.

Open Kumo.io

Open http://localhost:9500. Everything is on that one port: the app at /, the API under /v1/, and the admin API under /v1/admin/.

You can publish the port on any host port (-p 9600:9500) with no other change — Kumo.io follows the address your browser used.

Before your team can use the product, the installation must be connected to a Kumo.io account; until it is, opening it shows the setup screen, which walks you through connecting. Connecting starts a 14-day evaluation trial. Follow First run and recovery for the first visit, and Connect an installation for what connecting does.

The admin credential printed at first boot

The admin API needs a credential, and a fresh container has none, so the first boot creates one. It is printed once in the boot log, in lines that start with [admin]:

docker logs kumo 2>&1 | grep '\[admin\]'

The token is also stored on the volume at /data/keys/admin-bootstrap.token, readable only inside the container. Later boots print only where it lives.

To manage admin access yourself instead, set both KUMO_ADMIN_API_TOKENS and KUMO_ADMIN_ROLES when you start the container; Kumo.io then creates nothing. To run with no admin API at all, add serve appliance --disable-admin to the end of the docker run command.

What is on the /data volume

The /data volume is the whole installation:

Keep the volume, and you keep your installation. Back it up as one unit.

The built-in database listens only inside the container; it is never published on a host port.

Use your own PostgreSQL instead

Set KUMO_PG_DSN to a connection string and the container skips its built-in database entirely:

docker run -d --name kumo \
  -v kumo:/data \
  -p 9500:9500 \
  -e KUMO_PG_DSN='postgres://kumo:<password>@db.example.internal:5432/kumo' \
  kumoio/kumo:<version>

Keep the /data volume even with your own database — Kumo.io's own keys and backups live there. The database user must be able to create the pg_trgm extension the first time the schema is created.

Run commands against the running container

The kumo command inside the container attaches to the running installation, built-in database included:

docker exec kumo kumo doctor
docker exec kumo kumo db migrate --validate
docker exec -it kumo psql -U kumo kumo

The last line opens a SQL shell on the built-in database.

Stop and restart

Give Kumo.io time to finish in-flight work before the container stops:

docker stop -t 30 kumo
docker start kumo

Stopping shuts Kumo.io down first, then the built-in database, cleanly.

Serve Kumo.io on your network

The container serves plain HTTP. To give your team an https:// address, put a TLS-terminating reverse proxy or load balancer in front of port 9500 and set KUMO_EXTERNAL_URL to the public address:

-e KUMO_EXTERNAL_URL='https://kumo.example.com'

Kumo.io uses that address in the links and sign-in redirects it generates. Some first-run steps on a plain-HTTP installation work only from a browser on the same machine — see Connect an installation.

Next steps

• First run and recovery
• Backups and restore
• Check your installation is healthy
• Every setting you can configure