Skip to content

v0.1.0 — initial release

Choose a tag to compare

View all tags
@cjus cjus released this 07 May 18:13
· 108 commits to main since this release
v0.1.0
27b8683

v0.1.0 — initial release

Solrac is a self-hosted Claude-Code-style agent that listens to Telegram and uses Anthropic's Claude Agent SDK for thinking and tool use. ~2K lines of TypeScript on Bun.

Install

git clone https://github.com/cjus/solrac.git
cd solrac
npm install
cp .env.example .env       # then fill in 3 required values
npm run dev                # starts on PORT (default 8443)

Full walkthrough (Bun install, Telegram bot creation, Anthropic key): docs/SETUP.md — ~20 minutes.

Highlights

  • Customizable persona via SOUL.md (voice, stance, safety) and SOLRAC.md (operator overlay, re-read every turn)
  • Multi-user, multi-chat gated by per-from.id allowlist
  • Three-tier permission policy — auto-allow / auto-deny / Telegram-inline-keyboard-confirm
  • Dual-Claude tier routing — message prefix picks the model: no prefix or @ → primary, ! → secondary, with cross-tier context bridge
  • Local-Ollama escape hatch (> prefix) — free, offline, pure inference; cross-engine context bridge keeps the conversation thread coherent
  • Slash commands — /help, /status, /context, /clear, /compact
  • Operator-defined skills via SKILL.md (off by default; SOLRAC_SKILLS_ENABLED=true)
  • Per-chat hourly cost cap — sliding 60-minute window, default $1.00/chat/hour
  • Loop detector — denies the third call to the same (toolName, input) within a turn
  • Persistent SQLite audit trail — prompt, response, tool calls, cost, tokens, session id, engine
  • Session resume across restarts — SDK session ids persisted per chat and per tier
  • Bearer-gated /stats endpoint with node:crypto.timingSafeEqual constant-time auth
  • Daily cost report DM'd to the allowlist's first entry; idempotent, UTC-midnight window
  • Graceful shutdown — drains in-flight turns (60s cap), checkpoints WAL, removes PID file
  • Weekly auto-bounce — systemd timer mitigates Bun long-uptime drift
  • DB-pollution defenses — denial throttle, per-chat queue cap, prompt truncation
  • Sub-agent default-deny at SDK + policy layers

Stack

  • Bun ≥ 1.3, TypeScript, bun:sqlite, @anthropic-ai/claude-agent-sdk

Known limits / deferred to v1.x

  • No webhook transport — poll-only in v0.1.0. Webhook mode is in docs/ROADMAP.md.
  • No sub-agents — Agent/Task tools are default-deny at the SDK + policy layers (OQ#8).
  • No Bedrock/Vertex auth — direct ANTHROPIC_API_KEY only. Multi-cloud is an explicit anti-goal in v1.
  • Cache-token telemetry on /status — captured in audit + shown on /context, but not yet aggregated into /status (deferred to v1.1).
  • Single-operator scale — no multi-tenant UI, no role hierarchy. If you need that, fork it.

Docs

ARCHITECTURE.md · SETUP.md · USAGE.md · OPERATIONS.md · RUNBOOK.md · CONFIG.md

Assets 2
Loading