---
title: Link a self-hosted install to Venom for managed service
description: 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.
section: deploy
order: 49
audience: [operator]
sources: [docs/adr/0080-byoc-management-plane.md, services/nodejs-cloud/lib/managed/pure.ts, services/nodejs-cloud/lib/managed/link.ts, services/nodejs-cloud/lib/managed/server.ts, "services/nodejs-cloud/app/(console)/(shell)/settings/management-link/page.tsx", "services/nodejs-cloud/app/(console)/(shell)/installs/page.tsx", services/nodejs-cloud/app/api/managed/v1/enroll/route.ts, services/nodejs-cloud/app/api/managed/v1/heartbeat/route.ts, services/nodejs-cloud/app/api/managed/v1/unlink/route.ts, services/nodejs-cloud/migrations/0271_managed_installs.sql]
features: [cloud.api-managed, cloud.console-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](https://github.com/elishahbiz/venom/blob/main/docs/adr/0080-byoc-management-plane.md).

You don't need the link for a paid plan. A paid plan needs its [license file](/docs/deploy/self-host-cloud), 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](/docs/deploy/updates).

## 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](/docs/deploy/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.
