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