kyklos

README

Kyklos

Kyklos (Greek: Κύκλος — “cycle”) is a small, self-hosted dashboard for Docker Compose stacks. One static binary embeds the UI and talks to your local Docker socket — no separate frontend build, no nginx sidecar.

Getting started · API docs · OpenAPI · Contributing

Why Kyklos?

• Single binary — go:embed dashboard on http://127.0.0.1:9998
• Compose-native — reads docker-compose.yml, shows live container status
• Actions — start, stop, restart, up / down / pull per service or whole stack
• Logs — follow container output over WebSocket
• Preflight — Docker daemon, compose file, registry auth, env files
• Stable UI — polling refreshes rows in place so sort order and hover state are preserved

Quick start

git clone https://github.com/mdarguechi/kyklos.git
cd kyklos
make build
./bin/kyklos --base /path/to/your/compose-stack

Requires Docker with the Compose V2 plugin. See docs/getting-started.md for details.

CLI

kyklos                         # open dashboard in browser
kyklos --no-browser            # server only
kyklos --preflight             # run checks, exit 1 on failure
kyklos --workstation startup   # docker compose up -d
kyklos --base /path/to/stack

API

REST + WebSocket on port 9998 (localhost). Full reference: docs/api.md.

While Kyklos is running, fetch the OpenAPI document:

curl -s http://127.0.0.1:9998/api/openapi.yaml

Development

make test      # unit tests
make trivy     # vulnerability scan (see SECURITY.md)
make build     # → bin/kyklos

Go 1.26.3, CGO_ENABLED=0. Contributions welcome — read CONTRIBUTING.md.

Project layout

cmd/kyklos/           CLI entrypoint
internal/             compose, docker, preflight, server, workstation
web/static/           embedded dashboard assets
docs/                 user & API documentation

License

MIT © Marwa Draguechi marwa@darguechi.com - https://darguechi.com