Guides
Deploy Uptimy Agent on Render
Deploy the agent to your Render workspace from the Blueprint, sign in, and monitor your services, private services, databases and cron jobs. About five minutes.
Uptimy Agent or Uptimy Cloud?
Overview
Uptimy Agent is an open-source monitor (Apache-2.0, on GitHub) with its own UI, alert channels and public status page, and no account needed. Running on Render, it checks:
- Web services and static sites, at their custom domain or
onrender.comaddress. - Private services, which have no public address, over Render's private network.
- Render Postgres and Key Value, by logging in and running a query, so a full connection limit or a rejected password is caught too.
- Cron jobs, as heartbeats that alert when a run doesn't check in.
What the Blueprint deploys
| Service | A web service uptimy-agent from the image ghcr.io/uptimy/agent:latest, on a Starter instance |
| Disk | 1 GB, mounted at /data. The agent keeps everything here in one SQLite database: monitors, history, settings and users. |
| Health check | /healthz |
| Instances | 1. SQLite has a single writer, and a service with a disk can't scale out anyway. |
| Variables | ADMIN_USERNAME=admin and ADMIN_PASSWORD, generated once when the Blueprint is created. |
Why a paid instance
1. Deploy the Blueprint
Click Deploy to Render above, pick the workspace, and click Deploy Blueprint. Render asks for a payment method if the workspace has none.
The deploy takes about a minute. Render marks the service live once /healthz answers.
Region
2. Sign in
Open the service's onrender.com address. Sign in as admin with the value of ADMIN_PASSWORD from the service's Environment page.
While ADMIN_PASSWORD is set, that password is managed in Render, not in the agent: change the variable and save to deploy a new one. That's also how you get back in after losing it.
Add the people who need access under Users, as admins or viewers. Each of them can turn on two-factor sign-in under Account.
3. Add an alert channel
Under Notifications, add a channel: Slack, Discord, Teams, Telegram, email, ntfy, PagerDuty, a webhook, or one of 30+ more through Shoutrrr. New channels alert for every monitor, including the ones you add later, so one channel is all the alerting setup you need.
4. Import your Render services
- 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, across your Render workspaces, becomes a monitor:
- Web services and static sites: an HTTP check at the custom domain or
onrender.comaddress. A paid web service in the agent's workspace and region can be switched to its private address in the review. - Private services: an HTTP check over the private network, when they're in the agent's workspace and region.
- Cron jobs: a heartbeat on the job's schedule, in UTC like Render runs it. Add
curl -fsS <ping URL>as the job's last step. The heartbeat's page shows the ping URL.
Background workers have no address to check, and suspended services are skipped. The agent doesn't import itself. The key is only used for the import and isn't stored, and importing again skips services already imported.
Free services
5. Check your databases
The import doesn't list Render Postgres or Key Value. Add them as database checks, with the connection URL kept in Render rather than in the agent's database:
- On the database's page in Render, copy the Internal connection URL. The database has to be in the agent's region.
- On the agent's Environment page, add it as a variable, for example
POSTGRES_URL, and save. - In the agent, add a Postgres check with the target
${POSTGRES_URL}. For Key Value, add a Redis check the same way.
The agent reads the variable when the check runs, so the password never reaches its database.
6. Publish the status page
Under Status page, add the monitors visitors should see. It's public at /status on the agent's address and never shows targets or internal hostnames. To serve it on a domain such as status.example.com, add the domain under the service's Settings → Custom Domains in Render, then enter it under Status page → Custom domain in the agent. That domain serves only the status page, so sign-in stays on the onrender.com one.
When the agent itself goes down
A monitor inside Render can't report that Render, or the agent, is down. In the agent, Settings → Uptimy Cloud connects it to a free Uptimy account. The agent uploads its results every minute (every 5 minutes on Free), and Uptimy alerts you from outside when the uploads stop. Its monitors show up in your workspace for status pages, SLA reports and workflows, without counting toward your plan's limits. See Connect to Uptimy Cloud.
Updating
The Blueprint runs the latest image. Render pulls it again when you click Manual Deploy → Deploy latest reference. The database is migrated on start. To stay on one version, change the image to a tag from the releases, such as ghcr.io/uptimy/agent:0.3.2.
Troubleshooting
- A private check fails but the public address works: the service has to be in the agent's workspace and region, and on a paid instance. Check the internal hostname and port on the service's Connect menu.
- A database check says a variable isn't set: add it on the agent's Environment page and save.
- Checks pause during a deploy: a disk attaches to one instance, so Render stops the old one before starting the new one. Expect under a minute.
- The admin password doesn't work: it's the current value of
ADMIN_PASSWORD. Set a new one there and save.
Next steps
- Connect Render to Uptimy Cloud: deploy events as incidents and automatic restarts
- Uptimy Agent docs: other installs, importing from Uptime Kuma, and the full reference
- Every check type and heartbeat setting