Start here
What runs on your machine, what stays on the platform, and what “connected” actually means — before you download or install anything.
You can connect a machine with the desktop app or with a one-liner. Both install the same agent identity under ~/.clikdeploy. Afterwards the platform cannot tell which path you used, and you do not end up with two servers for one computer.
| Method | Who it is for |
|---|---|
Desktop app | Menu-bar / tray app for non-technical users. Sign in in the real browser; the app installs the agent and waits for a heartbeat. No terminal required. |
One-liner (curl | bash) | Terminal install. You get a short pairing code from the dashboard, run one command on the machine, and the installer does the rest. |
From the dashboard, start Connect a computer (or Connect Server). That gives you either the desktop download or a pairing code for the shell install:
curl -fsSL "https://clikdeploy.com/install.sh?code=YOUR_CODE" | bash
If you already use the CLI and are logged in on the machine, you can also run clikdeploy server connect agent <name> — see the CLI reference and the quickstart.
Same layout either way
Desktop and install.sh both write ~/.clikdeploy/agent.json, the same pinned Node under ~/.clikdeploy/node, and the same agent bundle under ~/.clikdeploy/agent. Re-running either path is safe: identity is reused when it is still valid.
Everything below lives under your home directory (plus an optional root helper for Docker-level work). Nothing here is the full ClikDeploy product — only the piece that has to sit next to your containers.
| On disk / process | What it is |
|---|---|
~/.clikdeploy/agent.json | The one identity file: agent id, server id, durable token, and platform URL. Mode 600. Written at pair/register time. |
~/.clikdeploy/agent | The agent bundle (dist/, node_modules/, run.sh). Downloaded from the release manifest and sha256-verified before extract. |
~/.clikdeploy/node | A pinned Node runtime the agent launches with. Its own sha256 is verified at install so the interpreter is not an unverified trust gap. |
Agent process (user service) | A per-user service (systemd --user on Linux, launchd agent on macOS, scheduled task on Windows). Restarts on crash and at login/boot for that user. No root required for connect. |
~/.clikdeploy/helper.sock | Unix socket for the optional privileged helper (Windows uses a named pipe). The unprivileged agent asks it for a fixed list of root ops — never arbitrary shell. |
~/.clikdeploy/runtime.json | Optional live knobs (for example keep-awake toggles from the desktop app). Readable by the agent without rewriting the service unit. |
The agent opens an outbound connection to the platform. You do not open inbound ports or a VPN for day-to-day control.
connectonly=1 to the one-liner (or pass --connect-only) to attach without helper/Docker work. You are Connected; deploys wait until a runtime is available.The control plane lives on ClikDeploy's servers (or your self-hosted control plane). Your machine never hosts these:
Install is not a single green check. There are two independent outcomes, on purpose.
| Stage | What it means |
|---|---|
1. Connected | The agent is installed as a user service, has written agent.json, and the platform has confirmed a live heartbeat. Only then does the installer (or desktop app) treat connect as success. |
2. Deploy-ready | A container runtime (Docker) is available so the agent can pull images and run apps. This may land later. Missing Docker does not undo “Connected”; it only blocks deploys until the runtime works. |
Connected ≠ ready to deploy
If you see the machine on the canvas but a deploy fails immediately, check Docker first. The one-liner prints a clear note when connect succeeded but Docker is not ready yet; the desktop app treats helper/Docker elevation as a separate, optional step after heartbeat.
Connect is designed so a half-trust path fails closed, not silently.
The agent is not a second ClikDeploy product. These stay on the platform (or in your browser):
Ready to connect? Follow the quickstart (step 1 is connect a server), then deploy something. For terminal day-to-day, see the CLI.
Stuck? Ask on Discord or email [email protected].