Uptimy Agent

Overview

Uptimy Agent runs next to your services, so it checks what an outside monitor can't reach: private APIs, databases with a real login and query, Kubernetes workloads and cron jobs. It has its own UI, alert channels and status page, needs no account, and is Apache-2.0 on GitHub.

healthchecks:
  - name: API
    type: http
    target: http://api.railway.internal:8080/health   # private networking
  - name: Database
    type: postgres
    target: ${DATABASE_URL}                           # logs in and runs a query
heartbeats:
  - name: Nightly backup
    cron: "0 3 * * *"                                 # alerts on missed or failed runs

Monitors can come from the UI, from YAML, or from Kubernetes labels. A mistake in monitors.yaml doesn't stop the agent: the rest is applied and the error is shown. Check the file in CI with:

docker run --rm -v "$PWD:/w" ghcr.io/uptimy/agent validate /w/monitors.yaml

A channel that's down is retried for up to an hour; alerts arrive in order and survive restarts. Channels can remind you while a monitor stays down, and Acknowledge stops the reminders.

Install

Docker

docker run -d --name uptimy-agent -p 8080:8080 \
  -v uptimy-agent:/data ghcr.io/uptimy/agent

Open http://localhost:8080 and sign in as admin with the password from docker logs uptimy-agent.

Kubernetes

helm install uptimy-agent oci://ghcr.io/uptimy/charts/uptimy-agent \
  -n monitoring --create-namespace

Label Services, Deployments and CronJobs with upti.my/monitor=true and they're monitored. The Kubernetes guide goes from install to the first alert.

Railway

Deploy the Railway template into your project. It comes with a volume and a generated password, and reaches your *.railway.internal services and databases over private networking.

Connect to Uptimy Cloud

Nothing inside a server or cluster can tell you it's gone. Connecting the agent to Uptimy covers that, and puts its monitors next to the rest of your workspace.

1. In the agent, open Settings → Uptimy Cloud and click Connect to Uptimy Cloud.
2. Sign in to Uptimy (a free account works), pick a workspace and approve.
3. The agent adds itself to the workspace as a private location and starts uploading results.

What you get:

• Alerts from outside. Every upload checks the agent in. If uploads stop, Uptimy alerts you, by default after two missed uploads. Uploads run every minute (every 5 minutes on Free).
• Its monitors in Cloud. Every healthcheck and heartbeat shows up read-only with status, uptime and history, for status pages on your own domain, SLA reports, alert rules, workflows and on-call. Change them in the agent and Cloud follows.
• The agent decides. It keeps checking and alerting on its own; Cloud records the status it decided. Passwords and tokens in targets are masked before anything is sent.

Connected agents per workspace:

Import from Railway

1. In Railway, create a project token under Project → Settings → Tokens.
2. In the agent, open Settings → Import from Railway and paste it.
3. Review the monitors and import.

Every service becomes a monitor:

• Web services: an HTTP check over private networking (*.railway.internal) when the agent runs in the same project, otherwise at the public domain.
• Postgres, MySQL and Redis: a database check.
• Cron services: a heartbeat.

The token is only used for the import and isn't stored. Importing again skips services already imported.

Import from Uptime Kuma

Under Settings → Import from Uptime Kuma, upload Kuma's kuma.db and see what each monitor and notification becomes before anything is imported. HTTP, keyword, TCP, ping, DNS, TLS, database and push monitors carry over, with notifications and status page membership. Uptimy Agent vs Uptime Kuma compares the two.

Reference

The full reference lives with the code: