---
title: Organisation settings
description: The Settings area of the Venom Cloud console - plan and billing, backup and restore, compliance packs, webhooks, the public status page and public session links.
section: cloud
order: 88
audience: [operator]
sources: [services/nodejs-cloud/app/(console)/(shell)/settings, "services/nodejs-cloud/app/status/[slug]/page.tsx", "services/nodejs-cloud/app/share/[token]/page.tsx", services/nodejs-cloud/lib/backup, services/nodejs-cloud/lib/compliance, services/nodejs-cloud/lib/webhooks, services/nodejs-cloud/lib/status-pages, services/nodejs-cloud/lib/billing/plans.ts, services/nodejs-cloud/lib/billing/addons.ts]
features: [cloud.console-settings, cloud.page-status, cloud.page-share, cloud.api-admin-licenses, cloud.api-license]
---

Settings holds everything about the organisation itself. `/settings` (General) shows the organisation's name (owners and admins can rename it there: only the display name changes, never the id, slug, keys or join tokens, and the name must be unique) and id, your role, the plan, the first-run checklist and the way to switch to another organisation. The other sections are in Settings' sub-navigation.

| Page | Permission to view | What |
|---|---|---|
| `/settings` | `org:read` | General: name (rename with `org:manage`), id, your role, plan, first-run checklist, switch organisation. |
| `/settings/members` | `members:read` | Members, invitations and roles. Covered with organisations and roles in this section. |
| `/settings/org-teams` | `org:read` | The organisation's teams and subteams, their members and roles, private teams; who manages a team is decided per team. See [Teams](/docs/cloud/teams.md#settings). |
| `/settings/teams` | platform operator | Organisations (tenants) and their key groups on this deployment (a key group holds API keys, daemons, policies and GPU grants, not people). |
| `/settings/keys` | `keys:read` | Client API keys (`vck_…`). Covered with keys in this section. |
| `/settings/key-rotation` | `providers:read` | Rotation schedule for provider and API keys, and every key against it. |
| `/settings/sso` | `sso:read` | Single sign-on (OIDC, SAML) and SCIM. Owners change it. |
| `/settings/logging` | `org:read` | Data & logging: what is kept about requests and for how long. |
| `/settings/audit-export` | `audit:read` | Export the audit log to your own S3-compatible bucket. |
| `/settings/msp` | `org:read` | Managed services: partners you let in. See [MSP mode](/docs/cloud/console-msp.md). |
| `/settings/billing` | `billing:read` | Plan and flat fee, metered usage, limits, Stripe checkout and portal, included products. |
| `/settings/backup` | `org:manage` | Download the configuration as JSON, restore it here or in another org. |
| `/settings/updates` | `org:manage` | Self-hosted only: the servers' versions, Check now, Upgrade now, Roll back, automatic updates and the history. See [Update a self-hosted Venom Cloud](/docs/deploy/updates.md). |
| `/settings/server-backups` | `org:manage` | Self-hosted only: scheduled backups to the servers' disk or your bucket, verify restore and a full export. See [Back up a self-hosted Venom Cloud](/docs/deploy/server-backups.md). |
| `/settings/compliance` | `org:manage` | Download a signed ZIP of audit evidence for a period. |
| `/settings/status-page` | `org:read` (change: `org:manage`) | Your public status page, incidents and changelog. |
| `/settings/webhooks` | `audit:read` (change: `org:manage`) | Your endpoints for organisation events, and the delivery log. |

Members, keys, key rotation, single sign-on, logging and the audit export have their own pages in this section ([overview](/docs/cloud.md)). The rest are below.

## Billing {#billing}

Venom Cloud charges each organisation a flat platform fee and meters what costs money to run. It never charges per seat: adding a person or an agent does not change the bill (ADR 0063).

