> For the complete documentation index, see [llms.txt](https://docs.telys.ai/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.telys.ai/licensing/device-code-sign-in.md).

# Device-code sign-in

`telys login` signs a machine in without handling your password. It uses the **OAuth 2.0 Device Authorization Grant** (RFC 8628): the CLI requests a code, you approve it in a browser, and Telys exchanges it for locally cached credentials. The result is a per-device identity — an Ed25519 key plus a device id — and a signed license the runtime verifies offline.

## Why a device-code flow

Telys often runs where there is no browser — a server, a container, an SSH session. A device-code flow fits:

* The CLI never sees your credentials — only a device code and, later, tokens scoped to this machine.
* Approval happens in a browser at [accounts.thyn.ai](https://accounts.thyn.ai), where MFA and SSO already work.
* Each machine gets its own key and id, so you can revoke devices independently. See [Seats & devices](/licensing/seats-and-devices.md).

## The flow, step by step

{% stepper %}
{% step %}

#### Start the login

```bash
telys login                    # free telys_developer plan
telys login --plan telys_pro   # commercial plan
```

The CLI requests a device code from the identity portal (`$TELYS_ACCOUNTS_URL`, default `https://accounts.thyn.ai`). It prints a user code and a verification URL and, unless you pass `--no-browser`, opens the URL.
{% endstep %}

{% step %}

#### Approve in the browser

Sign in at the verification URL and confirm the code shown by the CLI. Your account, plan, and any `telys_pro` Stripe checkout are handled here. The CLI polls the control plane (`$TELYS_API_URL`, default `https://api.telys.ai`) while it waits.
{% endstep %}

{% step %}

#### Register the device

On approval, Telys generates an **Ed25519 device key** and a random **device id**, and caches your control-plane credentials under `$TELYS_HOME` (default `~/.telys`):

```
~/.telys/device_key.pem     # Ed25519 private key for this device (0600)
~/.telys/device_id          # uuid4 hex identifying this device
~/.telys/token              # cached control-plane token
~/.telys/api_key            # cached API key
```

The private device key never leaves the machine; it identifies this device to your account.
{% endstep %}

{% step %}

#### Fetch the license

Telys downloads your signed license and caches it:

```
~/.telys/login_license.jwt  # signed, offline-verifiable license
```

This JWT records your `tier` and `features`; the runtime checks it offline from then on. See [Offline licenses & verification](/licensing/offline-licenses.md).
{% endstep %}
{% endstepper %}

Unless you pass `--no-install`, `telys login` also installs the signed runtime for your platform. To activate a tier without it, pass `--no-install` and run [`telys runtime install`](/cli/runtime.md) later.

## Headless & CI sign-in

On a machine with no browser — CI, a build agent, a remote box — provide a token directly:

```bash
telys login --token "$TELYS_TOKEN" --plan telys_pro --no-browser --no-install
```

`--token` authenticates with a control-plane token you already hold, skipping the browser; `--no-browser` stops the CLI opening a URL. Use this for automation.

{% hint style="info" %}
Pass the token through the environment (`$TELYS_TOKEN`), not the command line, to keep it out of shell history and CI logs. `$TELYS_TOKEN` overrides the cached control-plane token; `$TELYS_API_KEY` overrides the cached API key.
{% endhint %}

## Command reference

```bash
telys login [--token TOKEN] [--plan PLAN] [--no-install] [--no-browser]
```

| Flag            | Default           | Effect                                                                 |
| --------------- | ----------------- | ---------------------------------------------------------------------- |
| `--token TOKEN` | —                 | Authenticate headlessly with a control-plane token (skips the browser) |
| `--plan PLAN`   | `telys_developer` | The tier to activate (e.g. `telys_pro`)                                |
| `--no-install`  | off               | Do not install the signed runtime as part of login                     |
| `--no-browser`  | off               | Do not attempt to open a browser; print the URL instead                |

The relevant environment variables:

| Variable             | Default                    | Effect                                            |
| -------------------- | -------------------------- | ------------------------------------------------- |
| `TELYS_HOME`         | `~/.telys`                 | Root of all on-disk state (keys, license, tokens) |
| `TELYS_ACCOUNTS_URL` | `https://accounts.thyn.ai` | Identity portal for the device-code flow          |
| `TELYS_API_URL`      | `https://api.telys.ai`     | Control plane for keys, device, and license       |
| `TELYS_TOKEN`        | —                          | Control-plane token override                      |
| `TELYS_API_KEY`      | —                          | Telys API key override                            |

## Verify it worked

Confirm the runtime is installed and the license verifies locally:

```bash
telys runtime status     # 0 = ready, 1 = not installed
telys runtime verify     # verifies the installed runtime + license offline
```

See [Verify your install](/start-here/verify-install.md) for the full walkthrough.

## Next steps

<table data-view="cards"><thead><tr><th></th><th></th><th data-hidden data-card-target data-type="content-ref"></th></tr></thead><tbody><tr><td><strong>Offline licenses &#x26; verification</strong></td><td>What the license.jwt is and how it is checked.</td><td><a href="/pages/uRMcsbR2tREfJPlvdVTx">/pages/uRMcsbR2tREfJPlvdVTx</a></td></tr><tr><td><strong>Seats &#x26; devices</strong></td><td>Your per-device key, and re-login on a new machine.</td><td><a href="/pages/QId9O6LUKECM8BkqZLfg">/pages/QId9O6LUKECM8BkqZLfg</a></td></tr><tr><td><strong>License &#x26; login issues</strong></td><td>Fix a stuck or failing sign-in.</td><td><a href="/pages/f5D2AxbBcG8bokGMGJNZ">/pages/f5D2AxbBcG8bokGMGJNZ</a></td></tr></tbody></table>

Next: [Offline licenses & verification](/licensing/offline-licenses.md).


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.telys.ai/licensing/device-code-sign-in.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.