Setup command

lore setup [app] configures a supported AI coding agent to route its requests through the Lore gateway. It writes the right config file (or, for agents that don’t read env vars at runtime, the right -c override) so the agent’s API calls land on the gateway instead of going to the upstream provider directly.

When to use `lore setup`

Codex Desktop — the Desktop app does not accept -c CLI overrides at launch and has no obvious way to inject a custom openai_base_url through its UI. lore setup codex writes ~/.codex/config.toml once and the Desktop app picks it up on next launch. This is the recommended path for Codex Desktop.
Codex CLI without lore run — if you’d rather start the gateway yourself and launch Codex directly (for example, in a long-running dev workflow where you don’t want lore run to manage the gateway lifecycle), lore setup codex writes the same config.
OpenCode without lore run — lore setup opencode writes ~/.config/opencode/opencode.json with the gateway URL and disables OpenCode’s built-in auto-compaction. It also installs the @loreai/opencode plugin and registers it in the plugin array, which is what makes the integration worth having (transparent per-session routing, project-path injection, per-session cost rollups). Pass --no-plugin to skip the install (useful in CI, air-gapped networks, or when npm is not on PATH).
Claude Code without lore run — lore setup claude-code writes ~/.claude/settings.json with env.ANTHROPIC_BASE_URL and env.DISABLE_AUTO_COMPACT.
Pi without lore run — lore setup pi writes ~/.pi/agent/models.json, pointing every gateway-routable provider’s baseUrl at the gateway (Anthropic-family providers at the root, OpenAI-family at /v1). Pi has no env-var base-URL override, so this file is the only way to route a standalone pi without the @loreai/pi extension. For richer, dynamic routing plus memory features, install the extension instead (add npm:@loreai/pi@latest to the packages array in ~/.pi/settings.json, then run pi install).
Hermes Agent without lore run — lore setup hermes writes ~/.hermes/.env with OPENAI_BASE_URL (the gateway URL, including /v1) and HERMES_INFERENCE_PROVIDER=custom. Hermes loads that .env at launch (via python-dotenv), so a standalone hermes routes through the gateway — the persistent equivalent of what lore run hermes injects.
Remote gateway — lore setup <app> -r http://remote:3207 writes the config pointing at a non-default gateway URL, useful when the gateway runs on a different machine (Tailscale, LAN, a hosted deployment) and you want the local client to talk to it.

Gateway access authentication is optional. When a remote/hosted gateway configures LORE_GATEWAY_AUTH_TOKEN, clients must supply that separate access credential. lore setup -r intentionally writes only non-secret routing configuration; it never persists the token. Export LORE_REMOTE_URL and, when configured on the gateway, LORE_GATEWAY_AUTH_TOKEN when launching an adapter-capable client (OpenCode or Pi), or configure the direct client to send one x-lore-gateway-token header. A provider API key or bearer token is not gateway authorization. Clients that support only a base URL and no custom headers need an adapter or a trusted header-injecting edge proxy.

If you launch your agent through lore run, you do not need lore setup — lore run injects the right config (env vars or -c overrides) into the child process at launch. lore setup <app> is for the other case: launching the agent directly (a GUI/IDE app, or a standalone CLI) where a persistent config file is the only integration point. Each supported app reads provider config from its own file — Codex/Pi from a JSON/TOML config, Claude Code/Hermes from an env file, OpenCode from JSON plus a plugin — so lore setup writes the persistent config they need.

Usage

lore setup                     # Auto-detect installed supported apps and configure them
lore setup codex               # Configure Codex explicitly
lore setup opencode            # Configure OpenCode explicitly
lore setup claude-code         # Configure Claude Code explicitly
lore setup pi                  # Configure Pi explicitly (~/.pi/agent/models.json)
lore setup hermes              # Configure Hermes Agent explicitly (~/.hermes/.env)
lore setup codex -p 8080       # Configure Codex to talk to a gateway on a non-default port
lore setup codex -r http://remote:3207  # Configure Codex for a remote gateway

If no app is given, lore setup scans $PATH for supported CLIs. It also recognizes an existing ~/.codex/config.toml on any platform. On macOS, it checks ~/Applications and /Applications for Codex Desktop or ChatGPT with bundled Codex support, so the desktop client can be configured without a CLI on $PATH.