`/settings/billing` shows the plan and its fee, this month's metered usage by meter, the price of outcomes, usage against the plan's limits and the products the plan includes. There is no seat count. With `billing:manage` (owners and the billing role) it offers **Choose a plan** (Stripe Checkout, annual or monthly) and **Manage billing** (Stripe's customer portal).

| Plan | Fee (billed annually) | Built for | Limits |
|---|---|---|---|
| `community` | $0 | self-hosted, any size | 2 daemons, 3 provider keys, 10,000 requests a month, no platform keys |
| `team` | $249 a month | up to 25 people | none; platform keys metered |
| `business` | $749 a month | up to 150 people | none; several workspaces, longer audit retention, priority support |
| `enterprise` | from $1,999 a month | above 150, regulated | set in the contract; dedicated deployment |

Monthly billing costs 20% more. The sizes are fair-use bands, not seats: no per-person charge and no block, and an organisation past its band is asked to move up at renewal. Agents never count. `free` is the old name of `community` and still reads.

Usage that Venom supplies (inference and compute on its keys or the managed public mesh) is metered at the published rate card; traffic on your own keys and daemons has no markup. A Support conversation resolved by an approved AI reply is an outcome priced at $0.49. Deployment management (BYOC from $999 a month, private or on-premises from $2,500) is priced on its own, on top of the plan.

Hitting a limit answers `403 plan_limit_reached` (with an upgrade link) when creating a join token, enrolling a daemon or adding a provider key, and `429 plan_request_limit` on inference once the monthly request cap is reached. People are never limited. Public-pool daemons don't count. A past-due or cancelled subscription keeps the paid plan until the period ends; then the Community limits apply and nothing is locked or deleted.

A deployment without `STRIPE_SECRET_KEY` has no billing: the page says so, every organisation is treated as `team` with no limits and no metering. That is how a self-hosted cloud behaves.

### Products {#addons}

Every product (Notes, Tasks, Flags, Incidents, Forms, Experiments) is included in Team and up; nothing is sold per seat any more. A feature on a plan without the product answers `403 addon_required` with an `upgrade_url`.

- An organisation that bought a product per seat before keeps it on Community and sees a **Remove** button for the old charge: it deletes the subscription item with a prorated credit. Moving the subscription to a flat plan price also ends the per-seat items.
- The platform operator can grant a product to any organisation by hand (status `manual`, no subscription needed).
- Every change is in the audit log as `billing.addon_changed`.

### Licences for paid self-hosted plans {#license}

A paid plan on a self-hosted install runs on a signed license file (Ed25519, valid offline up to 365 days, a warning for the last 30). On expiry paid features drop to Community and every byte of data stays readable and exportable. The verifier checks against the public key built into the release and any key in `VENOM_LICENSE_PUBKEY`. See ADR 0063.

On a self-hosted install, **Settings, Billing** has a License card: upload the `.json` file (or paste it), see its plan, id, expiry and state, replace or remove it. A bad file (wrong signature, expired, lifetime over a year) is refused and changes nothing. With no license installed the install runs as it always did. Thirty days before expiry a banner asks you to renew; on expiry the install drops to Community limits, and nothing is locked or deleted. The card does not exist on the hosted deployment, whose plan comes from billing.

**The daily online check.** Only when a paid license is installed, at most once a day, the install sends the license id and the version to the license server (`VENOM_LICENSE_SERVER_URL`) and nothing else, to learn whether the license was revoked. A revoked license keeps working for 14 days with a banner. An air-gapped install sets `VENOM_LICENSE_CHECK=off`: it never makes the call and the license stays valid offline until its expiry. If the server cannot be reached nothing changes.

**For agents.** The MCP tool `workspace_license_get` (REST `GET /api/v1/license`, console `GET /api/workspace/license`) reads the status. Uploading is human-only: it is the commercial act of whoever runs the install.

**Issuing (Venom operators).** `POST /api/admin/v1/licenses` with the admin token and `{org, plan, days, limits?}` signs a license with `VENOM_LICENSE_SIGNING_KEY` (an Ed25519 private key in PEM, from the environment; make one with `cd services/nodejs-cloud && bunx --no-install tsx scripts/license-keygen.ts`) and returns the file once. `GET /api/admin/v1/licenses` lists them and `DELETE /api/admin/v1/licenses/{id}` revokes one. Set `VENOM_CLOUD_VERSION` to change the version string the check reports. The hosted cloud answers the installs' check at `POST /api/license/status`, which reads only the license id.

## Backup and restore {#backup}

`/settings/backup` exports the organisation's configuration as one versioned JSON file (`venom-backup-<org>-<date>.json`, at most 2 MiB) and restores it into the same or another organisation, with a dry-run diff first. Owners and admins only; including members needs `members:read` to export and `members:manage` to restore.

The file holds, in restore order: key groups (`teams`), members (optional), settings, gears, routing, trusted public daemons, model allowlists, filters, customers, budgets, library, memory, experiments, marketplace listings, alerts and saved queries, webhooks, integrations, autoscaling pools, single sign-on and permission profiles. It never holds provider keys, GPU cloud keys, integration tokens, webhook secrets, the OIDC client secret, SCIM tokens, API keys, customers' portal links, the Stripe key, signing keys, logs, usage, invoices or request bodies. The file's `reenter` list names what you will need to enter again (never a value).

To restore: pick a file (checked in the browser), choose sections, choose keep or replace for items that differ, and click **Preview changes**. Each item is listed as create, update or skip with the reason. **Restore** applies the plan in one transaction and never deletes anything. Webhooks come back disabled with new secrets, integrations `pending`, single sign-on off and not required, pools off; a running experiment comes back stopped if another runs. Customers need `billing:manage` and single sign-on needs `sso:manage`; without them those sections are skipped. The last 10 backups and restores are listed from the audit log.

The CLI does the same with a key created by an owner or admin:

```bash
venom cloud backup > backup.json
venom cloud restore backup.json            # dry run: prints the plan
venom cloud restore backup.json --apply --sections gears,routing
```

## Compliance pack {#compliance}

`/settings/compliance` builds one ZIP of evidence for an audit over a period: a preset (last 30 or 90 days, last month, this or last quarter, this year) or two UTC days, inclusive, at most 366 days. It contains a self-contained `summary.html`, members and key groups, keys (never the key), spend by model, key, member and day, models and model access, provider keys (never the secret), the controls in place, control changes with before and after, the redacted audit log (up to 50,000 rows), sign-in and retention settings, incidents, signed session shares, a `manifest.json` with every file's SHA-256, and `signature.json`: an Ed25519 signature over the manifest by the organisation's policy-signing key (else the deployment's). Check it with `venom compliance verify`. Without any signing key the download answers `503 policy_signing_not_configured`. The last packs downloaded are listed from the audit log.

## Webhooks {#webhooks}

`/settings/webhooks` sends organisation events to your own HTTPS endpoints. Add an endpoint with its URL and the event types it takes; the signing secret (`vwh_…`) is shown once on create or rotate. Per endpoint: **Send test**, enable or disable, **Rotate**, delete. The delivery log has a state filter and **Retry**.

Event types: `spend_cap.warning`, `spend_cap.reached`, `budget.warning`, `budget.reached`, `spend.threshold`, `spend.forecast`, `spend.anomaly`, `chargeback.statement`, `key.expiring`, `key.expired`, `key_rotation.due`, `key_rotation.overdue`, `key_rotation.completed`, `model.retiring`, `price.changed`, `credits.expiring`, `sla.breach`, `sla.credit_drafted`, `daemon.offline`, `daemon.online`, `prompt_filter.blocked`, `prompt_filter.response_blocked`, the `autoscale.*` machine events, Venom Tasks' `tasks.issue.*` and `tasks.comment.created`, the `globe.note.*` and `globe.team_note.*` events of Venom Notes (see [Webhooks for issues and notes](/docs/cloud/workspace-mcp#webhooks)), Experiments, Flags, People, Funnel, Chat, Teams, the status page and the other products' events (the full list is in [Webhooks and events](/docs/developers/webhooks)), and `webhook.test`. A new endpoint's form ticks every event except the busy or more private ones (`chat.message.created`, `people.person.*`, `globe.team_note.*`), which you tick on purpose.

Each delivery is a POST with `content-type: application/json` and the headers `venom-signature: t=<unix>,v1=<hex>` (HMAC-SHA256 of `<t>.<body>` with the secret), `venom-event`, `venom-event-id` and `venom-delivery`. The body is `{id, type, created_at, org: {id}, data, links}`: ids, names, numbers and console links, never a key or request content. A 2xx is delivered; anything else retries after 1, 2, 4 … 128 minutes with jitter (9 attempts, about 4 h 15 min), then fails. Treat `venom-event-id` as the idempotency key: a delivery can arrive twice.

Verify a delivery:

```ts
import { createHmac, timingSafeEqual } from "node:crypto";

export function verify(secret: string, header: string, body: string, toleranceS = 300): boolean {
  const parts = Object.fromEntries(header.split(",").map((p) => p.split("=") as [string, string]));
  const t = Number(parts.t);
  if (!t || Math.abs(Date.now() / 1000 - t) > toleranceS) return false;
  const want = createHmac("sha256", secret).update(`${t}.${body}`).digest("hex");
  return want.length === parts.v1?.length && timingSafeEqual(Buffer.from(want), Buffer.from(parts.v1));
}
```

URLs must be HTTPS with no credentials and resolve to public addresses (checked on save and before every delivery); redirects are not followed; 5 s timeout. Events and deliveries are kept 30 days.

## Public status page {#status-page}

`/settings/status-page` publishes a status page at `/status/{slug}` for the people who use your models. It is off until you enable it; while off, the address answers 404.

| Field | Rule |
|---|---|
| `slug` | 3 to 40 lowercase letters, digits and inner hyphens, unique across organisations |
| Title, description | Free text |
| Support URL | HTTPS only |
| Components | Model ids as clients request them, each with a public name; at most 30 |
| Automatic incidents | On by default |

Uptime comes from your own request log: 30 daily bars and the window's uptime per listed model, and its level now from the last 15 minutes. Rate limits, 5xx and timeouts count against a model; a client's own 4xx doesn't. With automatic incidents on, a model that is down or degraded opens an incident ("Elevated errors on …"), resolved when it serves 3 requests in 15 minutes without failing or after 2 hours without traffic; an incident you moved past `investigating` is yours to resolve.

Manual incidents have a title, impact (minor, major, critical), status (investigating, identified, monitoring, resolved), affected components, published or hidden, and dated updates; a status change needs a message. Changelog entries are written by you, optionally from one of your own gear and model change audit rows, with a suggested wording that names gears only.

Uptime checks, maintenance windows, groups, subscribers, the RSS and Atom feeds, the badge and the incident history are in [Status page uptime checks, maintenance and subscribers](/docs/cloud/status-page.md).

The public page shows your logo and colour from customer branding and is cached 60 seconds. No actor, key, provider, daemon, price, request volume or setting reaches it. Removing the page frees the address.

## Public session links {#share}

A session shared with `venom session share` is visible to your organisation in the console. With **public links** turned on under Data & logging (off by default), someone with `org:manage` can make one public link per share: `/share/{token}`, where the token starts `vss_`, shown once, valid 1 to 7 days by default (at most 30) and never past the share's own expiry. The page needs no sign-in, is read-only, shows no comments or names, and is not indexed; `?view=replay` opens the replay debugger on the trace alone. A new link replaces the old one, and turning public links off ends every link at once. Each view is audited as `session_share.public_viewed`.

## Admin over MCP {#mcp}

The console's admin pages are being opened to agents one area at a time as **Venom Admin**: `claude mcp add --transport http venom-admin <your cloud>/workspace/mcp/admin`. Every tool calls the same function as the console action, so your member role decides what an agent may do and each change is in the audit log with the agent as actor. A connection needs `admin:read`, and `admin:write` to change anything; an app that names no scope never gets them, and a team key (no member) is refused.

| Area | Tools |
|---|---|
| Organisation | `admin_org_update` |
| Members | `admin_member_list`, `admin_member_update`, `admin_member_remove`, `admin_invitation_create`, `admin_invitation_delete` |
| Spend budgets | `admin_budget_list`, `admin_budget_create`, `admin_budget_update`, `admin_budget_delete` |

Each has a REST twin under `/api/v1/admin/…`. The owner role stays a person's decision: no tool grants it, changes it or removes an owner. Signing in, creating an organisation, approving a device login and cutting off a connected app are human-only too. The rest of the admin pages (providers, routing, SSO, guardrails, integrations and others) are listed in `agents-capabilities` until their tools ship.

## Troubleshooting {#troubleshooting}

| Symptom | Cause and fix |
|---|---|
| Billing page has no buttons | The deployment has no Stripe (`STRIPE_SECRET_KEY`), or you lack `billing:manage`. |
| A product answers `addon_required` | The organisation is on Community: every product is included in Team and up. |
| Restore skips a section "needs billing:manage" or "sso:manage" | Ask an owner to run the restore. |
| Compliance download answers 503 | No policy-signing key. Create one from the MCP page or set `VENOM_POLICY_SIGNING_KEY` on the deployment. |
| Webhook URL refused on save | It is not HTTPS, has credentials, or resolves to a private address. |
| `/status/{slug}` answers 404 | The page is disabled or the slug is different. |
| A `/share/{token}` link stopped working | It expired, was replaced, or public links were turned off. |

## Related

- [Customers](/docs/cloud/console-customers.md) for branding used by the status page and portal.
- [Self-hosting Venom Cloud](/docs/cloud/self-hosting.md) for `STRIPE_*` and `VENOM_VAULT_KEYS`.
