Komodo with Docker: manage servers and stacks from one web UI (Linux, Windows, Mac)

What you get in one minute#

Komodo is a free, open-source web UI (GPL-3.0) that manages Docker containers, compose stacks, image builds and automations across all your servers from one place. Instead of SSH-ing into each machine, you connect every server once and deploy, update and monitor everything from a single page. Two parts make it up: Core (web UI, API, database) and Periphery (a small agent on each server).

The project is alive: v2.3.4 was released October 2026, and the repository is not archived or renamed. Use cases: a home lab with several machines, a small fleet of VPSes, or a team wanting git-driven deploys and an audit trail.

At a glance:

Logo: Komodo official logo, from the Komodo repository

• Two components: Core hosts the UI, API and MongoDB; Periphery is a small, stateless agent on every connected server.
• The agent dials out: with PERIPHERY_CORE_ADDRESS set (the default in the official compose files), Periphery connects out to Core over a websocket, so managed servers need no open inbound port.
• Keys, not passwords: Core and Periphery authenticate with auto-generated key pairs and a Noise handshake; the Periphery private key never leaves the server, say the docs.
• More than stacks: image builds, Procedures and Actions, Resource Sync (TOML in git), per-server alerting, and an audit trail.
• Platforms: Core runs anywhere Docker runs. The recommended Periphery install (systemd) is Linux-only; a macOS binary exists; no native Windows agent is documented.
• Not Portainer: Komodo trades simplicity for multi-server builds and automation - see Komodo or Portainer?.

How it fits together#

You open Core's web UI; Core keeps all state in MongoDB; on every managed server a Periphery agent dials out to Core, runs docker compose through the local Docker socket, and sends stats and logs back.

Drawn for this guide from the official Komodo docs (komo.do, November 2026). The dashed arrow is the response path: stats and logs flow back to Core over the same websocket.

Before you start#

You need a machine that stays on for Core, Docker with Compose v2, and one or more servers to manage.

Linux: any 64-bit distribution that runs Docker Engine and Compose v2. The Periphery setup script also needs python3. Check:

docker --version
docker compose version
python3 --version

Windows: Windows 10 or 11 with Docker Desktop. Check in PowerShell:

docker --version
docker compose version

Mac: Docker Desktop for Mac. Check in Terminal (same commands as Linux):

docker --version
docker compose version

Checklist:

• [ ] Docker and Docker Compose work (the commands above print a version)
• [ ] Port 9120 is free on the Core machine (or you change it in the compose file)
• [ ] You have new values ready for the database password, admin password, JWT secret and webhook secret
• [ ] Config backed up, if you already run Komodo from another guide
• [ ] For the HTTPS section only: a domain, a DNS record pointing at your server, and ports 80/443 free

Tested by DIY Lab Hub: not yet. Commands come from the official docs and release files read in November 2026; we did not run them.

Step 1: Install Komodo Core with Docker Compose#

The official route downloads two files - the compose file (MongoDB + Core + a local Periphery) and an environment file - then you edit the variables and start it.

Linux#

wget -P komodo https://raw.githubusercontent.com/moghtech/komodo/main/compose/mongo.compose.yaml && \
  wget -P komodo https://raw.githubusercontent.com/moghtech/komodo/main/compose/compose.env

Edit the variables:

nano komodo/compose.env

Then deploy:

docker compose -p komodo -f komodo/mongo.compose.yaml --env-file komodo/compose.env up -d

Windows (PowerShell)#

The docs give wget commands; these PowerShell lines download the same two files:

New-Item -ItemType Directory -Force -Path komodo | Out-Null
Invoke-WebRequest -UseBasicParsing https://raw.githubusercontent.com/moghtech/komodo/main/compose/mongo.compose.yaml -OutFile komodo\mongo.compose.yaml
Invoke-WebRequest -UseBasicParsing https://raw.githubusercontent.com/moghtech/komodo/main/compose/compose.env -OutFile komodo\compose.env
notepad komodo\compose.env

Then deploy (the docs' command with Windows path separators):

docker compose -p komodo -f komodo\mongo.compose.yaml --env-file komodo\compose.env up -d

Mac (Terminal)#

macOS ships curl rather than wget; if you installed wget (for example with Homebrew), the Linux commands work as they are:

mkdir -p komodo
curl -o komodo/mongo.compose.yaml https://raw.githubusercontent.com/moghtech/komodo/main/compose/mongo.compose.yaml
curl -o komodo/compose.env https://raw.githubusercontent.com/moghtech/komodo/main/compose/compose.env
nano komodo/compose.env

Then deploy with the same command as Linux.

What to edit in compose.env first. The file ships placeholder secrets; the docs' step 2 says "edit the variables":

• KOMODO_DATABASE_PASSWORD (shipped as admin) - the MongoDB password
• KOMODO_INIT_ADMIN_PASSWORD (shipped as changeme) - the first admin's password
• KOMODO_JWT_SECRET (shipped as a_random_jwt_secret)
• KOMODO_WEBHOOK_SECRET (shipped as a_random_secret)
• KOMODO_HOST (shipped as https://example.komodo.com) - used for OAuth and webhook URL suggestions

Optionally also KOMODO_INIT_ADMIN_USERNAME (admin) and KOMODO_FIRST_SERVER_NAME (Local). Some systems cannot run the latest MongoDB (issue #59); there the docs offer the same three steps with compose/ferretdb.compose.yaml (FerretDB).

Check it worked. The compose file deploys three services - mongo, core, periphery - and all three should be listed:

docker compose -p komodo -f komodo/mongo.compose.yaml --env-file komodo/compose.env ps

Then open http://localhost:9120 and log in with the admin username and password you set (KOMODO_LOCAL_AUTH=true enables username and password login; KOMODO_INIT_ADMIN_USERNAME and KOMODO_INIT_ADMIN_PASSWORD create the first admin). The docs publish no exact output.

Tip: Change all four secrets in compose.env before the first up -d. The database password is baked into MongoDB on first start, so changing it later takes more than an edit.

Step 2: Connect your servers with the Periphery agent#

Every server you want to manage needs the Periphery agent. The docs give three steps: create an onboarding key, install the agent passing that key, then confirm the connection status is OK.

First, in any browser: Settings, Onboarding, New Onboarding Key. The docs only say "via the Komodo Core API / UI" - issue #1360 reports a half-hour hunt for it; the path comes from issue #1723's repro steps (November 2026). The key displays once, so copy it.

Linux#

The docs recommend systemd: it "avoids a number of complications which can come up when running Periphery in a container" (maintainer, discussion #220). Run the official script as root:

curl -sSL https://raw.githubusercontent.com/moghtech/komodo/main/scripts/setup-periphery.py \
  | python3 - \
  --core-address="https://<core-address>" \
  --connect-as="$(hostname)" \
  --onboarding-key="O-..."

Enable it at boot:

sudo systemctl enable periphery

For a user-level install, add --user to the script and enable linger so the agent survives logout:

sudo loginctl enable-linger $USER

The script installs the binary to /usr/local/bin/periphery, the service to /etc/systemd/system/periphery.service and the config to /etc/komodo/periphery.config.toml (user installs go under $HOME/.config and $HOME/.local/bin). The docs note the user running Periphery must be in the docker group to use Docker without sudo. For many servers, the docs suggest Ansible (example role: bpbradley/ansible-role-komodo).

Windows (PowerShell)#

Plainly: the docs describe no native Windows Periphery install. The release assets are Linux x86_64, Linux aarch64 and Apple; the systemd route above is Linux-only. The documented alternative is the Docker container route, using the official compose/periphery.compose.yaml:

####################################
# KOMODO COMPOSE - PERIPHERY #
####################################

# This compose file will deploy:
#   1. Komodo Periphery

services:
  periphery:
    image: ghcr.io/moghtech/komodo-periphery:2
    init: true
    restart: unless-stopped
    environment:
      # The address of Komodo Core to connect to.
      PERIPHERY_CORE_ADDRESS: komodo.example.com
      # The name of the Komodo Server to connect as.
      # Must match existing server.
      PERIPHERY_CONNECT_AS: server-name
      # Optional. Create a Server Onboarding Key in the Komodo UI.
      # This allows Periphery to create a new Server in the UI with the above name,
      # and can be ommitted once the Server exists in Komodo.
      PERIPHERY_ONBOARDING_KEY: <your-onboarding-key>
      # List of accepted Core public keys.
      # File will be auto written if doesn't exist to match first Core it connects to.
      PERIPHERY_CORE_PUBLIC_KEYS: file:/config/keys/core.pub
      # Specify the root directory used by Periphery agent.
      # All your compose files and repos need to be inside this directory
      # for Periphery to interact with them.
      PERIPHERY_ROOT_DIRECTORY: ${PERIPHERY_ROOT_DIRECTORY:-/etc/komodo}
      # Specify whether to disable the terminals feature
      # and disallow remote shell access (inside the Periphery container).
      PERIPHERY_DISABLE_TERMINALS: false
      # Specify whether to disable the container exec feature
      # and disallow remote container shell access.
      PERIPHERY_DISABLE_CONTAINER_EXEC: false
      # If the disk size is overreporting, can use one of these to
      # whitelist / blacklist the disks to filter them, whichever is easier.
      # Accepts comma separated list of paths.
      # Usually whitelisting just /etc/hostname gives correct size for single root disk.
      PERIPHERY_INCLUDE_DISK_MOUNTS: /etc/hostname
      # PERIPHERY_EXCLUDE_DISK_MOUNTS: /snap,/etc/repos
    volumes:
      # Mount private key storage volume
      - keys:/config/keys
      # Mount external docker socket
      - /var/run/docker.sock:/var/run/docker.sock
      # Allow Periphery to see processes outside of container
      - /proc:/proc
      # Specify the Periphery agent root directory.
      # Must be the same inside and outside the container,
      # or docker will get confused. See https://github.com/moghtech/komodo/discussions/180.
      # Default: /etc/komodo.
      - ${PERIPHERY_ROOT_DIRECTORY:-/etc/komodo}:${PERIPHERY_ROOT_DIRECTORY:-/etc/komodo}

volumes:
  keys:

Save it (for example as komodo\periphery.compose.yaml), set PERIPHERY_CORE_ADDRESS to your Core address and PERIPHERY_CONNECT_AS to the server name, then docker compose up -d. We did not test this route on Windows; the docs do not describe it, and the socket mount depends on your Docker Desktop setup.

Mac (Terminal)#

The release includes a periphery-apple binary; issue #1726 shows a user running it on Apple Silicon via Homebrew. The systemd route is Linux-only, so on macOS you have two documented options:

• the container route, with the same periphery.compose.yaml as Windows, or
• the binary route: download periphery-apple from the latest release, create your config following config/periphery.config.toml, make sure the user is in the docker group, and start it with your process manager:

periphery --config-path /path/to/periphery.config.toml

periphery --help prints the manual. Note the open cosmetic bug from issue #1726: the service can report version v0.0.0 in Core even though the binary is 2.3.4.

Check it worked. In the Core UI, open the Server and confirm the connection status is OK - that is the docs' own third step. The onboarding key is not needed after the first connection.

Tip: Re-run the setup script after every Komodo release. The docs say it can be run multiple times, keeps your existing config, and updates the agent binary.

Step 3: Deploy your first stack#

A Stack is Komodo's compose resource. The docs list three ways to provide the compose file: write it in the UI (Komodo writes the files to the host at deploy time), point to files already on the server, or link a git repo and auto-redeploy on push via webhooks.

Linux#

In any browser: create a Stack, attach your Server, choose "write in the UI", and paste this test stack (our example - the hello backend from our Caddy guide):

services:
  hello:
    image: caddy:2.11.7
    restart: unless-stopped
    command: ["caddy", "respond", "--listen", ":8080", "Hello from Komodo"]
    ports:
      - "8080:8080"

Deploy it. The Stack's environment field becomes a .env file passed via --env-file; values can interpolate Komodo variables with [[KEY_1]] double brackets.

Windows (PowerShell)#

Same in any browser - the UI steps above are identical. To check on the managed server, run the same command as Linux.

Mac (Terminal)#

Same in any browser.

Check it worked. On the managed server, list compose projects - Komodo matches projects by compose project name, and the project name defaults to the Stack name:

docker compose ls

Then fetch the test page (our example's own expected answer):

curl http://<server-address>:8080

To import a running project, create a Stack with the same compose files and the correct Server; if the running project name differs from the Stack name, set a custom project_name (docs).

Put it behind HTTPS with Traefik#

For a Core server with a domain; local-only users can skip it. Put Core behind HTTPS before exposing it - the UI logs into your whole fleet. The labels below are our addition; the official compose ships without them.

With Traefik#

Create the proxy network if you do not have it (docker network create proxy), then extend the core service in komodo/mongo.compose.yaml:

  core:
    image: ghcr.io/moghtech/komodo-core:${COMPOSE_KOMODO_IMAGE_TAG:-2}
    init: true
    restart: unless-stopped
    depends_on:
      - mongo
    ports:
      - 9120:9120
    env_file: ./compose.env
    environment:
      KOMODO_DATABASE_ADDRESS: mongo:27017
    container_name: komodo-core
    networks:
      - proxy
    labels:
      - "traefik.enable=true"
      - "traefik.docker.network=proxy"
      - "traefik.http.routers.komodo.rule=Host(`komodo.example.com`)"
      - "traefik.http.routers.komodo.entrypoints=https"
      - "traefik.http.routers.komodo.tls=true"
      - "traefik.http.services.komodo.loadbalancer.server.port=9120"
    volumes:
      - keys:/config/keys
      - ${COMPOSE_KOMODO_BACKUPS_PATH}:/backups

networks:
  proxy:
    external: true

Also set KOMODO_HOST=https://komodo.example.com in compose.env (the docs use it for OAuth and webhook URL suggestions). Remote Periphery agents then connect with --core-address="https://komodo.example.com" - exactly the form in the connect docs.

Without Traefik: Caddy#

Run Caddy as shown in our Caddy with Docker guide - one container on ports 80 and 443, mounting the conf folder (./conf:/etc/caddy), not a single Caddyfile. Add this site block to your Caddyfile:

komodo.example.com {
    reverse_proxy komodo-core:9120
}

Reload with docker compose exec -w /etc/caddy caddy caddy reload. With a public domain, Caddy gets a Let's Encrypt certificate automatically (it needs the DNS record pointing at your server and ports 80/443 reachable). Home-only, with no public domain, use Caddy's own local certificate:

komodo.home.arpa {
    tls internal
    reverse_proxy komodo-core:9120
}

Devices trust it once you import Caddy's root certificate (data/caddy/pki/authorities/local/root.crt): on Linux copy it to /usr/local/share/ca-certificates/ and run sudo update-ca-certificates; on Windows run certutil -addstore -f ROOT <file> as administrator; on Mac run sudo security add-trusted-cert -d -r trustRoot -k /Library/Keychains/System.keychain <file>. The full steps are in the Caddy guide.

Check it worked. curl -I https://komodo.example.com/ returns a status line over HTTPS with no certificate warning. The docs publish no exact output.

Security and testing#

The docs warn about two specific permissions: Inspect on a Server "can easily lead to secrets being leaked" because it exposes all container environments on that server, and Terminal on a Server grants a server-level shell plus all container exec. Give both sparingly.

Quick tests after any change:

docker compose -p komodo -f komodo/mongo.compose.yaml --env-file komodo/compose.env ps
docker compose -p komodo -f komodo/mongo.compose.yaml --env-file komodo/compose.env logs core --tail 100
curl -I https://komodo.example.com/

On Windows, the same commands work in PowerShell (use curl.exe).

What leaves the machine: Periphery sends system stats (every 5 seconds by default), container stats (every 30 seconds), plus logs and terminal output on request, to your Core over the authenticated websocket. Core talks to git providers, registries, alerters, OAuth providers or AWS only if you configure them. We found no telemetry-to-the-developers setting in the docs or example configs; the only telemetry option is an OpenTelemetry endpoint that is empty by default.

Tip: Treat the Inspect permission like root on that server's containers: it hands out every container's environment variables, which is where compose apps keep their secrets.

How Komodo handles secrets and variables#

A variable or secret is a key-value pair. You interpolate it into resource fields with double brackets: SOME_ENV_VAR = [[KEY_1]]. The docs give four places to define them, in increasing privacy:

1. UI variables (Settings, Variables tab): stored in the database. Check the "secret" option and the value is hidden from updates and logs, and from non-admin users. The docs advise managing secrets in Resource Syncs only for non-secret variables.
2. Core config file ([secrets] block in core.config.toml): keys are visible on the variables page, but "the values are not exposed by API for ANY user".
3. Periphery config file ([secrets] block in periphery.config.toml): available only to resources on that one server, and "Periphery based secrets are never exposed to the network" - they never travel from Core to the agent:

[secrets]
KEY_1 = "value_1"
KEY_2 = "value_2"

4. A dedicated secret manager such as HashiCorp Vault: the docs say plainly that Komodo's features "may not fill enterprise level secret management requirements" - in that case your apps pull secrets from the real secret manager and they stay out of Komodo entirely.

Secret environment variables in compose.env also support the ${VARIABLE}_FILE form for Docker Compose secrets.

Tip: If a value must never cross the network, put it in the Periphery config on the server that needs it - that is the only route the docs guarantee never exposes the secret to Core.

Komodo or Portainer?#

We have a full Portainer installation guide; both tools manage Docker from a web UI, and both use a server plus agents (Portainer's docs: "the Portainer Server, and the Portainer Agent", UI on 9443).

Our take: one machine and simple stacks fit Portainer (our guide there is a shorter read). Several servers, git-driven deploys, builds or scheduled automations are where Komodo earns its extra setup. Both are free; Komodo's README carries a no-warranties disclaimer.

Common mistakes#

From the official docs' warnings, the maintainer's discussion #220, and the issue tracker (all read November 2026).

Troubleshooting#

Known bugs (open, November 2026)#

• Issue #1714: one oversized websocket response makes the server unreachable until Periphery restarts (v2.3.4).
• Issue #1711: Resource Sync skips file-only changes until the next resource poll (default 1-hr).
• Issues #1720 and #1635: CPU and memory stats are wrong inside LXC containers (PRs open).
• Issue #1723: the onboarding-key table can show stale names, and a blur can rename the wrong key - reload the page after creating a key.
• Issue #1546: reports of high CPU spikes caused by Periphery; one comment so far.

Diagnostics to run first: docker compose ps, docker compose logs core --tail 100 (with the project's flags from Step 1), and docker inspect on the agent container.

Updates and backups#

Update Core. The image tag COMPOSE_KOMODO_IMAGE_TAG="2" tracks the latest v2.x, so a pull brings the new version:

docker compose -p komodo -f komodo/mongo.compose.yaml --env-file komodo/compose.env pull
docker compose -p komodo -f komodo/mongo.compose.yaml --env-file komodo/compose.env up -d

Update Periphery. Re-run the setup script from Step 2 on each server; the docs say it updates the agent and keeps your config. Container-installed agents update with the same pull.

Backups. Komodo backs itself up: new installs (v1.19.0+) create a "Backup Core Database" Procedure scheduled every day at 01:00. Backups are gzip files in dated folders under the host path you mounted at /backups (COMPOSE_KOMODO_BACKUPS_PATH), the most recent 14 are kept, and the Stats history is excluded. The docs warn: "Currently no built-in encryption is supported" - encrypt remote copies yourself.

Restore with the CLI image (the docs' snippet; it restores the most recent backup, or pass --restore-folder):

services:
  cli:
    image: ghcr.io/moghtech/komodo-cli
    command: km database restore -y
    volumes:
      - /path/to/komodo/backups:/backups
    environment:
      KOMODO_CLI_DATABASE_TARGET_ADDRESS: komodo.example.com:27017
      KOMODO_CLI_DATABASE_TARGET_USERNAME: <db username>
      KOMODO_CLI_DATABASE_TARGET_PASSWORD: <db password>
      KOMODO_CLI_DATABASE_TARGET_DB_NAME: komodo-restore

The docs warn the restore does not clear the target database first, so old documents remain - drop the target before restoring into it.

Also keep your own config archive (the compose.env file and any agent configs) with the date in the name, on a schedule (Linux/Mac cron at 03:00; Windows Task Scheduler), and test a restore into an empty folder - never over the live one.

Performance and resources#

The project documents no RAM or CPU figures, so this guide gives none. The official compose caps MongoDB's WiredTiger cache at 0.25 GB (--wiredTigerCacheSizeGB 0.25), which is the only resource number in the docs. Measure your own load with docker stats.

Traffic knobs from the docs, if Core-to-agent chatter matters on slow links: KOMODO_MONITORING_INTERVAL (default 15-sec, how often Core polls servers), PERIPHERY_STATS_POLLING_RATE (default 5-sec) and PERIPHERY_CONTAINER_STATS_POLLING_RATE (default 30-sec). Raising them lowers traffic and refresh rate together.

FAQ#

Is Komodo still maintained? Yes. v2.3.4 was released in October 2026, and the repository is active (read November 2026). It is not archived and not renamed.

Komodo or Portainer? See Komodo or Portainer? above, and our Portainer guide. Short version: one server, simple needs - Portainer; several servers, builds or git-driven automations - Komodo.

Can Komodo manage a Windows server? Not natively. The docs describe no Windows Periphery install; the container route is the only documented option, and we did not test it under Docker Desktop.

Where do my secrets live? Four places, from UI variables to a dedicated secret manager - see How Komodo handles secrets and variables.

Does Komodo phone home? We found no telemetry setting aimed at the developers. Traffic is what you configure: agent-to-Core stats and logs, plus git providers, registries, alerters, OAuth or AWS if you enable them. The optional OpenTelemetry endpoint is empty by default.

Is there a limit on servers? The README: "There is no limit to the number of servers you can connect, and there will never be."

Sources#

• Komodo docs: What is Komodo?, Setup Core, MongoDB quick start, FerretDB setup, Connect More Servers, Backup and Restore, Variables and Secrets, Permissioning, Resources, Docker Compose stacks - read November 2026
• Komodo repository, release v2.3.4, mongo.compose.yaml, compose.env, periphery.compose.yaml, periphery.config.toml, periphery setup script readme - read November 2026
• Maintainer discussion To Systemd or not to Systemd (#220) - read November 2026
• Issues and PRs read November 2026: #1360, #1506, #1546, #1566, #1249 / PR #1614, #1139 / PR #1635, #1384 / PR #1720, #1704, #1711, #1714, #1723, #1726, #1727, #249, PR #1053, #1586
• Portainer CE install docs (for the comparison) - read November 2026
• Caddy automatic HTTPS docs and our Caddy with Docker guide - read November 2026

Checked against the official docs on 2026-11-05.