Skip to content
Docs menu

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.

View .md

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

  1. Open /auth/clerk/sign-up (the "Create an account" link on /login) and sign up with your email.
  2. 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 a default key group (a key group holds API keys, daemons, policies and GPU grants, not people; the API calls it team).
  3. 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/clerk shows 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/github sends 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 too

In 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.