https://github.com/cjus/solrac
Self-hosted Claude-Code-style Agent over Telegram (Bun runtime)
https://github.com/cjus/solrac
agent anthropic bun claude claude-agent-sdk claude-code coding-agent self-hosted telegram telegram-bot
Last synced: about 1 month ago
JSON representation
Self-hosted Claude-Code-style Agent over Telegram (Bun runtime)
- Host: GitHub
- URL: https://github.com/cjus/solrac
- Owner: cjus
- License: mit
- Created: 2026-05-07T16:38:01.000Z (about 1 month ago)
- Default Branch: main
- Last Pushed: 2026-05-10T21:59:36.000Z (about 1 month ago)
- Last Synced: 2026-05-10T23:23:17.293Z (about 1 month ago)
- Topics: agent, anthropic, bun, claude, claude-agent-sdk, claude-code, coding-agent, self-hosted, telegram, telegram-bot
- Language: TypeScript
- Homepage:
- Size: 1.92 MB
- Stars: 4
- Watchers: 0
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- Contributing: CONTRIBUTING.md
- License: LICENSE
- Code of conduct: CODE_OF_CONDUCT.md
- Roadmap: docs/ROADMAP.md
Awesome Lists containing this project
README
# Solrac
> A self-hosted, hackable personal Agent: free local Ollama by default, Claude Sonnet/Opus on demand via Anthropic's Claude Agent SDK. Reach it from Telegram or a browser; own every audit row, permission rule, and budget cap.
## Why Solrac
Solrac is a single-process Bun agent that bridges Telegram (and an optional browser UI) to a local Ollama model, escalating to Claude Sonnet or Opus only when you explicitly ask. It was built as part of [PNXStudios.com](https://pnxstudios.com) to manage a complex monorepo from anywhere — and, in doing so, to explore the mechanics of building a personal agent from first principles while enforcing hard cost controls and behavior auditing on every turn.
It's deliberately smaller and narrower than other personal-assistant projects:
- **[OpenClaw](https://github.com/openclaw/openclaw)** — Node/TypeScript "Gateway" daemon with macOS/iOS/Android companion apps, Voice Wake, Live Canvas, and ~25 inbound channels.
- **[Hermes Agent](https://github.com/NousResearch/hermes-agent)** (Nous Research) — Python, multi-provider, self-improving agent with seven execution backends and broad transport (Telegram/Discord/Slack/WhatsApp/Signal/Email/CLI).
Both are broader and better-resourced. **Solrac's distinct value:**
- **Local-LLM-first economics.** No-prefix messages route to free Ollama; `@` and `!` are paid Claude escalations only on operator intent.
- **Cost enforcement, not just visibility.** Sliding hourly USD caps that *deny* turns when hit, plus a daily cost-report DM.
- **Audit-before-acting.** Every update (allowed, denied, queue-full) writes a row to one append-only SQLite table.
- **Single-process minimalism.** No HTTP framework, no Telegram framework runtime, no queue server, no Docker, no sub-agents. A few thousand lines of TypeScript you can read in an afternoon and fork.
If you need multi-tenancy, voice wake, mobile companions, or 25 chat platforms, use OpenClaw or Hermes. If you want a small, cost-capped, fully audited foundation you can bend to your shape, Solrac fits.
## Quick start
**Packaged binary** (macOS/Linux):
```sh
curl -fsSL https://cjus.dev/solrac/install.sh | sh
```
**From source** (Bun required):
```sh
git clone https://github.com/cjus/solrac.git
cd solrac && npm install && cp .env.example .env
npm run dev
```
Need help with Bun, a Telegram bot, or an Anthropic API key? See [docs/SETUP.md](./docs/SETUP.md) (~20 min walkthrough). Full install reference at [docs/INSTALL.md](./docs/INSTALL.md).
## Documentation
| Doc | Audience | What it covers |
|-----|----------|---------------|
| [docs/FEATURES.md](./docs/FEATURES.md) | Everyone | Complete feature list, grouped by theme |
| [docs/INSTALL.md](./docs/INSTALL.md) | Operators | curl-pipe install, `~/.solrac/` layout, upgrade & uninstall |
| [docs/SETUP.md](./docs/SETUP.md) | First-time users | Bun, Telegram bot, `from.id`, Anthropic key, first boot |
| [docs/USAGE.md](./docs/USAGE.md) | Daily users | Concepts, interaction patterns, permission UX, cost cap, loop detector |
| [docs/CONFIG.md](./docs/CONFIG.md) | Operators | Full env-var reference |
| [docs/ARCHITECTURE.md](./docs/ARCHITECTURE.md) | Developers | Module map, data flow, concurrency, schema, policy, threat model, philosophy, anti-goals |
| [docs/OPERATIONS.md](./docs/OPERATIONS.md) | Operators | systemd deploy, `/health` & `/stats`, daily report, audit queries |
| [docs/SCHEMA.md](./docs/SCHEMA.md) | Operators / debuggers | SQLite schema + query cookbook |
| [docs/RUNBOOK.md](./docs/RUNBOOK.md) | On-call | Incident recovery: cost runaway, drain timeout, db corruption, … |
| [docs/GLOSSARY.md](./docs/GLOSSARY.md) | Everyone | Solrac-specific terms |
| [docs/ROADMAP.md](./docs/ROADMAP.md) | Maintainers | Open questions, deferred enhancements |
## Contact
Open issues against this repository. Project owner: [@cjus](https://github.com/cjus).