Monitoring
Uptimy Agent
An open-source monitor that runs inside your network. Install it, optionally connect it to Uptimy Cloud, and import what you already have.
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 runsMonitors 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.yamlA 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/agentOpen 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-namespaceLabel 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. The Railway guide covers its variables and goes from deploy to a monitored project.
Render
Deploy the Render Blueprint to your workspace. It runs on a Starter instance with a disk and a generated password, and reaches private services and databases in the same region over Render's private network. The Render guide goes from deploy to imported services.
Dokploy
In a Dokploy project, choose Create Service → Template and pick Uptimy Agent. It comes with a volume, a generated password and a domain, and checks your Dokploy databases over the server's internal network. The Dokploy guide goes from deploy to a published status page.
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.
- In the agent, open Settings → Uptimy Cloud and click Connect to Uptimy Cloud.
- Sign in to Uptimy (a free account works), pick a workspace and approve.
- 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, 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:
| Free | Starter | Growth | Scale | Enterprise |
|---|---|---|---|---|
| 1 | 2 | 5 | 10 | Custom |
Agent monitors are free
Import from Railway
- In Railway, create a project token under Project → Settings → Tokens.
- In the agent, open Settings → Import from Railway and paste it.
- 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 Render
- In Render, create an API key under Account Settings → API Keys.
- In the agent, open Settings → Import from Render and paste it.
- Review the monitors and import.
Every service the key can see becomes a monitor:
- Web services and static sites: an HTTP check at the custom domain or
onrender.comaddress. When the agent runs on Render in the same workspace and region, you can switch a paid web service to its private address. - Private services: an HTTP check over Render's private network, when the agent runs next to them.
- Cron jobs: a heartbeat on the job's schedule, in UTC.
Background workers have no address to check. The key is only used for the import and isn't stored. In Uptimy Cloud, the Render integration adds deploy events and automatic restarts.
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: