Frequently asked questions
The things developers ask in the first hour. If your question isn't here, file an issue on GitHub.
Ringlet is an open-source (MIT) CLI and daemon that orchestrates multiple AI coding agents — Claude Code, Codex CLI, Grok CLI, Droid, and OpenCode — behind isolated profiles. Each profile has its own HOME directory, credentials, conversation history, and provider binding. A single command (`ringlet profiles run my-project`) launches the right agent with the right model on the right credentials, with usage and cost tracked across all of them.
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.
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.