Concepts

Instance

One installation of xvii on one domain. It has one control plane server (the platform services, PostgreSQL, Caddy) and any number of nodes for apps. People have accounts on an instance; an instance has superusers (who administer it) and users.

Teams

Everything belongs to a team: deploys, apps, secrets, monitors, keys. Every person has a personal team; shared work goes into teams with members:

Role	Can
viewer	see the team's resources
developer	create, deploy and change them; read and write unprotected environments
admin	also protected environments, members, tokens of the team, settings
owner	also delete the team and change owners

Members are invited by account name or e-mail, or with a one-time invitation link for someone who has no account yet.

Projects and environments

A project groups what belongs together across services: a pages alias, an app, its database and secrets, monitors, an error project, an analytics site. Each project has environments, production and preview to start with; more can be added. An environment can be protected: only admins change what is deployed or stored there.

instance
└── team                  members with roles, limits
    └── project           shared by every service
        └── environment   production, preview, …
            └── resource  a deploy, an app, a secret set, a monitor, …

home shows one project across every service on a single page.

There are no passwords. People sign in at id with passkeys, and one passkey works for the whole instance. Panels redirect to id; the CLI uses a device code you confirm in the browser. A lost device is recovered with a one-time sign-in link from a superuser.

Tokens

For scripts and CI there are API tokens (xv_…), personal or a team's:

Scope	Allows
`read`	reading
`deploy`	reading and deploying (pages deploys, app releases)
`write`	everything the owner may do

A token can be narrowed to some services and one project, and has a lifetime (90 days by default).

xvii tokens create gitlab-ci --scope deploy --ttl 30d

CI jobs of GitLab and GitHub don't need stored tokens at all: a trust rule in the project lets the job trade its own OIDC token for a short-lived one. See Deploy from CI.

Limits and plans

Superusers define plans (bundles of limits such as pages.storage or apps.memory) and give them to teams, with overrides per team. Team admins can cap a project inside its team. Services say which limit stopped an action: "the team's plan Free allows 100 deploys". See Limits.

Nodes

Servers that run apps. A node's agent dials out to the control plane, so nodes can be anywhere. A node is either an instance node (shared between teams with memory quotas) or a team's own. It serves its apps' traffic itself (edge) or through the control plane (relay). See Nodes.

Events and activity

Every change through any API is recorded in the service's journal (who, what, team, IP) and sent to notify as an event. home shows the activity of every service; notify delivers the events people subscribed to. See Events.