Setup

Use this guide when your Linux VM or bare-metal host is already provisioned and you have the Kumo Docker Compose bundle. The bundle runs the Kumo images from NVIDIA NGC, plus its bundled Postgres database and Temporal workflow service that schedules Kumo background work, on one host. The first path uses localhost and local storage on CPU. GPU-backed training and prediction are optional.

Prerequisites

Have the following before you start:

• Linux x86_64 host: Recommended sizing is 32 vCPU, 128 GB RAM, and durable storage for Docker, Postgres, and the Kumo dataplane, where Kumo stores ingested data and model artifacts.
• Dedicated fast local SSD: Mount it at /mnt/localssd for DiskGraph working data. DiskGraph is Kumo’s on-host graph-processing workspace. The SSD must not be the root filesystem.
• GPU host (optional): An NVIDIA GPU with sufficient VRAM, a working host driver, and NVIDIA Container Toolkit configured for Docker. The primary path below uses CPU mode.
• Docker and host utilities: Docker Engine, Docker Compose v2, curl, openssl, and findmnt.
• NGC access: An API key entitled to nvcr.io/1000161941370113/kumo-3, plus network access to NGC and the upstream images referenced by Compose.
• Complete deployment bundle: kumo-compose, all three Compose files, and both config/ directories shown below.

The supplied configuration disables application authentication and TLS. Keep the published HTTP port private, behind an SSH tunnel, or otherwise restricted to trusted clients.

Verify the host:

docker version
docker compose version
openssl version
findmnt -n -o SOURCE,FSTYPE,TARGET -T /mnt/localssd
test "$(findmnt -n -o SOURCE -T /mnt/localssd)" != "$(findmnt -n -o SOURCE -T /)"

Starting Kumo

The deployment bundle includes the Compose wrapper, service definitions, and configuration for a single-host Kumo deployment. The steps below start the default CPU configuration with localhost access and local dataplane storage.

The commands below assume this bundle layout. Run the Compose commands from docker/compose/.

~/path-to-docker-compose/
├── README.md
├── .env.template
└── docker/compose/
    ├── kumo-compose
    ├── docker-compose.singlehost.yml
    ├── docker-compose.singlehost.postgres.yml
    ├── docker-compose.singlehost.gpu.yml
    ├── config/
    │   ├── postgres-initdb/
    │   └── temporal/dynamicconfig/
    └── .env (created in Step 1)

1. Create the runtime directories and environment file

cd ~/path-to-docker-compose/docker/compose
mkdir -p data/{dataplane,glove,nginx,prometheus,secrets,tls}
cp ../../.env.template .env
chmod 600 .env
sudo chown 999:999 /mnt/localssd
sudo chmod 0750 /mnt/localssd

Before the first startup, edit .env and set a unique Postgres password:

POSTGRES_PASSWORD=PASTE_A_UNIQUE_SECRET_HERE

Generate the password with openssl rand -hex 32 if needed. Leave the local-storage defaults in place:

PUBLIC_URL=http://localhost
DISABLE_AUTH=true
ENABLE_TLS=false
DISKGRAPH_DATA_ROOT=/mnt/localssd
LOCAL_DATAPLANE_HOST_MOUNT=./data/dataplane
DATAPLANE_ROOT=/opt/app/data/dataplane
ARTIFACT_ROOT=/opt/app/data/dataplane/artifacts
KUMO_POSTGRES_MODE=bundled
KUMO_BACKEND_VARIANT=cpu

2. Authenticate to NGC and start the stack

Use an API key that is entitled to the Kumo NGC organization. This command reads the key without displaying it:

read -rsp 'NGC API key: ' NGC_API_KEY; echo
printf '%s' "$NGC_API_KEY" | docker login nvcr.io --username '$oauthtoken' --password-stdin
unset NGC_API_KEY

Validate the rendered configuration, pull the images, and start Kumo:

./kumo-compose config --quiet
./kumo-compose config --images | sort -u
./kumo-compose pull
./kumo-compose up -d
./kumo-compose ps --all

3. Verify Kumo

Cold startup can take several minutes. kumo-bootstrap, temporal-schema, and temporal-namespace should finish with exit status 0; the long-running services should become healthy.

./kumo-compose ps --all
./kumo-compose logs --no-color kumo-bootstrap temporal-schema temporal-namespace
docker inspect --format '{{.State.Health.Status}}' kumo-rest kumo-rest-public
curl --fail http://localhost/ -o /dev/null
docker exec kumo-rest python3 -c "import urllib.request; urllib.request.urlopen('http://localhost:8000/health', timeout=10)"

Open http://localhost in a browser on the host, or reach it through a secure tunnel. With the default DISABLE_AUTH=true, Kumo does not display a sign-in prompt.

Deployment-type variations

Use these optional settings in place of the defaults from Step 1, before the first startup.

Optional Kumo authentication

Before the first startup:

1. Set DISABLE_AUTH=false in .env.
2. Uncomment DIRECT_CONNECT_LOGIN_METHOD, ADMIN_EMAILS, and DIRECT_CONNECT_ADMIN_TEMP_PASSWORD, then provide the administrator email and a unique temporary password.

After startup, sign in as that administrator, change the temporary password, and create a real API key for SDK access. A random placeholder API key is not accepted when authentication is enabled.

Optional TLS termination

To terminate TLS in the bundled nginx service, set these values in .env before the first startup:

ENABLE_TLS=true
PUBLIC_URL=https://kumo.customer.example
NGINX_PORT=443

Install a trusted full-chain certificate and its matching unencrypted private key before starting Kumo:

sudo install -o 999 -g 999 -m 0644 /path/to/fullchain.pem data/tls/server.crt
sudo install -o 999 -g 999 -m 0600 /path/to/private-key.pem data/tls/server.key

The default KUMO_TLS_DIR=./data/tls mounts these files read-only at /etc/kumo/tls for bootstrap and nginx. Bootstrap generates the HTTP or TLS nginx configuration only on its first run. If a customer-managed proxy terminates TLS, leave ENABLE_TLS=false and allow the published HTTP port to be reached only from that proxy.

Optional GPU-backed training and prediction

To use a GPU, add an NVIDIA GPU with sufficient VRAM, a working host driver, and NVIDIA Container Toolkit configured for Docker. Verify the GPU and Docker runtime before setting the GPU backend variant:

nvidia-smi
docker info --format '{{json .Runtimes}}' | grep -q '"nvidia"'

Then set this value in .env before starting the stack:

KUMO_BACKEND_VARIANT=gpu

kumo-compose adds the GPU overlay when this value is gpu. The overlay uses the NGC kumo-backend-gpu image for the pool worker and reserves all available NVIDIA GPUs. The included Compose file sets POOL_GPU_CONCURRENCY: "1"; on a multi-GPU host, change that Compose value to the number of physical GPUs you want to use concurrently. It fails early if the GPU or Docker runtime checks do not pass.

Storage and dataplane

For the AWS S3 path, do not combine the S3 roots with the local roots unless you deliberately migrate the generated deployment configuration. The supplied Compose files do not inject AWS_REGION into application containers, so validate image and bundle support for the chosen region before using this optional path.

Stop Kumo

Stop the stack without deleting its data:

./kumo-compose down --remove-orphans

Do not run down -v unless deleting the Docker-managed Postgres and observability volumes is intentional. It does not remove the host-mounted docker/compose/data/ directory or /mnt/localssd.

Next steps