Frequently asked questions

Because each one wants to own ~/.claude or ~/.config/codex and they conflict. Project A's API key leaks into project B. You can't run two Claude Code instances on different providers at the same time. Token spend is invisible until the invoice arrives. Ringlet solves all of that with hard profile isolation — separate HOMEs, separate caches, separate histories — plus per-profile provider binding and a single cost dashboard.

First-party support for Anthropic, OpenAI, MiniMax, and OpenRouter. Anything OpenAI-compatible (Groq, Together, Fireworks, your own gateway) works via a custom-provider TOML stanza. Anthropic-shaped agents (Claude Code, Droid, OpenCode) can be pointed at MiniMax or any anthropic-compatible proxy without touching the agent's config.

Ringlet itself is free and MIT-licensed. You only pay the underlying model providers (Anthropic, OpenAI, etc.) for the tokens your agents consume — Ringlet just makes that spend visible.

No. Ringlet is a single Rust binary you install on your laptop or dev box. It runs an embedded daemon on localhost:8765 for the web UI and the desktop app, with bearer-token auth and localhost-only binding by default. There is no cloud component you depend on.

Run `ringlet daemon --stay-alive` on a server you SSH to, and `ringlet profiles run my-project --remote` from your laptop. The daemon starts the agent inside a sandbox (bwrap on Linux, sandbox-exec on macOS) and proxies the PTY over an authenticated WebSocket. The web dashboard renders it with xterm.js. The agent never has shell access to your laptop.

Give each one a Ringlet profile. A profile is (agent + provider + credentials + isolated HOME), so a Claude Code profile and a Codex profile never share state — separate HOME directories, separate conversation history, separate credentials stored in the OS keychain. Ringlet parses the token-usage events every agent emits and writes them to a SQLite ledger, so `ringlet usage` shows spend across all of them — every agent, every provider, in one place. Setup is three commands: `ringlet profiles create claude work --provider anthropic`, `ringlet profiles create codex work --provider openai`, then `ringlet usage` to see the combined cost.

Bind the profile to that provider — `ringlet profiles create claude work --provider minimax` (or `openrouter`). Claude Code is Anthropic-shaped, so Ringlet can point it at MiniMax, OpenRouter, or any Anthropic-compatible proxy by injecting the right base-URL and credential env vars at launch. The agent's own config is never touched, and the credentials live in the keychain rather than in a dotfile. Anything OpenAI-compatible (Groq, Together, Fireworks, your own gateway) works the same way via a custom-provider TOML stanza.

You don't set them by hand — that's the whole point of a profile. Each agent CLI wants to own a single dotdirectory (~/.claude, ~/.config/codex), so running several accounts or projects normally means juggling CLAUDE_CONFIG_DIR / CODEX_HOME by hand and hoping you don't cross-contaminate. Ringlet gives each profile its own isolated HOME and sets those variables for you at launch. `ringlet profiles run work` starts the right agent, pointed at the right HOME, credentials, and provider — no env-var exports, no leaked keys between projects.

Claude Squad and Conductor are great at running multiple agents in parallel on git worktrees. Ringlet's primary unit isn't a parallel task — it's a long-lived profile that survives across sessions. You can absolutely combine them: use Ringlet for credential/provider isolation across projects, and Claude Squad inside a Ringlet shell for parallel tasks within one project.

LiteLLM and OpenRouter are LLM gateways — they sit between an application and a model API. Ringlet sits above the agent CLI; it doesn't proxy individual completions, it binds an agent (e.g. Claude Code) to a provider (e.g. MiniMax) before launch. You can use LiteLLM or OpenRouter as a Ringlet provider — they're complementary tools, not competitors.

In the system keychain: macOS Keychain via Security.framework, GNOME Keyring via the Secret Service API, Windows Credential Manager via wincred. Never in plain-text config files. The Rust `keyring` crate handles the platform abstraction. If you opt out of the keychain (e.g. on a headless server), keys go in `~/.config/ringlet/credentials.toml` with file mode 0600.

Yes. `ringlet import claude` reads `~/.claude/conversations` and `~/.claude/usage.jsonl`, attributing them to a profile you pick. Same for Codex (`~/.codex/sessions`). Future runs of those agents from inside a Ringlet profile write to the profile's HOME, leaving your original directories untouched.

MCP servers live inside each agent — Claude Code, Codex, etc. already speak MCP. Ringlet's contribution is that each profile gets its own MCP config: project A can have a Postgres MCP server pointed at staging while project B has one pointed at production, with zero risk of cross-contamination.

Ringlet parses the token-usage events each agent emits (Anthropic, OpenAI, and MiniMax all expose input/output token counts in their streaming responses). It writes them to a SQLite database in the profile's HOME with timestamps, model name, and provider. `ringlet usage` aggregates across profiles; `ringlet usage --export csv` dumps for billing reconciliation.

Plugin SDK (Rhai-scriptable hooks), cross-device profile sync, a Tauri-packaged desktop app for non-CLI users (already shipping for power users), and a team tier with shared profiles + centralized provider policy. Enterprise: SSO, audit trails, private registry hosting, air-gapped deployment.

Ringlet is at 0.1.0. The core profile-isolation, provider-switching, and usage-tracking flows are stable and tested. The CLI surface is intentionally small. Remote sessions and the desktop app are functional but recent — file issues on GitHub if you hit anything.