CLI & Desktopdevice flow · machine-bound tokens

Desktop App & CLI Authentication

Name: LyDos Orchestration Platform
Author: LYDOS

The LYDOS CLI and Tauri desktop app use an RFC 8628-inspired device authorization flow. Authentication opens a browser window, completes the consent, and returns a machine-bound token.

CLI Installation

Install the LYDOS CLI with the one-line installer. The script detects your platform, downloads the correct binary, verifies its SHA256 hash, and places it in ~/.local/bin/lydos (Linux/macOS) or %APPDATA%\lydos\bin\lydos.exe (Windows).

terminalBASH

# Linux / macOS — one-line installer
curl -fsSL https://get.lydos.ai/install.sh | bash

# Verify the installation
lydos --version
# LYDOS CLI v1.0.0 (build 20260421, platform linux/amd64)

# Add to PATH if not auto-detected (add to ~/.bashrc or ~/.zshrc):
export PATH="$HOME/.local/bin:$PATH"

NOTE

The installer verifies the binary against a SHA256 checksum file co-signed by two independent release keys before placing it on your PATH. If verification fails the installer exits without writing any files.

Manual install (alternative)

terminalBASH

# Download a specific version manually
VERSION="1.0.0"
ARCH="$(uname -m)"   # x86_64 or aarch64
OS="$(uname -s | tr '[:upper:]' '[:lower:]')"  # linux or darwin

curl -fsSL "https://releases.lydos.ai/cli/$VERSION/lydos-$OS-$ARCH" \
  -o /tmp/lydos

# Verify checksum
curl -fsSL "https://releases.lydos.ai/cli/$VERSION/SHA256SUMS" | \
  grep "lydos-$OS-$ARCH" | sha256sum --check

# Install
chmod +x /tmp/lydos
mv /tmp/lydos ~/.local/bin/lydos

CLI Authentication

Run lydos auth login to start the device authorization flow. The CLI displays a short user_code, opens your default browser to the verification URL, and polls the token endpoint until you approve the request.

Initiate device flow

Run the login command. The CLI requests a device code from the server and displays it.

terminalBASH

lydos auth login

# Output:
# Open your browser to: https://lydos.ai/device
# Enter code: ABCD-1234
# Waiting for authorization...

Approve in browser

Your default browser opens automatically. Log in with your LYDOS account, enter the user_code shown in the terminal, and click Authorize. The page displays a confirmation when the device is approved.

Token stored locally

After approval the CLI exchanges the device code for an access token and stores it at ~/.config/lydos/auth.json with file permissions 0600.

terminalBASH

# Token successfully stored
# Logged in as: [email protected] (Pro plan)
# Token expires: 2026-05-21

# Verify you are authenticated
lydos auth status
# Authenticated as: [email protected]
# Token: valid (expires in 29 days)
# Machine binding: 192.168.1.x / Mozilla/5.0... (hash bound)

Use with any CLI command

Once authenticated, all CLI commands automatically include the token.

terminalBASH

# Run an agent (token is attached automatically)
lydos agent run SPEC-001 --prompt "Analyze this repo"

# Stream a chat response
lydos chat "What is the current system health?" --stream

# Check your account and subscription
lydos auth whoami

Device Flow Internals

The flow is inspired by RFC 8628 (OAuth 2.0 Device Authorization Grant). The LYDOS implementation adds machine binding — the issued token is tied to the IP address prefix and User-Agent hash of the device that initiated the flow.

device-flow-sequence.txtTEXT

CLI                         LYDOS Server               Browser
 |                               |                          |
 |-- POST /api/auth/device ----> |                          |
 |   {}                          |                          |
 |                               |                          |
 |<-- 200 OK -------------------|                          |
 |   {                           |                          |
 |     "device_code": "...",     |                          |
 |     "user_code": "ABCD-1234", |                          |
 |     "verification_uri":       |                          |
 |       "https://lydos.ai/device",                         |
 |     "expires_in": 300,        |                          |
 |     "interval": 5             |                          |
 |   }                           |                          |
 |                               |                          |
 |-- opens browser ------------> |                    GET /device
 |                               |          user enters ABCD-1234
 |                               |          user clicks Authorize
 |                               |<-- POST /api/auth/device/approve
 |                               |    {device_code, user_id}  |
 |                               |                          |
 |-- POST /api/auth/token -----> |   (poll every 5 seconds) |
 |   {device_code}               |                          |
 |                               |-- returns access_token   |
 |<-- 200 OK -------------------|                          |
 |   {                           |                          |
 |     "access_token": "...",    |                          |
 |     "token_type": "Bearer",   |                          |
 |     "expires_in": 2592000,    |                          |
 |     "machine_bound": true     |                          |
 |   }                           |                          |

