ringlet
Install
architecture

How Ringlet works.

Ringlet sits one level above your agent CLI. The unit is a profile: (agent + provider + credentials + isolated HOME). Ringlet launches the agent with the right environment, tracks its token spend locally, and — for remote work — runs it in a sandbox behind a localhost-only daemon you drive from a browser.

Ringlet architecture: the CLI and daemon launch each agent in an isolated profile HOME, inject the bound provider's credentials, and stream a sandboxed PTY to the browser dashboard. You CLI · browser dashboard 127.0.0.1:8765 xterm.js · bearer auth Ringlet CLI + local daemon profile registry SQLite cost ledger event hooks provider injection OS keychain Keychain · Keyring · WinCred claude · work HOME + anthropic codex · scripts HOME + openai claude · remote sandbox (bwrap) commands exec read keys PTY over authenticated WebSocket
The CLI and daemon launch each agent in its own profile HOME with the bound provider's credentials injected from the OS keychain. Remote sessions run the agent in a sandbox and stream its PTY back to the browser dashboard over an authenticated, localhost-only WebSocket.

The profile is the unit

Every agent CLI assumes it owns a dotdirectory — ~/.claude, ~/.codex — and its own provider default. A Ringlet profile wraps that assumption in a box: an isolated $HOME, its own credentials, its own conversation history, its own MCP config, and a bound provider. Two Claude Code profiles never see each other's state.

Provider injection happens at launch

Ringlet never rewrites the agent's own config. When you run a profile, it sets HOME, looks up the bound provider, injects that provider's base-URL and credentials as environment variables, and execs the agent unchanged. That's how an Anthropic-shaped agent like Claude Code can talk to MiniMax or your own gateway without touching a config file.

Credentials live in the OS keychain

Keys go into the system keychain — macOS Keychain, GNOME Keyring / KWallet via the Secret Service API, Windows Credential Manager — not plain-text dotfiles. On a headless box with no keychain, they fall back to ~/.config/ringlet/credentials.toml at mode 0600.

The daemon is optional and local

The CLI works with no daemon. A local daemon runs only when you want the web dashboard or a remote session — it binds to 127.0.0.1:8765, requires a bearer token, and never exposes a public endpoint. The Vue 3 dashboard renders agent PTYs with xterm.js.

Remote sessions are sandboxed

Run ringlet daemon --stay-alive on a server and ringlet profiles run … --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 agent never gets shell access to your laptop.

From install to audited spend, in four commands

  1. ringlet init Ringlet detects the agent CLIs you already have (Claude Code, Codex, Grok, Droid, OpenCode) and imports any existing usage logs.
  2. Create a profile ringlet profiles create claude work --provider anthropic creates an isolated HOME, stores credentials in the OS keychain, and binds a provider.
  3. Run the agent ringlet profiles run work sets HOME plus the provider base-URL and credentials, then execs the agent unchanged.
  4. Audit the spend ringlet usage aggregates token and dollar cost across every profile and provider from a local SQLite ledger.
terminal 
ringlet init
ringlet profiles create claude work --provider anthropic
ringlet profiles run work
ringlet usage

Go deeper: all features · security & sandboxing · providers · use cases · glossary

ship it

Now that you know how it fits together — install it.

One curl, one Rust binary, under a minute. Open source under MIT.

Install Ringlet See use cases