Skip to content
Docs menu

Link a self-hosted install to Venom for managed service

Connect a self-hosted Venom Cloud to Venom's management plane with a one-time code, read exactly what its hourly heartbeat sends, disconnect at any time, and how Venom's operators see linked installs.

View .md

If Venom manages your self-hosted install (the BYOC and private managed plans), the management link lets Venom see the install's health and versions so it can plan upgrades with you. It never shows Venom your data. The link is off until an owner or admin of the install turns it on, and you can turn it off at any time. The design is ADR 0080.

You don't need the link for a paid plan. A paid plan needs its license file, and the link is a separate choice.

Connect

  1. Venom sends you a one-time enrollment code. It starts with vfe_, works once and expires after 7 days.
  2. On your install, open Settings → Management link (/settings/management-link). You need to be an owner or admin.
  3. Read What is sent. It shows the exact report the install would send right now.
  4. Paste the code and press Connect.

The install exchanges the code for its own link key (vfl_…). The key is sealed with the install's vault key (VENOM_VAULT_KEYS), and Venom keeps only a hash of it. The first heartbeat goes out straight away, then one every hour from the install's own scheduler. Connecting and disconnecting are written to your audit log as managed.link_connected and managed.link_disconnected.

The link is outbound only. Your install calls Venom, and Venom never calls your install. You don't need to open a port, a VPN or a tunnel, and Venom holds no credential that opens anything on your install.

What is sent

One JSON object, venom-managed/1, every hour:

Field What it holds
version the release the install runs
health whether the database answered, how many migrations are applied and the newest one's name, how many servers are reporting, and the last backup's and verify restore's time and result
servers for each app server: server-1, server-2, … (never its host name), its version, and whether and when it last reported
storage the database size, the data disk's total and free bytes, and the last backup's size
updates whether automatic updates are on, the level, the channel and your maintenance window
upgrades your last 10 upgrades, rollbacks and restores: when, from and to which version, and whether each one worked

It never sends:

  • content: prompts, responses, notes, messages, files or People records
  • keys, tokens or passwords
  • user names, emails, org names or member counts
  • host names, file names or log text
  • audit log rows

The report is built from the install's operational tables only. Venom's side also keeps only these fields and drops anything else.

Disconnect

Press Disconnect on the same page. The link key is deleted from the install at once, so the next hour sends nothing. Venom is told once that you disconnected, so its operators see "disconnected by the customer" rather than an outage. Every feature keeps working. Nothing on the install depends on Venom's servers being up.

If Venom revokes the link, the next heartbeat is refused and the install stops sending. The page then shows revoked by Venom. To link again, disconnect and connect with a new code.

An air-gapped install never uses the link. It updates from an offline bundle.

Settings

Setting What it does
VENOM_MANAGEMENT_URL Where the link connects. Defaults to https://cloud.usevenom.dev. It only accepts https addresses, or http on loopback for tests
VENOM_VAULT_KEYS Needed to keep the link key sealed. The installer sets it; without it, Connect is refused

For Venom's operators

Managed installs (/installs in Venom Cloud's console) lists every linked install: its state, version, servers reporting, database size, free disk, the last upgrade's result and when it was last seen. Only Venom Cloud operators can open it. Org members, partners and MSPs never see it.

  • Add install: name it (for example the customer and the environment). You get the enrollment code once. Send it to the customer's owner or admin.
  • Revoke: the link key and any unused code stop working at once. The install keeps running and stops sending at its next heartbeat.

The machine endpoints are POST /api/managed/v1/enroll (the code, returns the link key once), POST /api/managed/v1/heartbeat and POST /api/managed/v1/unlink (both with Authorization: Bearer vfl_…; a revoked key gets 410).

Coming next

Venom will be able to schedule an upgrade in your maintenance window if you allow it. Your servers still pull the signed release and check it themselves, as they do for updates. Support sessions will be granted by your owner or admin, limited in scope and time, and never open content. Both are described in ADR 0080 and are not built yet.