Setup prints each skipped app, its detection reason, and the explicit lore setup <app> command. Errors inspecting optional desktop app locations are reported while discovery continues. If Codex has no CLI on $PATH, discovery also preflights its config without writing: unsafe or unreadable paths, invalid TOML, conflicting providers, or invalid Lore backup metadata cause Codex to be reported and skipped so other detected agents can still be configured. Diagnostics identify the validation stage and any filesystem error code without printing config contents. Fix the reported issue before retrying lore setup codex; explicit setup and all configuration writes retain the same safety checks. If nothing is detected, setup exits with a non-zero status without changing configuration. An explicit app name proceeds even when the CLI is missing, allowing you to configure an app installed elsewhere or prepare its configuration before installation.

Supported apps

App	Config written	Notes
`codex`	`~/.codex/config.toml` (with an HTTP-only `lore_http` provider + `model_auto_compact_token_limit`)	Required for Codex Desktop. Idempotent — re-running updates existing fields without losing other settings.
`opencode`	`~/.config/opencode/opencode.json` (with `provider.openai.options.baseURL` + `compaction.auto: false`)	Sets the built-in `openai` provider’s `baseURL` and disables OpenCode’s auto-compaction. Deep-merges with existing config (preserves custom providers, themes, keybinds).
`claude-code`	`~/.claude/settings.json` (with `env.ANTHROPIC_BASE_URL` + `env.DISABLE_AUTO_COMPACT`)	The Anthropic base URL is written without the `/v1` suffix — Claude Code appends `/v1/messages` itself. Deep-merges with existing settings (preserves permissions, hooks, model overrides).
`pi`	`~/.pi/agent/models.json` (with `providers.<id>.baseUrl` for every gateway-routable provider)	Anthropic-family providers point at the gateway root; OpenAI-family at `/v1`. Deep-merges with existing config (preserves custom providers and models). Honors `PI_CODING_AGENT_DIR`. The `@loreai/pi` extension is the richer alternative (dynamic routing + memory features).
`hermes`	`~/.hermes/.env` (with `OPENAI_BASE_URL` + `HERMES_INFERENCE_PROVIDER=custom`)	The base URL keeps its `/v1` suffix (Hermes speaks the OpenAI-compatible wire format). Upserts the two keys and preserves all other lines (credentials, comments). Honors `HERMES_HOME`. A named `model.provider` in `~/.hermes/config.yaml` takes precedence over these env vars.

For Codex, setup selects model_provider = "lore_http" and writes a named Responses provider with requires_openai_auth = true and supports_websockets = false. Its base_url points to the gateway, normalized to end with /v1. This retains Codex authentication and avoids WebSocket retries against Lore’s HTTP-only gateway. The legacy openai_base_url override is also retained. The port defaults to 3207 (the first entry in DEFAULT_PORTS); override with -p or -r.

model_auto_compact_token_limit = 999999999 disables Codex’s built-in auto-compaction so Lore’s gradient context manager and distillation pipeline can do their job. Re-running lore setup resets this value to 999999999 — any custom value you set is overwritten.

Existing installations can opt into HTTP transport by re-running lore setup codex and restarting Codex. Setup preserves unrelated providers and records the complete Lore provider for undo. Codex scopes older sessions by provider; use codex resume --all if they no longer appear after switching. A default profile selecting another provider must be adjusted before setup; see Codex with Lore for compatibility details.

Undoing setup

lore setup undo [app] restores only settings previously changed by lore setup. Lore records each prior value and restores it only when the current value still matches what Lore wrote, so a setting you changed afterward is left untouched.

lore setup undo              # Restore every app with a Lore setup backup
lore setup undo codex        # Restore one app
lore setup undo opencode

This command does not remove the lore executable, Lore’s database or caches, project .lore.md files, or globally installed npm packages. Copilot setup is guidance-only and writes no config, so there is nothing to restore; if COPILOT_API_URL or COPILOT_PROVIDER_BASE_URL is set outside lore run, unset it where your shell or service defines it.

To remove the standalone installation as well, use lore uninstall. It first validates every setup backup, stages the verified standalone executable for reversible removal, applies setup undo, then finalizes executable and installer-owned file removal. If setup restoration fails, the executable is restored. Use lore uninstall --purge only when you also want to delete the default local Lore runtime data; custom data paths are always preserved for manual review.

