# OpenLLM > A local subscription gateway and hosted BYOK API gateway, with a CLI and MCP server for agents. Use this guide to onboard an existing user on the computer running your agent. Discover current providers, login methods, models, and tools rather than assuming a fixed catalog. ## Before making changes - The user must authorize installation and provider login. Account creation and initial vault setup happen in the web onboarding; this guide does not bypass them. - Use the API key supplied by onboarding or the user's existing local configuration. Never request the recovery phrase. Local provider login does not need it. - API keys are sensitive credentials, not harmless identifiers. Do not print them, put them in source control, include them in URLs, or echo configuration files into a transcript. - These commands control only the daemon on this machine. They do not select another device, change the dashboard's “this machine” designation, or bypass remote device authorization. - Ask before logout, cancellation, reinstalling, restarting a working daemon, or performing billable inference. Do not continually refresh quotas or start background authentication. ## Install and start The installer installs both `openllm` (alias `ollm`) and the `openllmd` daemon. Check `openllm --version` and `openllm status` first if already installed. ```sh curl -fsSL https://www.openllm.sh/install | bash openllm start openllm status ``` - With no key, `openllm start` prompts in an interactive terminal. Obtain the initial key from web onboarding; returning users can find it under Keys. - For agent-driven installation, provide the onboarding key through the installer process's `OPENLLM_API_KEY` environment using your harness's secret handling, not a literal key in a command. The installer persists the supplied key for the daemon. - CLI and daemon share `~/.openllm/.env`. Do not create a second config or overwrite an existing account's pairing. `OPENLLM_CLOUD_ORIGIN` selects the gateway; retain the origin supplied by onboarding. - A key is required for gateway pairing. Local management uses the daemon's owner-only, per-boot capability automatically; never copy or display that capability. - Missing/stopped daemon: install/start it with permission. Unsupported auth commands on an older binary: update the installed pair with permission rather than falling back to an unauthenticated HTTP route. ## Discover provider authentication ```sh openllm auth providers --json openllm auth status --json openllm auth usage --json ``` Discovery reports the running daemon's providers and supported methods. Use the exact returned provider identifier. Status and usage reads do not initiate login or request fresh vendor quota data. Cached or unknown usage is not proof that quota is available. Start a login only when the user requests it. Choose a supported method explicitly: ```sh openllm auth login --method browser --json openllm auth login --method device --json ``` - Use only a method listed in that provider's `methods` from `openllm auth providers --json`. Its `default_method` is the primary method, selected automatically if you omit `--method`; it is not necessarily `browser`. - `browser` starts the vendor's browser-based login on this computer. `device` starts a headless flow that may use a verification URL/code or a paste-back code, not necessarily OAuth device authorization. Some providers are device-only; not every provider offers both methods. - The daemon reuses the vendor's existing native login machinery. The user may still need to open the vendor's site and approve access; “no OpenLLM dashboard required” does not mean “no human consent.” - Keep the returned `flow_id` private: it is the continuation handle for that local login, not a public status identifier. Login returns while native consent is still running. `command_status: "done"` or `pending: true` is not a completed login; confirm `connected: true`. Show the intended user the returned consent instructions, then check that flow: ```sh openllm auth status --flow-id --json ``` If the flow requests a paste-back code, feed the single-use code through stdin to: ```sh openllm auth submit-code --flow-id --json ``` Do not put the code in argv, shell history, logs, or a public document. For automation, use a subprocess stdin pipe. Check status again after submission; stop on an expired/failed flow and report the actual result rather than repeatedly restarting login. ```sh openllm auth cancel --flow-id --json openllm auth logout --json openllm auth refresh --json ``` Cancel ends the selected pending login. Logout signs out that provider on this daemon, not the OpenLLM web account. Refresh explicitly requests updated usage and may defer while authentication is busy. Use it on demand, not as a polling loop. Never cancel someone else's flow or change login methods mid-flow without permission. ## Run a client or connect MCP ```sh openllm --help openllm claude openllm codex openllm mcp ``` - Use the installed CLI's help for supported clients. Session clients launch with temporary configuration instead of overwriting their existing config; always-on integrations such as Raycast are an explicit, reversible exception. - The CLI's supported client overlays include OpenLLM's stdio MCP server. For another MCP client, configure the executable `openllm` with args `["mcp"]`, using the existing local pairing. The server must run on the machine whose daemon you want to control. - MCP exposes local auth tools, native gateway operations, code/docs indexing, and memory tools. Read their current schemas: do not guess tool names or required fields. - Local auth tools mirror the CLI lifecycle and require the same explicit user intent for mutations. They are not hosted cloud endpoints. - A client already running may need to reconnect/restart its MCP connection after installation or an update. Do not claim new tools are available until the client has listed them. ## Discover inference, then verify - Query authenticated `/v1/models` through the gateway's MCP tool or client SDK. Use exact returned IDs, `provider_type`, capabilities, formats, and limits. The catalog describes configured availability, not live readiness or remaining quota. - Subscription inference requires the local daemon, which exposes its own `/v1/` surface like the hosted gateway. Its default API base is `http://127.0.0.1:8787/v1`. The port is configurable through `OPENLLM_DAEMON_PORT` in `~/.openllm/.env`; honor that value instead of hardcoding 8787. The CLI's client launchers handle endpoint selection. - Hosted `https://www.openllm.sh/v1` serves API-key BYOK. Do not point a subscription chain there and expect the cloud to run the user's subscription login. - `ultra`, `plus`, and `lite` are configurable fallback aliases, not subscription-only guarantees. They may reach a paid API-key provider. For subscription-only intent, select a direct subscription model from discovery and verify its local auth state. - For a user-authorized smoke test, make one small request to a discovered model and supported endpoint. Preserve the requested wire format and report the actual response/error. Do not benchmark or exhaust quota during onboarding. - For media tools that support automatic model selection, omit `model`; do not send `"auto"` or an empty string. Preserve explicit user constraints and consult the current tool schema. ## Other capabilities and limits - Search: use the supported search tools/models returned by discovery. Grok has a native X/web-search path, but do not assume every model exposes it on every endpoint. Muse's presence alone does not establish Instagram/Facebook search access; do not promise unverified social-search coverage. - Context: MCP can index and search codebases and documentation; indexed code/docs features require the applicable paid plan. A codebase needs a Git origin. Obtain permission before uploading/indexing material, and inspect indexing status before relying on results. - Memory: MCP can save, recall, and forget account-scoped memories across devices; memory content is vault-encrypted. Use existing pairing, never request the recovery phrase to enable an agent tool. - Privacy: do not describe embeddings as anonymization or assume indexing uploads no source material. Read the relevant tool's contract and the privacy policy before sending sensitive content. - Chat/media/device sessions: browser surfaces and local clients have different capabilities. Do not promise a particular endpoint, cross-device media access, or a remote terminal session merely because the daemon is connected. - Quota estimates and API-equivalent cost estimates are not vendor billing records. Provider auth, entitlement, model capabilities, and current quota remain separate checks. ## References - [Sign in / onboarding](https://www.openllm.sh/sign-in): initial account, vault, and API-key setup. - [Documentation](https://docs.openllm.sh/): public guides and reference; `openllm api --spec` also prints the installed API spec. - [Daemon](https://github.com/openllmsh/daemon): public daemon distribution and documentation. - [CLI](https://github.com/openllmsh/cli): public CLI distribution and documentation. - [Tunnel](https://github.com/openllmsh/tunnel): public tunnel package. - [Protocol](https://github.com/openllmsh/protocol): public protocol contracts. - [Privacy](https://www.openllm.sh/privacy): data handling and user controls. - [Terms](https://www.openllm.sh/terms): terms of service. - [Contact](https://www.openllm.sh/contact): support and questions. - [Public usage index](https://www.openllm.sh/usage-index): aggregate estimates, not a promise of available quota.