> ## Documentation Index > Fetch the complete documentation index at: https://www.offlineprotocol.com/docs/llms.txt > Use this file to discover all available pages before exploring further. > ## Agent Instructions > These docs target Mesh SDK v0.27.0. Match the installed package and binding before generating code. Start at /getting-started/agents for task-specific reading paths. > Call the company and product Offline Protocol, never Offline alone. Current packages: @offline-protocol/mesh-sdk 0.27.0 (React Native), @offline-protocol/id-react 0.2.0, @offline-protocol/id-react-native 0.3.3, @offline-protocol/pol 0.1.2 and @offline-protocol/cli 0.2.6. Canonical docs URLs start with https://www.offlineprotocol.com/docs. > The Mesh SDK runs in a native app or gateway. A browser OfflineID SDK integration does not provide browser mesh transport. Local mesh operation does not require a portal API key. > Service RPC is signed plaintext in v0.27.0. Message delivery, durable local acceptance and backend commit are distinct outcomes. Use the workflow guide for the required application logic. > Offline Protocol CLI 0.2.6 is on npm (@offline-protocol/cli, command offline). Its local MCP server runs with offline mcp serve and requires no login or key. Hosted MCP is at https://mcp.offlineprotocol.com/mcp with an application API key in Authorization: Bearer and a matching x-app-id; organization keys are rejected. Follow /tools/overview for setup and do not invent commands beyond it. MCP provides integration context and planning, not mesh execution; file-writing tools are local only. > Phone Wi-Fi Direct and MultipeerConnectivity carry no data in v0.27.0. Use BLE or a provisioned relay. The receiver core ACKs before application persistence; use application acceptance for durable workflows. > Proof of Location is Sepolia testnet witness evidence, not zero-knowledge proof or proof of presence. The geohash is public onchain. Read /proof-of-location/security before integration. # Offline Protocol CLI and MCP server > Install the Offline Protocol CLI 0.2.6 (@offline-protocol/cli), run its local MCP server or hosted MCP, connect a coding agent and scaffold an integration. The Offline Protocol CLI (`@offline-protocol/cli` 0.2.6) installs the `offline` command and a local MCP server. Use them to find packages, read integration guidance, plan an application and scaffold project files. Hosted MCP provides the same registry and planning context without a local installation, but cannot write files. Neither MCP mode runs the mesh or communicates with peers. Build and test device communication with the [Mesh SDK](/docs/getting-started/quickstart). This page covers the Offline Protocol MCP server; the separate docs MCP server at `https://www.offlineprotocol.com/docs/mcp` only searches and reads these documentation pages. ## Install Requires Node.js 18 or later. Prebuilt binaries cover macOS arm64 and x64, Linux x64 and arm64, and Windows x64. npm installs only the binary for your machine, from a per-platform optional dependency such as `@offline-protocol/cli-darwin-arm64`, so keep optional dependencies enabled: do not install with `--omit=optional` or `--no-optional`. ```bash theme={null} npm install -g @offline-protocol/cli offline --version ``` Without a global installation: ```bash theme={null} npx -y @offline-protocol/cli --version ``` Use `npx -y @offline-protocol/cli ` for any command below. Install through npm; the crates.io package is a placeholder, not the released CLI. ### Changes in 0.2.6 * The npm package metadata and README list [support@offlineprotocol.com](mailto:support@offlineprotocol.com) as the help contact. * `offline init` and new scaffolds start the local MCP server with `@offline-protocol/cli@0.2.6`. ### Changes in 0.2.5 * npm installs one platform binary, about 10 MB, instead of all five, about 50 MB. Keep optional dependencies enabled. * The developer session from `offline login --email` renews while you use the CLI, and `offline logout` signs it out. * On macOS and Linux, credentials are written atomically and owner-only. The local login callback limits request size and time. * Starter templates are licensed under MIT-0, and each generated README lists the license of every Offline Protocol package the project uses. * New scaffolds use `@offline-protocol/id-react` 0.2.0. Run `offline update` to check for a newer release; it prints the upgrade command. ## Login and logout ```bash theme={null} offline login offline whoami --json ``` Login prints a confirmation code and opens `https://dev.offlineprotocol.com/cli-auth`. Choose the application, enter the code exactly as the terminal shows it and approve. Only approve a login you started yourself; after five wrong codes the login is cancelled. Each login creates a new **application API key** for that terminal. Organization keys are not accepted. The CLI receives the approval on a local callback at `127.0.0.1`, on a free port chosen at login (set `OFFLINE_CALLBACK_PORT` to pin one), and also polls for it, so login completes even when the browser cannot reach the callback. Credentials are stored in `~/.offline/config.json`; see [what the CLI stores and sends](#what-the-cli-stores-and-sends). Use `offline login --no-browser` on a headless machine and complete approval from another browser. For CI, supply `OFFLINE_API_KEY` through your secret manager, or use `offline login --api-key `. Keep keys out of source control and logs. `offline login --email` signs in with a one-time code in the terminal instead. It stores a developer session rather than an API key, and it is required for `setup`, `orgs`, `apps` and `keys`. ```bash theme={null} offline logout ``` Logout clears local credentials and revokes the key that login created. Keys you created in the portal, including one supplied with `--api-key`, stay active; delete them in the portal when they are no longer needed. After `offline login --email`, logout also signs out the developer session. That session lasts 30 days, renews while you use the CLI, and ends 90 days after sign-in at the latest. ## What the CLI stores and sends **On your computer.** `offline login` and `offline login --email` write `~/.offline/config.json` (or `$OFFLINE_CONFIG_DIR/config.json`): the application API key, the developer session token from email sign-in, your email address, and your developer, organization and application IDs. The file is plain JSON, not encrypted and not in the system keychain. On macOS and Linux it is created owner-only (0600) and replaced atomically, `~/.offline` is kept owner-only (0700), and a symlinked file or a directory other users can write to is refused. On Windows the file keeps the default permissions of your user profile folder. Anyone who can read the file can use the key. `offline logout` deletes it. **To Offline Protocol.** Sign-in requests, including this computer's hostname as the device name shown when you approve the sign-in, and the developer API calls each command makes with your key or session. Hosted MCP receives the tool arguments your agent sends; it keeps rate-limit counters, keyed by a hash of the credential or by network address, in memory for about 90 seconds. **Elsewhere.** `offline update` asks the public npm registry for the latest version, only when you run it. Scaffolding and the local MCP tools that write projects run `npm install` and similar package-manager commands against the registries you have configured. Your MCP client receives tool inputs and results under its own terms. The CLI and the local MCP server send no usage analytics and no crash reports. Local MCP tools can write files in your project and run package-manager commands with your permissions, subject to your agent client's approval settings; they are not sandboxed. The [privacy policy](https://www.offlineprotocol.com/privacy) covers the same points for every Offline Protocol service. ## Initialize a project From an existing JavaScript or TypeScript application directory containing `package.json`: ```bash theme={null} offline init --app-id app_your_application_id ``` For a new application, start with `offline create`; `offline init` requires an existing package manifest. This writes `offline.config.json`, an `AGENTS.md` section and, when the project has none, a `.mcp.json` that starts the local MCP server with `npx -y @offline-protocol/cli@0.2.6 mcp serve`. Review the generated changes with the rest of your application code. The configuration references the live [JSON Schema](https://dev.offlineprotocol.com/schemas/offline.config.json). The application ID is public metadata; keep API keys outside these files. | Command | Purpose | | - | - | | `login`, `logout`, `whoami` | Manage credentials and inspect authentication state. | | `setup`, `orgs`, `apps`, `keys` | Create or list organizations, applications and API keys from the terminal. Requires `offline login --email`. | | `init` | Configure an existing project. | | `create`, `add` | Scaffold a project or add packages. | | `plan` | Plan an integration. | | `doctor`, `update` | Check the toolchain and credentials, and check npm for a newer CLI release. `update` prints the upgrade command; it does not install it. | | `registry`, `skills` | Inspect available packages and integration guidance. | | `mcp serve`, `mcp install`, `mcp tools` | Run local MCP, print client configuration or list tools. | | `completions` | Generate shell completions. | Use `offline --help` for command options. There is no `offline link` command; project initialization uses `--app-id`, not `--project-id`. | Flag or variable | Effect | | - | - | | `offline whoami --verify` | Checks the stored API key and app ID against the developer API. | | `offline logout --local-only` | Clears local credentials without revoking the key on the server. | | `offline add --dry-run` | Prints what would change without writing files. | | `offline create --pol` | Adds Proof of Location (`@offline-protocol/pol`) to a React Native scaffold. Off by default. | | `offline create --dir ` | Writes the project to `` instead of `./`. | | `offline create -y` | Runs without prompts: accepts defaults and fails on missing required input. Same as `--yes`. | | `OFFLINE_APP_ID` | Overrides the application ID saved in `config.json` when no `--app-id` is passed. | | `OFFLINE_ORG_ID` | Overrides the organization ID saved in `config.json` when no `--org-id` is passed. | ## Start from a workflow `offline plan ""` recommends a workflow, the packages it needs and the exact `offline create` command. Three workflows cover common enterprise integrations. Each scaffolds a React Native app on `@offline-protocol/mesh-sdk` 0.27.0 and needs no login: | Workflow | Scaffold | Guide | | - | - | - | | `local-handoff` | `offline create local-handoff --platform react-native --name my-app` | [Local handoff](/docs/guides/local-handoff) | | `backend-delivery` | `offline create backend-delivery --platform react-native --name my-app` | [Deliver to a backend](/docs/guides/backend-delivery) | | `nearby-service` | `offline create nearby-service --platform react-native --name my-app` | [Nearby service](/docs/guides/nearby-service) | Run `offline registry list workflows` for every workflow and `offline registry list templates` for the templates behind them. ## Local MCP ```bash theme={null} offline mcp serve ``` The `offline-protocol` server uses stdio and requires no login or API key. Let your MCP client launch it. It provides 18 tools for packages, capabilities, workflows, examples, skills, templates, planning and scaffolding. Run `offline mcp tools` to inspect the list. `scaffold_project`, `integrate_packages` and `init_project` write local project files. These tools are available only in local mode. `offline mcp install ` **prints configuration**; it does not edit your client files. Supported names are `claude-code`, `claude-desktop`, `codex`, `cursor` and `vscode`. Use the manual configuration below for Windsurf. ## Hosted MCP Endpoint: `https://mcp.offlineprotocol.com/mcp`. Create an application key in the application's **API keys** tab and send both headers: ```http theme={null} Authorization: Bearer x-app-id: app_your_application_id ``` The app ID must match the key. Organization keys are rejected. Hosted mode offers the 15 read-only tools and cannot write files; use local MCP when your agent needs to scaffold or modify a project. Requests are limited to 60 per minute per key and 600 per minute per network address; a limited request receives `429` with `Retry-After`. The MCP endpoint only accepts `POST` requests from MCP clients. Opening `https://mcp.offlineprotocol.com` in a browser shows a short page explaining how to connect an agent; `GET /mcp` answers 405. The [health endpoint](https://mcp.offlineprotocol.com/health) reports service status. ## Connect your agent For per-client steps that run the pinned CLI through npx without a global installation, and for plugin availability, see [Use Offline Protocol from your coding agent](/docs/tools/coding-agents). Choose local or hosted mode for the same server name; do not configure both under `offline-protocol` in one client. Hosted examples use an application key supplied through the client's environment, a secure prompt, or its private user configuration. | Client | Local setup | Hosted setup | | - | - | - | | Claude Code | `claude mcp add offline-protocol -- offline mcp serve` | HTTP command below. | | Codex | `codex mcp add offline-protocol -- offline mcp serve` | TOML with environment bearer token. | | Cursor | `.cursor/mcp.json` or `~/.cursor/mcp.json` | JSON with environment key. | | VS Code | `.vscode/mcp.json` | JSON with a secret input prompt. | | Windsurf | `~/.codeium/windsurf/mcp_config.json` | JSON in private user configuration. | | Claude Desktop | `claude_desktop_config.json` | Use local mode; its configuration cannot send these headers. | Local: ```bash theme={null} claude mcp add offline-protocol -- offline mcp serve ``` Hosted, with `OFFLINE_API_KEY` set in your environment: ```bash theme={null} claude mcp add --transport http offline-protocol https://mcp.offlineprotocol.com/mcp --header "Authorization: Bearer $OFFLINE_API_KEY" --header "x-app-id: app_your_application_id" ``` The command expands the key into the client configuration. Keep that configuration private. For a project `.mcp.json` that retains an environment reference, use: ```json theme={null} { "mcpServers": { "offline-protocol": { "type": "http", "url": "https://mcp.offlineprotocol.com/mcp", "headers": { "Authorization": "Bearer ${OFFLINE_API_KEY}", "x-app-id": "app_your_application_id" } } } } ``` Local, in `~/.codex/config.toml`: ```toml theme={null} [mcp_servers.offline-protocol] command = "offline" args = ["mcp", "serve"] ``` Hosted, in the same file: ```toml theme={null} [mcp_servers.offline-protocol] url = "https://mcp.offlineprotocol.com/mcp" bearer_token_env_var = "OFFLINE_API_KEY" http_headers = { "x-app-id" = "app_your_application_id" } ``` Set `OFFLINE_API_KEY` in the environment used to start Codex. Use `.cursor/mcp.json` in the project or `~/.cursor/mcp.json`. Local: ```json theme={null} { "mcpServers": { "offline-protocol": { "command": "offline", "args": [ "mcp", "serve" ] } } } ``` Hosted, with the key in the environment used to start Cursor: ```json theme={null} { "mcpServers": { "offline-protocol": { "url": "https://mcp.offlineprotocol.com/mcp", "headers": { "Authorization": "Bearer ${env:OFFLINE_API_KEY}", "x-app-id": "app_your_application_id" } } } } ``` Use `.vscode/mcp.json`. Local: ```json theme={null} { "servers": { "offline-protocol": { "type": "stdio", "command": "offline", "args": [ "mcp", "serve" ] } } } ``` Hosted, with a secret input prompt: ```json theme={null} { "inputs": [ { "type": "promptString", "id": "offline-api-key", "description": "Offline Protocol application API key", "password": true } ], "servers": { "offline-protocol": { "type": "http", "url": "https://mcp.offlineprotocol.com/mcp", "headers": { "Authorization": "Bearer ${input:offline-api-key}", "x-app-id": "app_your_application_id" } } } } ``` Use `~/.codeium/windsurf/mcp_config.json`. Local: ```json theme={null} { "mcpServers": { "offline-protocol": { "command": "offline", "args": [ "mcp", "serve" ] } } } ``` Hosted: replace `YOUR_API_KEY` in this private user file. Do not commit or share it. ```json theme={null} { "mcpServers": { "offline-protocol": { "serverUrl": "https://mcp.offlineprotocol.com/mcp", "headers": { "Authorization": "Bearer YOUR_API_KEY", "x-app-id": "app_your_application_id" } } } } ``` Choose Settings, Developer, Edit Config and add this to `claude_desktop_config.json`: ```json theme={null} { "mcpServers": { "offline-protocol": { "command": "offline", "args": [ "mcp", "serve" ] } } } ``` Use local mode. Claude Desktop's configuration cannot send the headers required by the hosted endpoint. ## Give the agent current instructions Use the live [agent setup prompt](https://dev.offlineprotocol.com/agent-setup/prompt.md) rather than a copied version. Then provide your application, platform and intended workflow using [Build with an AI agent](/docs/getting-started/agents). The documentation page menu shares reading context; it is separate from the Offline Protocol MCP server.