Real questions, with answers grounded in how DockSight actually behaves.
The file is not a binary. It is GitHub's HTML "not found" page, saved under the
binary's name because the download URL was wrong and curl was not told to fail:
$ head -c 16 docksight-cli-v0.0.1-linux-amd64 | od -c
0000000 \n \n \n \n \n \n < ! D O C T Y PThe shell tried to execute HTML and choked on line 8 of the markup. Confirm with
file:
file docksight-cli-* # want: ELF 64-bit LSB executable, x86-64, statically linkedAlways download with -f, which turns a 404 into an error instead of a saved
error page:
curl -fLO https://github.com/Open-Source-Kigali/docksight/releases/latest/download/docksight-cli-v0.0.1-linux-amd64The usual root cause is that the asset genuinely does not exist on that release — check before blaming the network:
curl -s https://api.github.com/repos/Open-Source-Kigali/docksight/releases/latest | grep '"name": "docksight'The execute bit is missing. GitHub serves release assets over plain HTTP with no
file mode, so every download arrives as 0644:
chmod +x docksight-cli-v0.0.1-linux-amd64This is also true of assets built on Windows, where NTFS has no execute bit to preserve in the first place.
Wrong architecture for the machine. Check and re-download:
uname -m # x86_64 → -linux-amd64, aarch64 → -linux-arm64Windows, yes — both the agent and the platform. macOS, no.
docksight agent install registers the agent with the Service Control Manager.
See Windows support.
docksight install runs the platform's five Linux containers on a Docker
Engine in Linux-container mode, which on Windows means Docker Desktop. Both
commands need an Administrator prompt. See
Windows platform install for what it configures and
the one thing it cannot do.
macOS is not supported for either: the release publishes a macOS CLI build,
but it can only run version and --help.
Not on its own. This is the one real limitation of running the platform on Windows, and it is worth understanding before you choose that host.
Docker Desktop's engine runs in a VM started by the Docker Desktop
application, in a user session. A Windows host that reboots to a sign-in
screen has no engine — so the containers, all of which are
restart: unless-stopped, have nothing to restart them. The platform stays down
until somebody signs in.
To reduce the window, enable Docker Desktop → Settings → General → "Start Docker Desktop when you sign in" and configure the machine to sign in automatically. There is no arrangement that makes the platform survive a reboot with nobody signed in.
A monitoring platform that is offline exactly when the machine has just rebooted is the worst time for it to be offline. If unattended restarts matter, run the platform on a Linux host — the agent still installs on all your Windows machines and reports to it.
For the platform, yes. It needs a Docker Engine in Linux-container mode, and Docker Desktop is how you get one on Windows. Note that Docker Desktop requires a paid subscription for larger organisations.
For the agent, no. The agent talks to whatever Engine is on the host over
the \\.\pipe\docker_engine named pipe, and only monitors it.
Both installers make machine-wide changes. The agent registers a Service Control
Manager service; the platform writes to C:\Program Files, adds a machine PATH
entry and opens a firewall port. None of that is permitted to an ordinary user.
Start an elevated PowerShell — right-click Windows PowerShell → Run as administrator — and run the command again.
The check runs during validation, before anything is downloaded or written, so a failure here leaves the host untouched.
A Docker Engine on Windows runs either Linux or Windows containers, never both
at once, and the platform's images — postgres:17-alpine among them — are Linux
images. Right-click the Docker Desktop tray icon and choose Switch to Linux
containers, then run the install again.
Without this check the daemon would reject the images with a manifest error that never mentions the mode being wrong.
Yes, in practice. The agent needs a reachable platform URL, and installation verification checks that it connected. You can install an agent first — it will install and then retry the connection with exponential backoff (capped at 30 seconds, with jitter) until the platform appears — but you lose the verification signal.
sudo systemctl start docker
sudo systemctl enable dockerIf the message mentions permission denied instead, the daemon is up but your
user cannot reach its socket. Use sudo.
On Linux the agent is a systemd service, so systemd must be PID 1. Common causes: you are inside a container, or in WSL without systemd. For WSL:
[boot]
systemd=trueThen wsl --shutdown and reopen.
This check does not run on Windows, where the Service Control Manager takes systemd's place.
Not today. Both installers resolve releases from api.github.com and download
assets from GitHub. An air-gapped installation would need the artifacts staged
manually, which is not yet supported.
No. That is the central design decision. Agents always dial out; nothing ever connects to them. Hosts behind NAT, in another cloud, or on a home network work with no port forwarding and no VPN. See why agents dial out.
2002 by default, published by nginx. Change DOCKSIGHT_PORT in
/opt/docksight/.env and restart the stack.
Only if you tell it to. The scheme is derived from the platform URL you give at
install time: https:// becomes wss://, http:// becomes ws://. Installing
with http://10.0.0.5:2002 gives you an unencrypted session and nothing warns
you at runtime. See Security.
journalctl -u docksight-agent -n 50 --no-pager
grep url /etc/docksight-agent/config.yamlIn order of likelihood:
- Wrong port in the platform URL.
:200and:2002are both accepted at install time; only one of them is your platform. - Platform not reachable from that host — test with
curl -I http://platform:2002. - Egress blocked by a firewall.
Fix the URL without reinstalling:
sudo docksight agent update --url http://platform.example.com:2002Yes. Each host only needs outbound reachability to the platform. They do not need to reach each other.
Containers keep running — the agent does not stop anything. The agent retries with exponential backoff (capped at 30 seconds, with jitter) and re-registers when the platform returns. Only management is unavailable in the meantime.
It reads /var/run/docker.sock, which is root-owned. Running as a non-root user
would require adding that user to the docker group — which grants
root-equivalent access anyway, just less visibly.
It is exactly as dangerous as Docker access always is: socket access is
root-equivalent on the host. Anyone who can use it can start a container that
mounts /.
What DockSight does to limit exposure: the socket is read locally and never published to the network, the agent exposes no inbound port, and the agent implements a fixed set of operations rather than proxying arbitrary Docker API calls. See Security.
It is not supported. The installer requires systemd, and a containerised agent would need the Docker socket bind-mounted in — which is precisely the pattern security guidance warns against.
The release exists but nobody uploaded the agent binaries to it. The error lists what is published:
release v0.0.1 publishes no asset matching docksight-agent-* for linux-amd64
(has: docksight-cli-v0.0.1-linux-amd64, docksight-platform-v0.0.1.tar.gz, ...)
Fix it on the release side:
scripts/build-release.sh v0.0.1
scripts/publish-release.sh v0.0.1publish-release.sh verifies against the API after uploading, which is what
prevents this recurring.
GitHub's /releases/latest excludes drafts and prereleases. If the newest
release is either, installers keep resolving the previous one. Publish it
properly, or pin with --version.
Yes, by design. The CLI, platform and agent version independently, and the protocol ignores unknown message types and unknown payload fields. A v0.0.1 agent works against a v0.0.1 platform, using only the subset it knows.
No. release/ is git-ignored. The artifacts are build outputs, rebuildable from
any tag, and binaries bloat repository history permanently.
The platform must push commands and receive streams. Polling adds latency and wastes requests; an inbound HTTP API on the agent would require open ports; gRPC adds a proto toolchain across a Go/TypeScript boundary and needs extra plumbing through HTTP/1.1 proxies. WebSocket gives one long-lived bidirectional connection that traverses ordinary proxies. See why WebSocket.
It sends agent.heartbeat every 30 seconds. TCP keepalives are not enough — a
connection can stay open through a NAT device long after the process behind it
stopped working. The heartbeat proves the agent's event loop is running.
Silence is success. An ack would double heartbeat traffic to tell the agent something the socket already tells it.
Yes. protocol.md is a complete specification: implement
agent.register, agent.heartbeat, and whichever domains you need. Keep the
{ type, payload } envelope and ignore unknown fields.
In Docker named volumes (postgres-data, redis-data), not in
/opt/docksight. Reinstalling the platform does not touch them.
Back up the postgres-data volume and /opt/docksight/.env together. The
password in .env must match the volume it was initialised with; restoring one
without the other leaves you locked out.
.env is 0600 and root-owned. Compose running as another user cannot read it,
so every variable interpolates empty — Postgres refuses a blank password, and
JWT_SECRET silently falls back to the placeholder in the compose file. Compose
reports this only as warning: The "POSTGRES_PASSWORD" variable is not set. Run
Compose with sudo.
Not simply. POSTGRES_PASSWORD is baked into the database volume at first boot,
so changing it in .env alone locks the platform out. Rotating it means
changing it inside PostgreSQL as well. JWT_SECRET can be changed freely — it
only invalidates existing sessions.
Not yet. It prints a fixed string. Use:
docker compose -f /opt/docksight/dockersight-installation.yml psIt holds the UUID that makes a machine the same host across restarts and upgrades. Deleting it makes the agent generate a new UUID, so the platform sees a brand-new host and the old record becomes an orphan. Never copy it between machines — two agents claiming one identity is worse than two identities.
No. agent install and agent update both preserve identity.json, so the host
keeps its identity and history.
No — docksight agent update reads it back from /etc/docksight-agent/config.yaml.
That is deliberate: retyping is how a wrong port gets introduced.
sudo docksight agent update --version v0.0.1Only releases that actually publish agent binaries are valid targets.
They are declared placeholders and return "not implemented yet". Use systemctl
and journalctl — see the CLI reference.
The service is healthy and stayed up, but the journal had no connection line yet when verification finished — common on a slow link. Watch it:
journalctl -u docksight-agent -fLook for websocket connected followed by registration acknowledged.
No. Installation writes to a private temporary directory first and only copies into place after a successful download and extraction. A failure before that point leaves nothing behind; a failure at the compose stage leaves the files installed so you can inspect and retry. Every install command is safe to re-run.
An older CLI staged downloads at a fixed /tmp path, which collides with a
root-owned file left by an earlier sudo run — /tmp is sticky-bit 1777, so
you may create files there but not truncate someone else's. Current versions
stage in a private per-run directory. Upgrade the CLI, or sudo rm the stale
file.
Installation reports this rather than claiming success:
✗ service failed to start: server: exited (code 3)
Then:
docker compose -f /opt/docksight/dockersight-installation.yml logs server
journalctl -u docksight-agent -n 100 --no-pager=== "Platform"
```bash
cd /opt/docksight
docker compose -f dockersight-installation.yml down -v # -v deletes data
sudo rm -rf /opt/docksight /var/lib/docksight
```
=== "Agent"
```bash
sudo systemctl disable --now docksight-agent
sudo rm /etc/systemd/system/docksight-agent.service
sudo systemctl daemon-reload
sudo rm -rf /etc/docksight-agent /usr/local/bin/docksight-agent
```
Removing `/etc/docksight-agent` discards the identity, so the host will
register as new.
Open an issue with the command you ran, the full output, docksight version,
and the relevant logs. See Contributing —
and redact .env contents before pasting.