Instance Settings

The Instance page (Admin → Instance) is where you tune how your Perch deployment behaves.

General

The General section shows you deployment info you can’t edit here: the hub token (tap the eye to reveal it) and the current version. The hub token comes straight from the PERCH_HUB_TOKEN environment variable, so it isn’t editable from the UI. The Sign-in methods card jumps you over to the Auth page where you set up OAuth providers.

Sessions & Security

Session expiry is how many days a login session lasts before someone has to sign in again. Defaults to 30 days. Lower it if you want tighter control over access, say for a shared or high-security setup.

Self-registration, when on, lets anyone create an account from the login page, or by signing in with an OAuth provider for the first time. When it’s off, only admins can create accounts. You can also pick the default role for self-registered accounts, either member or admin.

Login lockout blocks a user after too many failed password attempts within 15 minutes. The threshold sets how many failures it takes to trigger the lockout. It’s on by default with a threshold of 5 attempts. See Security for the full story.

Agents & Monitoring

Report interval is how often agents push metrics to the hub, in milliseconds. Defaults to 5000ms (every 5 seconds). Lower values give you fresher data at the cost of more traffic between agents and the hub.

Reconnect delay is how long an agent waits before trying to reconnect after a dropped WebSocket connection, in milliseconds. Defaults to 5000ms.

Default check interval is the starting cadence for new health checks, in seconds. Defaults to 60 seconds, and you can override it per check. Lowering it instance-wide just means new checks run more often out of the box.

Default check timeout is how long the hub waits for an HTTP response before it marks a health check as timed out, in milliseconds. Defaults to 10000ms (10 seconds). Bump it up for endpoints that are slow to respond.

Alerts

Webhook timeout is how long the hub waits for a webhook delivery to Discord, Slack, or ntfy before it gives up and logs the delivery as failed. Defaults to 10000ms.

Default cooldown is the cooldown applied to new alert rules when they’re created, in seconds. Defaults to 300 seconds (5 minutes). A cooldown stops the same rule from firing again in a short window, which keeps notification noise down.

Privacy

Geolocation, when on, makes one request to ipapi.co on startup to look up the hub’s city and country. That shows up on the Overview page as the hub’s location.

Retention

Perch runs a cleanup job once an hour and trims old records based on these settings.

Metrics history is how many days of agent metrics to keep. Defaults to 30 days.

Alert history is how many days of fired alert records to keep in the history table. Defaults to 90 days.

Health check results is how many days of ping results to keep. Defaults to 90 days.

Maintenance

Maintenance mode, when on, stops non-admin users from logging in. They’ll see an error on the login page, while admins keep full access. Reach for it during upgrades, or any time you need to take the instance down for a bit without locking yourself out.

It’s a plain toggle, not a timed window, so remember to turn it back off when you’re done.

Monitored Platforms

Right now Docker is the only platform Perch actually collects from, and it’s enabled by default. The others are listed so you can see what’s on the way, but they aren’t functional yet.

• Docker Available
• Kubernetes Coming soon
• Podman Coming soon
• Proxmox Coming soon
• Nomad Coming soon
• LXC / LXD Coming soon

Status Pages

Flip this on to enable public-facing status pages at /status/:slug. When it’s off, the Status Pages admin section disappears and any existing pages stop serving. See Status Pages to set one up.