While waiting for the user to approve, the CLI polls POST /api/auth/token every 5 seconds (the interval value). The server returns authorization_pending until the user approves, then issues the token in the next poll response.

Token Storage

Tokens are stored in a single JSON file. The file is created with 0600 permissions — readable only by the current user. On macOS, tokens are additionally stored in the system Keychain when available.

~/.config/lydos/auth.jsonJSON

{
  "access_token": "eyJhbGciOiJFUzI1NiIsInR5cCI6IkpXVCJ9...",
  "token_type": "Bearer",
  "expires_at": "2026-05-21T10:00:00Z",
  "refresh_token": "rt_...",
  "user": {
    "id": "usr_abc123",
    "email": "[email protected]",
    "plan": "pro"
  },
  "machine_binding": {
    "ip_prefix": "192.168.1.x",
    "ua_hash": "sha256:7f3a...",
    "bound_at": "2026-04-21T10:00:00Z"
  }
}

WARNING

Machine-bound tokens are rejected when used from a different IP prefix or with a different User-Agent hash. If you change networks or devices, run lydos auth login again to issue a new machine-bound token.

Token management commands

terminalBASH

# Show current auth status and token expiry
lydos auth status

# Revoke the current token (logout)
lydos auth logout

# Revoke all tokens for this account (all devices)
lydos auth logout --all-devices

# Rotate the token manually before expiry
lydos auth refresh

# Show token details (redacts the raw token value)
lydos auth whoami --verbose

Desktop App

The LYDOS desktop application is built with Tauri (Rust backend, Next.js frontend). It bundles the same authentication flow as the CLI with a native UI. The desktop app communicates with the local LYDOS server on port 8888 by default.

Platform Releases

Platform	Format	Architecture
Linux x86_64	`.AppImage`	x86_64
Linux ARM64	`.AppImage`	aarch64
macOS Intel	`.dmg`	x86_64
macOS Apple Silicon	`.dmg`	aarch64
Windows x64	`.msi`	x86_64
Windows ARM64	`.msi`	aarch64
Debian/Ubuntu	`.deb`	amd64

terminalBASH

# Download the desktop app for your platform
# All releases are signed and include a SHA256 checksum

# Linux AppImage (x86_64)
curl -fsSL https://releases.lydos.ai/desktop/v1.0.0/LYDOS_1.0.0_amd64.AppImage \
  -o ~/Applications/LYDOS.AppImage
chmod +x ~/Applications/LYDOS.AppImage
~/Applications/LYDOS.AppImage

# macOS Universal DMG
curl -fsSL https://releases.lydos.ai/desktop/v1.0.0/LYDOS_1.0.0_universal.dmg \
  -o ~/Downloads/LYDOS.dmg
open ~/Downloads/LYDOS.dmg

Desktop app authentication flow

When you first open the desktop app, it detects whether a valid token exists in ~/.config/lydos/auth.json and whether it is still machine-bound to the current device. If not, it opens the built-in browser pane to the device flow verification URL.

The desktop app shares the same token store as the CLI. Logging in via either the CLI or the desktop app authenticates both simultaneously.

Authentication API Endpoints

terminalBASH

# 1. Initiate device flow
curl -s -X POST http://localhost:8888/api/auth/device \
  -H "Content-Type: application/json" | python3 -m json.tool

# 2. Poll for token (repeat until authorized or expired)
curl -s -X POST http://localhost:8888/api/auth/token \
  -H "Content-Type: application/json" \
  -d '{"device_code": "<device_code>", "grant_type": "urn:ietf:params:oauth:grant-type:device_code"}' \
  | python3 -m json.tool

# 3. Validate current token
curl -s http://localhost:8888/api/auth/me \
  -H "Authorization: Bearer $TOKEN" | python3 -m json.tool

# 4. Refresh a token before expiry
curl -s -X POST http://localhost:8888/api/auth/token \
  -H "Content-Type: application/json" \
  -d '{"grant_type": "refresh_token", "refresh_token": "<refresh_token>"}' \
  | python3 -m json.tool

# 5. Revoke a token
curl -s -X POST http://localhost:8888/api/auth/revoke \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"all_devices": false}' | python3 -m json.tool

TIP

Tokens expire after 30 days. The CLI and desktop app automatically refresh tokens 7 days before expiry when you run any authenticated command. You can also refresh manually with lydos auth refresh.

Next steps

Auth & Organizations

JWT structure, org management, RBAC roles

CLI Reference

Full command reference for the LYDOS CLI

Sovereign Security Stack

KSL device-bound key sovereignty layer

Getting Started

Server setup for local CLI usage