Your agents. Your machine. From anywhere.
Run autonomous AI agents on your machine. Monitor them from any device through P2P encrypted connections the server can never read.
- Zero-Knowledge Architecture — Keys exchanged offline via QR code. The server relays encrypted blobs it can never read.
- Multi-Agent Management — Run 20+ agents simultaneously, each in isolated git worktrees. Manage from the TUI or your browser.
- Plugin System — Extensible Lua plugin architecture with a template catalog for one-click install from the browser.
- Local-First Execution — Agents run on your hardware. Keys live in your OS keychain. No cloud execution, no vendor lock-in.
- Agents & Accessories — Define AI agents and plain PTY accessories at device or repo level. Workspace manifests auto-spawn groups of sessions with optional port forwarding over encrypted WebRTC.
The server sees nothing. Privacy by architecture, not policy.
- Offline key exchange — Encryption keys shared via QR code. They never touch the server.
- Encrypted signaling — The server only negotiates handshakes, and even those are encrypted blobs it relays without any ability to read.
- P2P data channel — After handshake, connections are direct P2P. Data is encrypted with vodozemac (the Matrix Foundation's audited Olm implementation) on top of WebRTC encryption.
- No trust required — The server cannot decrypt your data, even if compromised.
curl -fsSL https://raw.githubusercontent.com/Tonksthebear/trybotster/main/install.sh | shDetects your platform, downloads the latest release, verifies the checksum, and installs to /usr/local/bin.
| Platform | Binary |
|---|---|
| macOS (Apple Silicon) | botster-macos-arm64 |
| macOS (Intel) | botster-macos-x86_64 |
| Linux (x86_64) | botster-linux-x86_64 |
| Linux (ARM64) | botster-linux-arm64 |
Download from GitHub Releases, chmod +x, and move to a directory in your PATH.
Requires Rust toolchain:
git clone https://github.com/Tonksthebear/trybotster.git
cd trybotster/cli
cargo build --release
# Binary at: target/release/botsterThe CLI checks for updates on launch. You can also update manually:
botster update # Download and install latest
botster update --check # Check without installingRun botster start from the root of the project you want agents to work in:
cd ~/projects/my-app
botster startOn first run, the CLI will prompt you to name your hub (defaults to the repo name) and walk you through device authorization:
Setting up a new Botster hub.
Name this hub (Enter for "my-app"):
To authorize, visit:
https://trybotster.com/hubs/codes/WDJB-MJHT
Code: WDJB-MJHT
Press Enter to open browser (or visit the URL above)...
Visit the URL, sign in with GitHub, and approve. Token is saved securely in your OS keychain.
Set up a .botster/ directory in your repo (see Repository Setup) or use the browser Settings page to configure sessions and install templates.
Open trybotster.com/hubs and scan the QR code displayed in the TUI. This establishes the E2E encrypted P2P connection — the server never sees your data.
Create agents from the browser or from the TUI menu (Ctrl+P). Terminal output streams in real-time over the encrypted connection.
Browser / TUI
|
Create agent (manual or plugin-triggered)
|
Rust daemon receives command
|
Creates git worktree
|
Spawns session PTYs (agent, server, etc.)
|
Agent works in isolation
|
Monitor via E2E encrypted WebRTC
Rails server (trybotster.com) — User auth, hub management, template catalog, plugin event channels. Relays E2E encrypted data it cannot decrypt.
Rust daemon (botster) — Interactive TUI with ratatui, event-driven Lua runtime for agent lifecycle, creates isolated git worktrees, spawns sessions in PTYs, streams terminal over encrypted WebRTC.
Lua runtime — Hot-reloadable event-driven plugin system. Core handlers manage agent lifecycle, WebRTC signaling, hub commands, and TUI keybindings. User-extensible via plugins in .botster/.
The TUI has two primary modes:
Normal mode — Command mode, no PTY forwarding:
i - Enter insert mode (forward keys to PTY)
Ctrl+P - Open menu
Ctrl+J - Next agent
Ctrl+K - Previous agent
Ctrl+] - Toggle PTY session
Ctrl+R - Refresh agents
Ctrl+Q - Quit daemon
Insert mode — Keys forward to the active PTY. Modifier combos still work:
Ctrl+P - Open menu
Ctrl+J / Ctrl+K - Switch agents
Ctrl+] - Toggle PTY session
Shift+PageUp - Scroll half page up
Shift+PageDown - Scroll half page down
Shift+Home - Scroll to top
Shift+End - Scroll to bottom
Ctrl+Q - Quit daemon
Each repository that uses Botster needs a .botster/ configuration directory. You can set this up manually or use the browser Settings page (Settings > Config tab) to create and edit files over E2E encrypted connections. Session and plugin templates are available for one-click install from the Settings > Templates tab.
.botster/
agents/
claude/ # Agent definition (AI-driven PTY)
initialization # startup script (required: at least one agent)
accessories/
rails-server/ # Accessory definition (plain PTY, no AI)
initialization # startup script
port_forward # sentinel file — session gets $PORT
workspaces/
dev.json # Workspace manifest (auto-spawn group)
plugins/
{name}/init.lua # Lua plugins
Configuration is resolved across 2 layers (repo wins on collision):
- Device (
~/.botster/) — Personal defaults for all repos - Repo (
{repo}/.botster/) — Project-specific config (highest priority)
At least one agent config is required. Agents, accessories, and plugins are all merged per-name with repo overriding device.
An accessory that runs a dev server with port forwarding:
.botster/accessories/server/initialization # contains: bin/dev
.botster/accessories/server/port_forward # empty sentinel file
The port_forward sentinel file tells Botster to assign a $PORT and tunnel it over encrypted WebRTC for browser preview.
Plugins are Lua scripts that extend Botster's behavior. They live in .botster/plugins/{name}/init.lua at either the device or repo level, with repo overriding device.
The easiest way to install plugins is from the browser: go to your hub's Settings > Templates tab, which shows a catalog of available plugins. One click installs to either device or repo scope.
You can also create plugins manually by adding an init.lua to the appropriate plugins directory.
The GitHub plugin subscribes to webhook events for your repository and automatically creates agents when @botster is mentioned in issues or PRs. Install it from the Templates catalog.
Once installed, mentioning @botster in a GitHub issue or PR will:
- Create a git worktree for the issue
- Spawn an agent with the mention context
- Agent investigates and creates a PR or comments with findings
- Issue/PR closed triggers automatic cleanup
The plugin also:
- Fetches a scoped MCP token so agents can use GitHub tools (showing as
@trybotster[bot]) - Routes new mentions to existing agents instead of spawning duplicates
- Posts notifications back to GitHub when agents ask questions
Plugins have access to the full Lua runtime API: events, hooks, action_cable, http, json, secrets, log, and more. See the GitHub plugin source for a comprehensive example.
Environment variables:
| Variable | Default | Description |
|---|---|---|
BOTSTER_SERVER_URL |
https://trybotster.com |
Rails backend URL |
BOTSTER_WORKTREE_BASE |
~/botster-sessions |
Where to create worktrees |
BOTSTER_POLL_INTERVAL |
5 |
Seconds between polls |
BOTSTER_MAX_SESSIONS |
20 |
Max concurrent agents |
BOTSTER_AGENT_TIMEOUT |
3600 |
Agent timeout in seconds |
BOTSTER_TOKEN |
— | Skip device flow (for CI/CD) |
Supported terminals: Ghostty (recommended), iTerm2, or any terminal supporting OSC 9 notifications. macOS Terminal.app does not support agent notifications.
Each spawned agent has access to:
BOTSTER_REPO=owner/repo
BOTSTER_ISSUE_NUMBER=123
BOTSTER_BRANCH_NAME=botster-issue-123
BOTSTER_WORKTREE_PATH=/path/to/worktree
BOTSTER_PROMPT="User's request text"
BOTSTER_MESSAGE_ID=42
BOTSTER_TOKEN=your_api_key
BOTSTER_TUNNEL_PORT=4001Additional env vars may be injected by plugins (e.g., the GitHub plugin adds BOTSTER_MCP_TOKEN and BOTSTER_MCP_URL).
botster mcp-serve resolves hub context from BOTSTER_SESSION_UUID.
Use a single Codex MCP server entry named botster (do not register additional Botster MCP aliases in session scripts).
For Botster agent sessions, launch Codex with --no-alt-screen so PTY scrollback is preserved.
Accessory sessions can keep Codex default/auto alternate-screen behavior.
Configure Codex to forward that PTY env var to the MCP subprocess:
[mcp_servers.botster]
command = "botster"
args = ["mcp-serve"]
env_vars = ["BOTSTER_SESSION_UUID"]Verify:
codex mcp get botsterThe output should show env_vars: BOTSTER_SESSION_UUID.
The Settings > Templates tab in the browser provides a catalog of installable templates:
- Sessions — Pre-configured session initialization scripts (e.g., Claude agent session)
- Plugins — Lua plugins (e.g., GitHub integration)
- Initialization — User init.lua for custom hooks and commands
Templates can be installed to either device scope (~/.botster/) or repo scope ({repo}/.botster/) and are transferred over E2E encrypted connections.
Rust CLI: Always use the test script:
cd cli
./test.sh # Run all tests
./test.sh --unit # Unit tests only
./test.sh -- scroll # Tests matching 'scroll'Rails: rails test or rspec.
Contributions welcome! See the GitHub repository.
O'Saasy License — Free to use, modify, and distribute. Cannot be repackaged as a competing hosted/SaaS product.