Skip to main content
Most Lager Boxes need no sign-in — you run commands and they work. Some boxes, though, sit behind an access gateway: an authenticating proxy that only lets assigned users reach the box. Against one of those, Lager asks you to sign in once, then authenticates every command automatically. A plain Lager Box never prompts for this. You only see it when someone deliberately places a box behind a gateway.

​
Signing in

The first time you run a command against a gated box, it tells you exactly what to do. The message fills in the URL for you:
You’ll be asked for your account email and password (and an MFA code if your account uses one). Your session is stored in ~/.lager_gateway_auth (readable only by you) and refreshes on its own, so you rarely sign in more than once. From then on, lager hello, lager python, net commands, and everything else just work against that box.

​
Signing in with a browser

Add --web to sign in on a web page instead of typing a password into the terminal:
Lager opens the sign-in page of the auth server in your browser. Sign in there the way you usually do, then approve the request. The terminal shows the link too, in case the browser does not open. This is the only way to sign in if your account uses single sign-on (SSO) and so has no password. On a computer with no browser, such as one you connect to over SSH, add --no-browser. Lager shows a link and waits. Open the link on any computer, approve the request, and paste the code that the page shows into the terminal.
Browser sign-in needs an auth server that supports it. If the server does not, Lager says so, and you sign in with a password.

​
Non-interactive sign-in

Both credentials can be supplied as options instead of being prompted for, which is what you want in a CI job:
A password passed on the command line is visible to other users via the process list and is written to your shell history. Read it from a secret store or an environment variable, as above, rather than typing the literal value.
If the account has MFA enabled, these two options are not enough on their own. The CLI still prompts for the MFA code, so the sign-in is not fully unattended. Use an account without MFA for automation.

​
A token instead of a sign-in

A CI job has no person to be. If your auth server can make a machine token, give the job that token and drop the login step:
The CLI sends this token with every request to a box. It wins over any stored session, and it is never refreshed. Nothing is written to ~/.lager_gateway_auth, so the job leaves no credential on the runner. An empty or whitespace-only value counts as unset. If the gateway refuses the token, the command fails at once and names the auth server that refused it. There is no second credential to fall back on.

​
Using your session in a container

To use your session in a Docker container, mount the session file into the container. Then the container and your computer use one session. A sign-in or a refresh on one side is immediately available on the other side. lager devenv terminal and lager exec do this for you. For a container that you start in a different way, add the mount yourself. A dev container (devcontainer.json, for VS Code or Cursor):
docker run:
  • Make sure that the file exists before the container starts. If the file does not exist, Docker makes a directory with that name. Set its mode to 0600: the file contains your session, and a container cannot change the mode of a file that Docker Desktop mounts.
  • Use the CLI version that includes this change, or a later version, on your computer and in the container. Earlier versions replace the file when they save it. The container then keeps an old copy, and its own saves fail.
  • If the container user is not root, change the target to the home directory of that user. Or set LAGER_GATEWAY_AUTH_FILE in the container to the target path.

​
Checking your status

When something looks off, lager whoami is the first thing to run:
It shows four things:
  • which servers you are signed in to
  • who you are signed in as
  • when each session expires
  • which gated boxes the CLI saw
That separates three problems at a glance: “not signed in”, “signed in as the wrong account”, and “signed in but no access”.

​
Common messages and what they mean

If you hit any of these on an old Lager version, upgrade first — sign-in support needs a current CLI:

​
For administrators

Your control-plane dashboard, not the CLI, controls whether a box requires sign-in and who can use it. Assign users to a box, then turn its access guard on; denied attempts are logged so you can see who needs access.