Glossary.
The vocabulary Ringlet uses — profiles, providers, hooks, sandboxes — defined in plain language. Each links to where the concept shows up in practice.
- # Profile
-
Ringlet's core unit: (agent + provider + credentials + isolated HOME). Each profile has its own HOME directory, credentials, conversation history, MCP config, and trust cache, so two profiles never share state.
Profile isolation → - # Agent CLI
-
A command-line AI coding tool such as Claude Code, Codex CLI, Grok CLI, Droid, or OpenCode. Ringlet orchestrates these unchanged — it manages their environment rather than replacing them.
Supported agents → - # Provider
-
The model endpoint an agent talks to — Anthropic, OpenAI, MiniMax, OpenRouter, or any OpenAI/Anthropic-compatible gateway. Ringlet binds a provider to a profile and injects its base-URL and credentials at launch.
Provider matrix → - # Provider injection
-
The launch-time step where Ringlet sets the environment variables (base-URL, credentials) that point an agent at its bound provider, without editing the agent's own config file.
How it works → - # Wire format
-
The request/response shape an agent speaks — Anthropic-shaped or OpenAI-shaped. Ringlet maps a profile's provider to the agent's wire format so, e.g., an Anthropic-shaped agent can run against an Anthropic-compatible proxy.
- # Cost ledger
-
A per-profile SQLite database where Ringlet records token and dollar spend parsed from each agent's streaming usage events, tagged with timestamp, model, and provider. `ringlet usage` aggregates it.
Cost visibility → - # Event hook
-
A shell command or webhook fired on a lifecycle event: pre-tool-use, tool-use, stop, notify, cost-threshold, or daily-rollup. Used for audit logs, Slack alerts, and pre-flight guards.
Auditing tool use → - # Sandbox
-
The isolation layer a remote session runs in — bubblewrap (bwrap) on Linux, sandbox-exec on macOS — constraining an agent's filesystem and process access so it can't reach beyond its workspace.
Security → - # Daemon
-
Ringlet's optional local process. It runs only when you want the web dashboard or a remote session, binds to 127.0.0.1:8765, and requires a bearer token. The CLI works with no daemon at all.
How it works → - # Remote session
-
Running an agent on a server via the Ringlet daemon and driving its PTY from your laptop's browser over an authenticated WebSocket, rendered with xterm.js. The agent runs sandboxed.
Remote sessions → - # Keychain-backed credentials
-
API keys stored in the OS secret store — macOS Keychain, GNOME Keyring / KWallet, Windows Credential Manager — instead of plain-text config. A mode-0600 file is used only when no keychain is available.
How it works → - # Registry
-
A shareable TOML repo of standard profile definitions. `ringlet registry add team <url>` pulls it so a whole team has the same named profiles pointed at the same providers.
For teams → - # MCP config
-
Per-profile Model Context Protocol server configuration. Because each profile is isolated, one profile can point an MCP server at staging while another points at production with no cross-contamination.
- # N/A — Ringlet is not a gateway
-
Ringlet does not proxy individual model completions the way LiteLLM or OpenRouter do. It sits one level above the agent CLI, binding an agent to a provider before launch. Gateways work great as Ringlet providers.
vs LiteLLM →