Everything Ringlet does, in one page.

Profile isolation

A Ringlet profile is a long-lived bundle of (agent, provider, credentials, conversation history). Each one gets its own HOME directory, populated with whatever the agent expects to find there. Two Claude Code profiles never see each other's ~/.claude/conversations; two Codex profiles never share a cache. Switching contexts is ringlet profiles run other-project.

# Two Claude Code profiles on different Anthropic accounts:
ringlet profiles create claude work     --provider anthropic --key-alias work
ringlet profiles create claude personal --provider anthropic --key-alias personal

# They live side by side:
ls ~/.ringlet/profiles
# work  personal

# Run them in two terminals — they share nothing.
ringlet profiles run work     # terminal A
ringlet profiles run personal # terminal B

Provider switching

Each profile names a provider. At launch, Ringlet sets the correct base URL and API key environment variables for the agent it's about to run. The agent itself never knows it's been re-pointed.

# Same Claude Code, different providers per profile:
ringlet profiles set work     --provider anthropic
ringlet profiles set personal --provider minimax
ringlet profiles set fast     --provider openrouter --model anthropic/claude-3.5-haiku

# Verify:
ringlet profiles run fast --dry-run
# → exec claude
#   HOME=~/.ringlet/profiles/fast
#   ANTHROPIC_BASE_URL=https://openrouter.ai/api/v1
#   ANTHROPIC_API_KEY=*** (keychain)
#   ANTHROPIC_MODEL=anthropic/claude-3.5-haiku

Cost tracking

Ringlet parses the token-usage events each provider streams back (Anthropic, OpenAI, and MiniMax all expose input/output token counts) and writes them to a per-profile SQLite ledger with timestamps, model name, and provider. Aggregation lives in one CLI command.

ringlet usage
# PROFILE     AGENT        PROVIDER    TOKENS         COST
# work        claude       anthropic   1.21M / 340K   $8.41
# personal    claude       minimax     2.83M / 820K   $0.92
# staging     codex        openai      0.45M / 90K    $1.40
# ─────────────────────────────────────────────────────────
# TOTAL                                                $10.73

ringlet usage --since 2026-05-01 --export csv > may.csv
ringlet usage --profile work --by-day

Event hooks

Subscribe shell commands or webhooks to lifecycle events: agent start, agent stop, tool use, notification, cost-threshold-crossed. Audit trail, Slack ping, CI-style guardrail — pick your shape.

# Audit every tool use to a file:
ringlet hooks add work --on tool-use \
  --shell 'echo "$(date -u) $RINGLET_PROFILE $RINGLET_TOOL" >> ~/audit.log'

# Page Slack when a profile crosses $10/day:
ringlet hooks add work --on cost-threshold --threshold 10 \
  --webhook 'https://hooks.slack.com/services/...'

# Reject 'rm -rf' from a tool call before the agent sees it execute:
ringlet hooks add work --on pre-tool-use --filter 'rm -rf' --action deny

Remote terminal sessions

Run the daemon on a server you SSH to, then launch agents on the server from your laptop. The PTY is proxied over an authenticated WebSocket. The agent runs inside bwrap (Linux) or sandbox-exec (macOS) with a read-only system root and an explicit workspace mount.

ringlet daemon --stay-alive --listen 0.0.0.0:8765

ringlet profiles run work --remote dev-box.internal:8765
# Or via browser:
# → https://dev-box.internal:8765 (xterm.js dashboard)

Web dashboard + desktop app

The daemon ships a Vue 3 + xterm.js dashboard at http://127.0.0.1:8765. It manages profiles, renders usage analytics, and lets you launch agent sessions from the browser. There's also a native Tauri wrapper (ringlet-app) if you'd rather not keep a browser tab.

Keychain credential storage

API keys go in the OS-native credential store via the Rust keyring crate: macOS Keychain (Security.framework), GNOME Keyring or KWallet (Secret Service API), Windows Credential Manager. If you opt out (e.g. on a headless server), keys go in ~/.config/ringlet/credentials.toml with mode 0600.

Registry

Ringlet caches an offline-capable index of supported agents and providers (GitHub-hosted JSON, signed). New agent CLIs and providers ship without a Ringlet upgrade — sync the registry and a new entry shows up.

ringlet registry sync
ringlet registry list --kind agents
ringlet registry list --kind providers

Scripting (Rhai)

Hooks support inline shell, file paths, and Rhai scripts — a small embedded scripting language. Useful when you want richer logic than a shell one-liner but don't want to write a real plugin yet.

fn on_tool_use(ctx) {
  if ctx.tool == "bash" && ctx.input.contains("rm -rf") {
    return deny("Refusing destructive shell.");
  }
  log_to_file("/tmp/ringlet-audit.log", `${ctx.profile} ${ctx.tool}`);
}