llamas-connect

One-command OAuth onboarding for LLamas AI OS.

npx llamas-connect

Opens a browser, you sign in, and your Claude Code / Claude Desktop are wired up to your LLamas workspace. You never copy or paste an API key.

What it does

1. Discovers OAuth endpoints via /.well-known/oauth-authorization-server
2. Generates a PKCE code_verifier + code_challenge
3. Starts a local loopback HTTP server (http://127.0.0.1:<random>/callback)
4. Opens your default browser to the LLamas authorize page
5. After you sign in, captures the callback and exchanges the code for tokens
6. Verifies the connection by calling GET /api/v1/auth/me
7. Saves your tokens to ~/.llamas/tokens.json (mode 0600)
8. Patches Claude Code's ~/.claude/settings.json and Claude Desktop's claude_desktop_config.json
9. Auto-creates <username>-code, <username>-cowork, <username>-dispatch bot identities (when the backend supports it)

Install

This package is published on npm. You don't need to install it — npx fetches it on demand:

npx llamas-connect

If you'd rather have it locally:

npm install -g llamas-connect
llamas-connect

Usage

USAGE
  npx llamas-connect [options]

OPTIONS
  --server <url>      LLamas server URL (default: https://llamas.runningbulltech.com)
  --invite <token>    Accept an invite token (first-time onboarding)
  --status            Show whether you're connected and token validity
  --refresh           Refresh the access token using the stored refresh token
  --name <name>       MCP server entry name in Claude config (default: llamas)
  --no-patch          Don't write to Claude Code / Claude Desktop config
  --help, -h          Show this help
  --version, -v       Show version

ENVIRONMENT
  LLAMAS_SERVER       Default server URL (overridden by --server)
  CLAUDE_CONFIG       Path to Claude Code settings.json
  NO_COLOR            Disable ANSI colors

Examples

# Default — connect to llamas.runningbulltech.com
npx llamas-connect

# Self-hosted instance
npx llamas-connect --server https://llamas.acme.io

# First-time onboarding from an invite link
npx llamas-connect --invite eyJ0eXAi...

# Check whether your existing connection is healthy
npx llamas-connect --status

# Renew the access token without opening a browser
npx llamas-connect --refresh

Token storage

Tokens are stored at ~/.llamas/tokens.json:

{
  "server_url": "https://llamas.runningbulltech.com",
  "client_id": "...",
  "access_token": "<JWT>",
  "refresh_token": "<opaque>",
  "expires_at": 1738312345,
  "username": "luis",
  "contributor_id": "...",
  "project_slugs": ["red-wallet", "llamas"],
  "saved_at": 1738308745
}

The directory is chmod 700 and the file is chmod 600 on POSIX. On Windows we rely on default ACLs.

Token refresh

The CLI installs both Authorization: Bearer <access_token> AND X-LLamas-Refresh: <refresh_token> headers into your Claude config. On the LLamas side, the MCP server transparently refreshes expired tokens via the refresh header — no daemon, no re-running this CLI.

If the refresh token itself expires (default 90 days), run npx llamas-connect again to re-authenticate.

You can also force a refresh at any time:

npx llamas-connect --refresh

Security

• Never commits your tokens to git. Tokens live in ~/.llamas/tokens.json, mode 0600.
• PKCE everywhere. No client secret; the code_verifier is generated fresh on every run and never persisted.
• Loopback redirect only. The dynamic client registration uses http://127.0.0.1:<port>/callback — the LLamas backend rejects any non-loopback redirect URI.
• Atomic config patches. Existing ~/.claude/settings.json and claude_desktop_config.json are backed up to <file>.bak.<timestamp> on every patch.

Development

cd packages/llamas-connect
npm install
npm run build
node dist/cli.js --help

# Run against a local LLamas backend
node dist/cli.js --server http://localhost:8080

License

MIT