Sign in to the console and the CLI
Sign in to the Venom Cloud console with email, GitHub, single sign-on or the operator token, create your first organisation, and approve a venom cloud login from the terminal.
The console has one sign-in page, /login, with up to four ways in. Which buttons appear depends on what the
deployment has configured. Every way leads to the same console session, and every sign-in, accepted or refused,
is written to the audit log.
| Sign-in | Shown when | Who it admits |
|---|---|---|
| Continue with email (Clerk) | CLERK_SECRET_KEY and NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY are both set |
members of an organisation; anyone else is offered to create one |
| Continue with GitHub | GITHUB_CLIENT_ID and GITHUB_CLIENT_SECRET are both set |
GitHub accounts on the deployment's allowlist |
| Sign in with SSO | any organisation has single sign-on enabled, or the URL has ?sso=1 |
members whose email is at a verified domain of an organisation with SSO |
| Admin token | always (folded under "Operator? Sign in with the admin token" when another sign-in exists) | the operator of the deployment |
On the hosted Venom Cloud, use email, GitHub or your company's SSO. The admin token is for people running their own deployment.
Create an account
- Open
/auth/clerk/sign-up(the "Create an account" link on/login) and sign up with your email. - If you belong to no organisation yet, the console sends you to
/onboarding, "Create your organisation". Enter a name of 2 to 80 characters. You become its owner, and the organisation gets adefaultkey group (a key group holds API keys, daemons, policies and GPU grants, not people; the API calls itteam). - You land on Get started (
/get-started), which walks you through a model source, a gear, the CLI and a test request. See Console home.
The onboarding ticket lasts 30 minutes. After that /onboarding sends you back to /login with "The
organisation setup expired". Sign in again to get a new one.
Invited by someone? Open the link in the invitation email instead. It goes to /auth/clerk/sign-up, and you
join their organisation with the role they picked. See Organisations, members and roles.
Sign in
/login sends you to Home (/home) after signing in, or to the page you asked for (?next=/path,
same-origin paths only). The operator without an org seat lands on /dashboard. Already signed in, /login redirects straight there.
- Email:
/auth/clerkshows Clerk's sign-in form. Once Clerk has signed you in, the page posts the Clerk session token to/auth/clerk/callback, which checks it and starts the console session. A verified primary email is required. - GitHub:
/auth/githubsends you to GitHub with a signed state and a PKCE challenge (valid 10 minutes); GitHub returns to/auth/github/callback. The GitHub token is used for the sign-in and dropped. - SSO: "Sign in with SSO" asks for your work email and posts it to
/auth/sso. The email's domain picks the organisation, and the browser goes to its identity provider. An organisation's own sign-in link is/auth/sso/start?org=<org id>. Setup is in Single sign-on and SCIM. - Admin token: paste the token. Five wrong tries from one client (or 100 overall) within 15 minutes block the form for 15 minutes.
Operator or member
An operator who signs in with email (listed in VENOM_CLOUD_CLERK_ADMINS) and is also a member of an
organisation chooses how to use the console. After the first such sign-in, /auth/choose asks:
- Continue as operator: every organisation, with the operator's rights. Your organisation's seat stays your workspace in Venom Notes and Tasks.
- Continue as Org member: only that organisation, with your role in it, exactly like any other member. No operator page, action or API route opens in this mode.
The choice is remembered on this browser (an httpOnly cookie, venom_cloud_signin_as, for a year), so later
sign-ins skip the question. Switch any time from the account menu: Use as Org member, or Switch to
operator. Switching back to the operator works only while your email or Clerk user id is still listed. Each
switch starts a new session, ends the old one everywhere, and is written to the audit log (console.sign_in,
method switch_mode; a refused switch is console.sign_in_refused). An organisation that requires single sign-on
is not offered as a member choice unless you own it. Operators with no organisation seat, the admin token, GitHub
and everyone who is not a listed operator sign in exactly as before.
A console session lasts 12 hours. Signing out ends it on every instance of the cloud. /auth/clerk/sign-out
also ends the Clerk session in this browser (use it to try another Clerk account); it then goes to /, or back
to /login with the refusal when a sign-in was refused.
Auth routes
| Route | Method | What it does |
|---|---|---|
/login |
GET | the sign-in page; ?next=, ?sso=1 (open the SSO form), ?token=1 (open the token form), ?error= |
/auth/clerk |
GET | Clerk's sign-in; 404 unless Clerk is configured |
/auth/clerk/sign-up |
GET | Clerk's sign-up; invitation emails link here |
/auth/clerk/sign-out |
GET | ends the Clerk session in the browser |
/auth/clerk/callback |
POST | form token, next: verifies the Clerk session token, picks the role, starts the session |
/auth/choose |
GET | ?next=: operator or member, for a listed operator who is also an organisation member (above) |
/auth/github |
GET | redirects to GitHub's authorize page; ?next= |
/auth/github/callback |
GET | GitHub's return: checks state and allowlist, starts the session |
/auth/sso |
POST | form email, next: finds the org by the email's verified domain, redirects to its IdP |
/auth/sso/start |
GET | ?org=<org id>[&next=]: an organisation's SSO sign-in link |
/auth/sso/oidc/callback |
GET | the OIDC redirect URI every organisation's IdP is given |
/auth/sso/saml/{tenant} |
GET | the SAML SP metadata; the URL is also the SP entity ID |
/auth/sso/saml/{tenant}/acs |
POST | the SAML Assertion Consumer Service |
/onboarding |
GET | "Create your organisation", for a signed-in Clerk user in no organisation |
/device |
GET | approve or deny a venom cloud login (below) |
Sign in from the terminal: venom cloud login
venom cloud login signs a machine in without pasting a key. It shows a code, opens /device in your browser,
and waits until someone approves it. The console then mints an API key for the key group you pick, and the CLI keeps
it in ~/.venom/cloud.json (mode 0600).
venom cloud login # opens https://cloud.usevenom.dev/device?code=…
venom cloud status # cloud, key group, key prefix, pinned policy keys, the policy in use
venom cloud logout # deletes ~/.venom/cloud.json; revoke the key in the console tooIn the browser, /device asks you to sign in first if needed, then shows the code (it looks like WDJB-MJHT),
the machine's name, its venom version, a coarse location and how long ago it asked. Check the code matches your
terminal, pick a key group and press Approve, or Deny. The key is minted at the CLI's next poll and never appears on
the page. Approving needs keys:write on the key group (an owner, admin or developer).
| Subcommand or flag | What it does |
|---|---|
venom cloud login |
the device login above; also pins your organisation's policy-signing key in ~/.venom/policy-keys when no administrator installed keys, and fetches the key group's policy |
--url <cloud> |
the cloud to sign in to; default VENOM_CLOUD_URL, else https://cloud.usevenom.dev |
--no-browser |
print the link instead of opening it |
--trust-new-key |
accept a policy key other than the one pinned before (after a rotation) |
venom cloud logout |
deletes ~/.venom/cloud.json, no network call; the key works until you revoke it under Settings, API keys |
venom cloud status |
the cloud, key group and key prefix in use (never the key), the pinned keys, the policy |
venom cloud backup, venom cloud restore |
an organisation's configuration as JSON and back; needs an owner or admin signed in |
VENOM_CLOUD_URL and VENOM_CLOUD_KEY, when set, win over ~/.venom/cloud.json. More on the policy key in
Policy.
Environment variables
For people running their own Venom Cloud deployment. The hosted cloud sets these for you.
| Variable | Used by | What it does |
|---|---|---|
VENOM_CLOUD_ADMIN_TOKEN |
cloud | the admin API's token and the console's token login; at least 32 characters, or the admin API and console answer 503 "not configured". make cloud-dev uses a fixed loopback-only value when unset |
VENOM_CLOUD_CONSOLE_PASSWORD |
cloud | the token login's password; falls back to VENOM_CLOUD_ADMIN_TOKEN |
VENOM_CLOUD_ORIGIN |
cloud | the public origin (https://cloud.example.com); default the origin of the request (x-forwarded-host behind a proxy) |
VENOM_CLOUD_ALT_ORIGINS |
cloud | other origins the same deployment answers on, comma-separated (see Change the domain); sign-in always starts on VENOM_CLOUD_ORIGIN. Unset: only that one |
VENOM_CLOUD_REGION |
cloud | the region label /api/status and the cloud's own providers report off Vercel (VERCEL_REGION wins); default sin1 |
AUTH_SECRET |
cloud | signs session cookies and OAuth state; default a key derived from the console password |
GITHUB_CLIENT_ID, GITHUB_CLIENT_SECRET |
cloud | turn on GitHub sign-in |
VENOM_CLOUD_GITHUB_USERS, VENOM_CLOUD_GITHUB_ORGS, VENOM_CLOUD_GITHUB_TEAMS |
cloud | GitHub's allowlist: logins; organisations; org/team-slug[=<venom key group id>|=admin]. With no allowlist nobody is admitted |
CLERK_SECRET_KEY, NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY, CLERK_JWT_KEY |
cloud | turn on email sign-in through Clerk; the optional JWT public key (PEM) makes the token check networkless |
VENOM_CLOUD_CLERK_ADMINS, VENOM_CLOUD_CLERK_TEAMS, VENOM_CLOUD_CLERK_DOMAINS |
cloud | Clerk operators (emails or user ids; one who is also an organisation member chooses operator or member); legacy key group mappings; allowed email domains |
VENOM_CLOUD_URL, VENOM_CLOUD_KEY |
CLI | the cloud and client key the CLI uses; override ~/.venom/cloud.json |
VENOM_CLOUD_ADMIN_KEY |
CLI | an organisation admin's vak_ key, for venom gear new --publish |
VENOM_CLOUD_AUDITOR_TOKEN |
venom-auditor |
the public mesh auditor's token for the cloud's auditor API; required by the auditor, never logged |
Troubleshooting
/login shows the reason after a refused sign-in (?error=):
| Message | Cause and fix |
|---|---|
| Your GitHub account is not on this console's allowlist. | Not in VENOM_CLOUD_GITHUB_USERS, _ORGS or _TEAMS. Ask the operator. |
| Your GitHub account has no role on this console. | Admitted but mapped to no key group or admin. |
| GitHub sign-in expired or was tampered with. | The 10-minute state cookie expired or did not match. Start again. |
| Your Clerk account needs a verified primary email address. | Verify your email in the Clerk form. |
| Your email domain is not allowed on this console. | VENOM_CLOUD_CLERK_DOMAINS excludes it. |
| The organisation setup expired. | The 30-minute onboarding ticket ran out. Sign in again. |
| No organisation has single sign-on for that email domain. | The domain is not verified by any organisation, or SSO is off. |
| Your organisation requires single sign-on. | Use Sign in with SSO. Owners keep their other sign-ins. |
| Too many failed attempts. Try again in 15 minutes. | The token login's limit. |
| The audit log is unavailable, so the console cannot sign you in. | The database is down. No session starts without its audit row. |
On /device:
| Message | Cause and fix |
|---|---|
| No login is waiting with that code. | Codes expire after 10 minutes. Run venom cloud login again. |
| This login was already approved or denied. | Each code decides once. |
| You can't approve logins for that team. | You lack keys:write on it; an owner, admin or developer can. |
Related
- Console home: the Overview and the Get started checklist.
- Organisations, members and roles
- Single sign-on and SCIM
- API keys: keys made by
venom cloud loginshow up there. - Venom Cloud quickstart