Manual

Users and access

An Account is an hv identity, distinct from a dom0 root login or an operating-system login inside a VM. Accounts and Groups belong to a Silo. Before granting access, decide whether the person needs one Project, every Project in a Silo or Fleet infrastructure. Keep a working administrator session while testing changes.

Grant the appropriate role

Use Project access for Project members, Silo access for Silo-wide access and System, Fleet access for infrastructure roles. A Group contains Accounts from its own Silo. Review the subject and target before saving a grant.

A wider grant may allow an action even if the Project membership is narrower. API-token scopes can further restrict rights. Test with the intended Account rather than assuming an administrator's view proves the member's access.

Give a team access to production

Suppose one colleague needs to inspect web-01 and another needs to create and operate VMs in production. Confirm first that their Accounts belong to the same Silo as the Shared project. Open Project access on production, select the intended Accounts or Group, and grant Viewer to the person who only reads and Collaborator to the person who operates workloads. Reserve Project Admin for someone who must also manage membership and the Project.

Check the selected Project and subject before saving. Similar usernames in different contexts should not be treated as interchangeable identities. If the team already has a Group in this Silo, a Group grant can express the shared requirement without repeating individual grants. Review the Group's membership as part of the access decision.

Test each result in the member's own session. The viewer should be able to inspect the Project without gaining workload-management rights from this grant. The collaborator should be able to perform the intended Project work, but this does not grant Host maintenance or live migration. If either Account can do more than expected, inspect its Silo and Fleet roles as well as the Project grant; a narrower Project role does not cancel broader rights.

If web-01 is missing altogether, check the acting Silo, Project membership and ownership before changing infrastructure visibility. If the VM is visible but an operation is refused, identify that operation's permission. Granting Fleet administration to solve every refusal would give the team control beyond its stated task. See Projects for visibility and quota checks that are separate from roles.

Protect sign-in

Open Settings, Security to enroll a TOTP authenticator. Confirm its current code and preserve the recovery codes displayed once. Each recovery code works once. Fleet administrators can require a second factor using System, Settings, Security, Require a second factor for Fleet roles. Silo policy can require it for members. Neither install profile requires it by default.

When required enrollment has no active second factor, a Fleet administrator issues an enrollment code through the supported Account workflow. Resetting another Account's second factor ends its sessions and revokes its API tokens. After enabling a mandatory policy, older tokens that were not issued after second-factor verification may be refused; create replacements through an authenticated second-factor session.

Before making second-factor enrollment mandatory, enroll the administrators who will manage recovery and test a sign-in with the authenticator. Keep the recovery codes where the Account owner can retrieve them during loss of the device. Their one-time display is the opportunity to preserve them; a screenshot in a shared support conversation is not an appropriate recovery store.

After changing the policy, test the affected Account and any automation that uses its tokens. If a token is refused because it predates the required verification, issue its replacement from a properly verified session. Treat a reset of another Account's second factor as a disruptive access change: its existing sessions end and API tokens are revoked. Coordinate replacement access with the Account owner rather than assuming only the authenticator changes.

External identity providers

hv supports LDAP, OIDC and SAML sign-in. They are configured for a Silo in the orchestrator's configuration; they do not bypass roles or token scopes. LDAP requires protected transport, a correct search base/filter and stable identity mapping. OIDC needs the exact registered callback, trusted issuer and admission policy. SAML uses a pinned signing certificate, IdP/SP identifiers and its own callback, not the OIDC endpoint.

Have the identity-provider administrator prepare those values, bind the provider to the intended Silo, validate configuration and restart the service through the deployment's configuration process. Test one permitted Account, one denied Account and provider unavailability before relying on it. Automatic provisioning must use the intended Silo role; do not assume it grants Fleet administration. Keep a working administrator identity available until those checks pass.

API tokens and MCP

Create scoped tokens in Settings, Access tokens. Store the displayed value privately; it is shown once. Give an automation Account only the roles and scopes needed, and revoke unused tokens. Browser sessions and API tokens are separate.

The MCP server also uses an Account token and checks its scopes and roles. Mutation confirmation does not grant additional permission. Inspect returned Tasks to establish completion.

Common problems

For 403, inspect the action, role target and token scopes. A 404 may hide an object outside the Account's visibility. For repeated sign-in failures, check clock synchronization, provider trust and rate-limit diagnostics. Do not fix an isolated permission problem by granting global administration. Avoid removing the last useful sign-in identity or administrator path during provider changes.