data-analysis

---

Starpod is an open-source AI agent runtime built in Rust. Bootstrap an agent in any directory with starpod init, then run it locally or deploy to the cloud. Each agent gets its own memory, vault, filesystem, and sessions — all self-contained in a .starpod/ directory.

Install

curl -fsSL https://starpod.sh/install | sh

Or via Homebrew:

brew install sinaptik-ai/tap/starpod

# From crates.io
cargo install starpod

# From source
git clone https://github.com/sinaptik-ai/starpod.git
cd starpod
cargo install --path crates/starpod --locked

Quick start

# Initialize an agent
starpod init --name "Jarvis" --model anthropic/claude-haiku-4-5

# Seed your API key into the vault
starpod init --env ANTHROPIC_API_KEY=sk-ant-...

# Start the dev server (opens browser)
starpod dev

  ╭──────────────────────────────────────────╮
  │      Jarvis  ·  AI Assistant             │
  ╰──────────────────────────────────────────╯

  Server 127.0.0.1:3000
  API Key sp-abc123...

Or use the terminal:

starpod chat "What files are in this directory?"
starpod repl

Highlights

• Simple setup — starpod init bootstraps everything. No workspace files, no blueprints, no separate instance management.
• Multi-channel — Web UI, Telegram, CLI, HTTP API, WebSocket streaming. Same agent, every surface.
• Persistent memory — markdown files + SQLite FTS5. Per-user memory spaces. The agent remembers across sessions.
• Self-extending skills — the agent creates, edits, and deletes its own skill files at runtime. /skill and it executes.
• Encrypted vault — AES-256-GCM credential storage. API keys never touch disk in plaintext. No .env files — vault only.
• Cron scheduling — interval, cron expressions, one-shot. Runs through the full agent loop, records history.
• Channel-aware sessions — explicit sessions for web/API, time-gap sessions for Telegram. Per-user scoping.
• Streaming — real-time text deltas and tool-use events over WebSocket.
• Built in Rust — 16 crates, 1,362 tests, zero warnings.

Architecture

crates/
├── agent-sdk/            Claude API client + agent loop
├── starpod-hooks/        Lifecycle hooks, events, permissions
├── starpod-core/         Config, shared types, errors
├── starpod-db/           Unified SQLite (core.db)
├── starpod-memory/       FTS5 full-text search + per-user memory
├── starpod-vault/        AES-256-GCM encrypted credentials
├── starpod-session/      Channel-aware session lifecycle
├── starpod-skills/       Markdown-based self-extension
├── starpod-cron/         Scheduling (interval, cron, one-shot)
├── starpod-agent/        Orchestrator wiring everything together
├── starpod-gateway/      Axum HTTP/WS server + embedded web UI
├── starpod-telegram/     Telegram bot (teloxide)
├── starpod-instances/    Remote instance management
└── starpod/              CLI binary

Agent layout

Each agent is self-contained in a .starpod/ directory:

.starpod/
├── config/
│   ├── agent.toml          Agent configuration
│   ├── SOUL.md             Personality
│   ├── HEARTBEAT.md        Periodic self-reflection
│   ├── BOOT.md             Boot instructions
│   ├── BOOTSTRAP.md        First-run instructions
│   └── frontend.toml       Web UI config
├── skills/                 Skill files
├── db/
│   ├── core.db             Sessions + cron + auth
│   ├── memory.db           FTS5 + vectors
│   └── vault.db            Encrypted credentials
└── users/<id>/
    ├── USER.md             User profile
    ├── MEMORY.md           Memory index
    └── memory/             Daily logs

Configuration

All configuration lives in a single agent.toml:

agent_name = "Nova"
models = ["anthropic/claude-haiku-4-5"]
max_turns = 30
server_addr = "127.0.0.1:3000"

[channels.telegram]
allowed_users = [123456789]

Secrets live in the vault (vault.db), seeded via starpod init --env KEY=VAL or the web UI Settings page. No .env files.

Personality in SOUL.md — not in config.

Agent tools

API

WebSocket at ws://localhost:3000/ws. Auth via X-API-Key header or ?token= param.

← {"type": "message", "text": "Hello"}
→ {"type": "stream_start", "session_id": "..."}
→ {"type": "text_delta", "text": "Hi "}
→ {"type": "text_delta", "text": "there!"}
→ {"type": "tool_use", "name": "Read", "input": {...}}
→ {"type": "tool_result", "content": "..."}
→ {"type": "stream_end", "cost_usd": 0.004}

Telegram

1. Create a bot with @BotFather
2. Store the token in the vault (via starpod init --env TELEGRAM_BOT_TOKEN=... or Settings UI)
3. Add allowed_users to agent.toml
4. starpod dev — look for Telegram connected

CLI

starpod init [--name N] [--model M] [--env K=V]   Initialize agent
starpod dev [--port P]                             Dev server (opens browser)
starpod serve                                      Production server
starpod deploy                                     Deploy to remote (coming soon)
starpod chat "message"                             One-shot message
starpod repl                                       Interactive REPL
starpod auth login|logout|status                   Platform authentication

Development

cargo test --workspace

Community

• Discord — questions, feedback, show & tell
• GitHub Issues — bug reports and feature requests
• Docs — full documentation

License

MIT