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?

This guide runs the open-source Uptimy Agent inside your Render workspace, to check private services and databases. To check your public services from outside Render, turn failed deploys into incidents and restart services automatically, see Connect Render to Uptimy Cloud. The two work together.

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.com address.
  • 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.

Deploy to Render

What the Blueprint deploys

ServiceA web service uptimy-agent from the image ghcr.io/uptimy/agent:latest, on a Starter instance
Disk1 GB, mounted at /data. The agent keeps everything here in one SQLite database: monitors, history, settings and users.
Health check/healthz
Instances1. SQLite has a single writer, and a service with a disk can't scale out anyway.
VariablesADMIN_USERNAME=admin and ADMIN_PASSWORD, generated once when the Blueprint is created.

Why a paid instance

Disks need a paid instance, and free web services sleep when idle, which would stop the checks. The Blueprint uses Starter, Render's smallest paid instance, which is plenty: the agent idles at a few MiB of memory.

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

The Blueprint doesn't set a region, so Render creates the service in Oregon. Private addresses only work within one workspace and region. If your services run elsewhere, create the web service by hand in their region with the settings above, or check them at their public addresses.

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

  1. In Render, create an API key under Account Settings → API Keys.
  2. In the agent, open Settings → Import from Render and paste it.
  3. 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.com address. 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

Free web services can't receive private network traffic, so they're always checked at their public address.

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:

  1. On the database's page in Render, copy the Internal connection URL. The database has to be in the agent's region.
  2. On the agent's Environment page, add it as a variable, for example POSTGRES_URL, and save.
  3. 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