One curl. One binary.
Pulls the right build for your OS and architecture, drops it in ~/.local/bin, runs ringlet init.
- macOS 13+
- Linux x86_64
- Linux aarch64
- Rust 1.85+
1. Install
curl -fsSL https://raw.githubusercontent.com/neul-labs/ringlet/main/install.sh | shOr with Cargo if you have the Rust toolchain:
cargo install ringletOr build from source:
git clone https://github.com/neul-labs/ringlet
cd ringlet
cargo build --release
cp target/release/ringlet ~/.local/bin/2. Initialise
The init flow detects every supported agent CLI on your $PATH, imports any existing usage logs, and writes the keychain entries it needs.
ringlet init
# Output:
# ✓ Detected: claude (2.0.5), codex (1.4.0), grok (0.7.1)
# ✓ Imported 18,432 usage events from ~/.claude/usage.jsonl
# ? Anthropic API key (stored in macOS Keychain): [sk-ant-...]
# ✓ Stored: ringlet/anthropic/default3. Create a profile
A profile binds an agent to a provider and gives it its own HOME.
ringlet profiles create claude work --provider anthropic
# To bind to a different provider:
ringlet profiles create claude personal --provider minimax
ringlet profiles create codex staging --provider openai4. Run an agent
ringlet profiles run work
# Behind the scenes, Ringlet:
# - exports HOME=~/.ringlet/profiles/work
# - exports ANTHROPIC_API_KEY (from keychain)
# - exports ANTHROPIC_BASE_URL (from profile config)
# - execs claude in the current TTY5. See what it cost
ringlet usage
# Or export for billing reconciliation:
ringlet usage --export csv > may-2026.csv
ringlet usage --profile work --since 2026-05-016. (Optional) Web dashboard
Ringlet ships a Vue 3 + xterm.js dashboard. Run the daemon and open it in a browser:
ringlet daemon --stay-alive --foreground &
open http://127.0.0.1:8765The daemon binds to localhost only and uses a bearer token stored at ~/.config/ringlet/http_token. If you'd rather a native app, install ringlet-app (Tauri).
7. (Optional) Remote agent sessions
Run the daemon on a server you SSH to. From your laptop, launch agents remotely — the PTY is proxied over a WebSocket, and the agent runs inside a sandbox.
# On the server
ringlet daemon --stay-alive# On the laptop
ringlet profiles run work --remote dev-box.internal:8765Platform support
- macOS: 13+ (Ventura), Intel and Apple Silicon. Keychain integration via
Security.framework. - Linux: x86_64 and aarch64. GNOME Keyring or KWallet via the Secret Service API; fallback to
~/.config/ringlet/credentials.toml(mode 0600). - Windows: coming. Credential Manager support is implemented; remote PTY needs polish.
- Rust toolchain: 1.85+ if you're building from source.
Uninstall
rm -rf ~/.ringlet ~/.config/ringlet ~/.local/bin/ringlet
# Then delete keychain entries:
ringlet keychain purge # (run before deleting the binary)