> ## Documentation Index
> Fetch the complete documentation index at: https://docs.lagerdata.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Signing In

> Using lager login for access-controlled boxes

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:

```bash theme={null}
lager login https://your-control-plane.example.com
```

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:

```bash theme={null}
lager login https://your-control-plane.example.com --web
```

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.

```bash theme={null}
lager login https://your-control-plane.example.com --no-browser
```

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:

| Option | Description |
| - | - |
| `--email TEXT` | Account email |
| `--password TEXT` | Account password |

```bash theme={null}
lager login https://your-control-plane.example.com --email "$LAGER_EMAIL" --password "$LAGER_PASSWORD"
```

<Warning>
  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.
</Warning>

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.

```bash theme={null}
lager logout                 # forget every stored session
lager logout <auth-url>      # forget one server's session
```

### 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:

```yaml theme={null}
env:
  LAGER_GATEWAY_TOKEN: ${{ secrets.LAGER_GATEWAY_TOKEN }}
```

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.

## Checking your status

When something looks off, `lager whoami` is the first thing to run:

```bash theme={null}
lager whoami
```

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

| Message | What it means | What to do |
| - | - | - |
| **This box requires sign-in** | The box is gated and you have no stored session. | Run the `lager login <url>` it prints, then retry. |
| **requires sign-in… now linked to this box** | First contact after signing in — the box was just linked to your session. | Re-run the command; it authenticates automatically. |
| **Your session… was rejected** | Your session expired or was revoked. | Run `lager login <url>` again. |
| **signed in but not authorized** | Your account is valid but has no access grant for this box. | Ask an org admin to grant you access. |
| **could not verify your access right now** | The box couldn't reach its auth server. | Try again shortly; if it persists, contact your admin. |
| **refused the token in LAGER\_GATEWAY\_TOKEN** | The gateway rejected the token the job supplied. | Get a new token from the auth server named in the message. |
| **does not support debug tunnels yet** | A warning. `lager debug ... gdbserver` started the GDB server and exited successfully, but the gateway of the box cannot open a tunnel to it, so no debugger on this machine can connect. | Ask the administrator of the box to update its gateway. |

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

```bash theme={null}
pip install --upgrade lager-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.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.