Verifying the setup

After lore setup codex, launch the gateway in one terminal:

lore start

In a second terminal, run Codex (or launch the Codex Desktop app). In the gateway’s request log you should see requests originating from 127.0.0.1 with model set to your configured Codex model. If you see requests going to api.openai.com instead, the config.toml write was overridden — check that no other tool (Codex’s own first-run wizard, a system service, a different shell profile) is writing to the file after lore setup runs.

A quick check for override-by-another-tool: stat -c '%y' ~/.codex/config.toml. If the mtime updates after the next Codex Desktop launch and you didn’t change anything, another tool is touching the file.

Per-harness notes

Codex Desktop — lore setup codex is the only way to route the Desktop app through Lore (the app does not honor -c CLI overrides at launch). Run it once, leave the gateway running via lore start (or a system service), and the Desktop app routes correctly. If the Desktop app overwrites or ignores your config.toml, run the gateway under a system service manager (systemd, launchd, etc.) so the URL stays stable. Check Codex’s docs for a session-scoped override file at ~/.codex/sessions/<session-id>/config.toml if your Codex version supports it.
Codex CLI — lore run codex is simpler than lore setup codex because it manages the gateway lifecycle and passes -c overrides per-invocation (no persisted config). Use lore setup only when you want to launch Codex without lore run.
OpenCode — lore setup opencode writes provider.openai.options.baseURL to ~/.config/opencode/opencode.json. If you have a custom OpenAI provider configured (e.g. provider.openrouter), the helper only updates the built-in openai provider — your custom providers are preserved. The compaction setting is also disabled by default; you can re-enable it in the same file if you want. By default, lore setup opencode also installs the @loreai/opencode plugin (via npm install -g @loreai/opencode) and registers it in the plugin array of the same config file. The plugin provides transparent per-session routing, automatic project-path injection, and per-session cost rollups in the dashboard — features the config-file approach alone can’t provide. Pass --no-plugin to skip the install (CI, air-gapped, no npm on PATH).
Claude Code — lore setup claude-code writes env.ANTHROPIC_BASE_URL (without the /v1 suffix) to ~/.claude/settings.json. The Anthropic SDK appends /v1/messages itself, so the gateway URL must not have /v1. If you have a project-level .claude/settings.local.json, that file overrides the user-level one — re-run lore setup after editing the project-level file.
Pi — lore setup pi writes providers.<id>.baseUrl for every gateway-routable provider to ~/.pi/agent/models.json (honoring PI_CODING_AGENT_DIR). Pi splits by wire protocol: Anthropic-family providers (anthropic, fireworks, minimax, …) get the gateway root; OpenAI-family providers (openai, openrouter, groq, local runtimes, …) get ${root}/v1. A bare baseUrl override routes Pi’s built-in providers and is a harmless no-op for the rest, so your custom providers and models are preserved. Pi has no base-URL env var, so unlike Hermes there’s no lore run-only shortcut — either run lore setup pi or install the @loreai/pi extension (add npm:@loreai/pi@latest to ~/.pi/settings.json’s packages array and run pi install), which routes all providers dynamically and adds per-session memory features. lore setup undo pi restores the prior config.
Hermes Agent — lore setup hermes upserts OPENAI_BASE_URL (with /v1) and HERMES_INFERENCE_PROVIDER=custom into ~/.hermes/.env (honoring HERMES_HOME), which Hermes loads via python-dotenv at launch. All other lines — API keys, comments, unrelated vars — are preserved, and a #-commented backup block records prior values for lore setup undo hermes. One caveat: a named model.provider in ~/.hermes/config.yaml takes precedence over these env vars (Hermes warns when it detects the mismatch), so if you pin a provider there, set provider: custom in that file too. lore run hermes injects the same pair per-launch without persisting anything.

Next steps

Codex with Lore — full per-harness guide for Codex, including the Codex Desktop caveat and custom-upstream headers.
Custom upstreams — corporate proxies, LiteLLM, Cloudflare AI Gateway. Pairs with lore setup -r for remote gateways.
Architecture — how temporal storage, distillation, and the gradient context manager fit together.