Installing an agent

An agent lets CuliPulse check targets only reachable from inside your own network. Setting one up takes two steps: enroll it, then run it.

Saved passwords and tokens stay with CuliPulse

An agent you run never receives your saved sign-in details, secret headers, secret request bodies or secret payloads, so its checks run without them. CuliPulse warns you when you save a monitor that mixes the two, and repeats the warning on every save while it stands. See Saved passwords and tokens.

1. Enroll

1. Go to Agents → Add agent.
2. Give it a name and a label for where it runs (e.g. office-lan, prod-vpc).
3. CuliPulse generates a one-time enrollment token. It’s shown once — the install command on the next screen already has it filled in, so copy that command directly. You don’t choose which check types it can run: the agent reports that itself when it first connects.

2. Run

The enroll screen gives you a ready-to-run command for each method, pre-filled with your API URL and token. Copy the one you want — the shapes below are just for reference.

Docker

docker run -d --restart=unless-stopped --network host --cap-add=NET_RAW \
  -e CULIPULSE_API_URL=https://culipulse.dev \
  -e CULIPULSE_AGENT_TOKEN=<your-token> \
  ghcr.io/culipulse/agent:latest

• :latest is always the newest released version. To stay on a specific version instead, use its number as the tag (for example ghcr.io/culipulse/agent:1.12.1).
• --network host lets the agent reach services on the same machine (for example a database on 127.0.0.1) as well as everything else on the host’s network.
• NET_RAW is needed for ICMP (ping) checks.

Native Linux (systemd)

Installs a small static binary as a hardened systemd service — no Docker required. Re-running the same command later updates it in place.

curl -fsSL https://culipulse.dev/install.sh | sudo \
  CULIPULSE_API_URL=https://culipulse.dev \
  CULIPULSE_AGENT_TOKEN=<your-token> sh

Kubernetes

The enroll screen generates a manifest (a Secret plus a single-replica Deployment, with the NET_RAW capability granted for ping). Apply it:

kubectl apply -f culipulse-agent.yaml

Checking services on the same machine

To monitor something running on the same machine as the agent (say Redis on 127.0.0.1:6379), the agent has to share the machine’s network. That is what --network host does.

• Checks fail with “Port closed or refused”, but the port is open on the machine. The agent was started without --network host, so 127.0.0.1 inside the container is the container itself, not your machine. Find the container’s name with docker ps, remove it with docker rm -f <container-name>, and run the command again with --network host. To get a ready command: open the agent’s page, then Update this agent and Generate update command. It recreates the container with a fresh token, so add back any extra -e settings you had added, such as network discovery. Auto-update (Watchtower) keeps the container’s old settings, so it won’t add host networking for you.
• Docker Desktop (Mac, Windows or Linux). By default, host networking points at Docker’s own virtual machine, not at your computer’s localhost. Use host.docker.internal:<port> as the monitor’s target instead of 127.0.0.1.
• Native Linux (systemd) install. It runs directly on the machine, so 127.0.0.1 already means the machine and nothing extra is needed.

With host networking, anyone who can create monitors in your workspace can point checks at services on that machine. The native install works the same way.

3. Confirm it connected

After the agent starts, the enroll screen watches for its first check-in and shows connected. The agent now appears in your Agents list and can be picked as a checkpoint on any monitor.

Only outbound access needed

An agent makes outbound HTTPS connections to CuliPulse and to the targets you ask it to check. It never needs an inbound port opened, a VPN, or a firewall change.

Update an agent

A new agent version is published from time to time. The Agents list shows each agent’s version and whether an update is available. How you update depends on how you installed it. On the agent’s own page, Update this agent shows the exact commands for your setup.

Docker

• Automatic (recommended). Run Watchtower once, scoped to just the agent container. It pulls the new image and recreates the container in place whenever a new version is released, keeping its settings and token. Replace <container-name> with the name from docker ps (for an agent called office-lan that is culipulse-office-lan):

  docker run -d --name culipulse-watchtower --restart=unless-stopped \
    -v /var/run/docker.sock:/var/run/docker.sock \
    containrrr/watchtower --cleanup <container-name>

  If you run more than one agent on a host, give each Watchtower its own --name.

• By hand. Open the agent’s page, choose Update this agent, then Generate update command. This gives the agent a fresh token (the old one stops working immediately) and hands you a docker pull, docker rm -f and docker run block. Run it on the agent’s host.

Native Linux (systemd)

Re-run the install command without a token. It downloads the latest binary, keeps your existing settings and restarts the service:

curl -fsSL https://culipulse.dev/install.sh | sudo sh

To restart without downloading anything: sudo systemctl restart culipulse-agent.

Kubernetes

Restart the Deployment so it pulls the latest image. The Secret, and so the token, is kept:

kubectl rollout restart deployment/culipulse-agent-<name>

If you changed the manifest, apply it again instead. The exact name is on the agent’s page under Update this agent.

Remove an agent

Revoking an agent in the console does not stop the software. The program keeps running on your machine and keeps trying to connect with a token that no longer works, which fills its log with “401 unauthorized” lines. Stop it on the host too, in this order:

1. Stop it where it runs.

   • Docker: docker rm -f <container-name>. If you set up auto-update, also remove it: docker rm -f culipulse-watchtower.

   • Native Linux (systemd):

     sudo systemctl disable --now culipulse-agent
     sudo rm /etc/systemd/system/culipulse-agent.service /usr/local/bin/culipulse-agent
     sudo rm -r /etc/culipulse-agent
     sudo systemctl daemon-reload

     The installer may also have created a culipulse system user. You can leave it, or remove it with sudo userdel culipulse.

   • Kubernetes: kubectl delete deployment,secret culipulse-agent-<name>.

2. Revoke it in the console. Open the agent from the Agents page and choose Revoke agent. Its token stops working immediately.

Before you confirm, the console shows how many monitors check from this agent. A monitor that used only this agent turns unknown, and one that also uses other locations keeps running from those (see When an agent goes offline).

If an agent just seems stuck, look at its log first: docker logs <container-name> for Docker, or journalctl -u culipulse-agent for a native install.