tiphys-ai 0.3.0

A local-first, extensible AI agent framework in Python

Tiphys

Your Personal AI Assistant. Python-Native. Local-First.

Tiphys is a resilient, self-hosted AI agent framework designed to run 24/7 on your own infrastructure. Built on Python's asyncio, it connects your favorite messaging platforms to powerful LLMs, giving you a personal assistant that remembers context, executes tasks, and protects your data.

Inspired by OpenClaw (formerly Moltbot), Tiphys brings the same "local-first" philosophy to the Python ecosystem, adding enterprise-grade resilience and security defaults.

Features

• State-Persistent Runtime: Powered by the Castor microkernel. Supports checkpoint/replay, allowing your agent to resume complex reasoning tasks even after a service restart or crash.
• Safety Gates (HITL): Define mandatory human approval for high-stakes tools (e.g., spending > $1.00, executing shell commands) using Castor's capability budgets. Your agent won't spend your money or delete your files without asking.
• Multi-Channel Hub: Seamlessly connect via Telegram, Discord, or the built-in WebChat while maintaining unified context. Slack & Matrix coming soon.
• Resilient Memory: Long-term vector storage (ChromaDB) ensures your agent remembers who you are and what you've discussed — weeks later.
• Task Scheduler: "Remind me every Monday at 9am to check server logs." (Cron/Interval/One-time)
• Secure Pairing: One-time code authentication (/pair 123456) protects your DM channels.
• Sandboxing: Run untrusted code or shell commands inside isolated Docker containers.
• Context Guard: Automatically manages token limits to prevent context overflow crashes.
• Auth Rotation: Rotates multiple API keys to handle rate limits and quotas gracefully.
• 24/7 Resilience: Built-in process supervision, automatic channel reconnection, and session persistence ensure your agent never sleeps.

Quick Start

Prerequisites: Have at least one LLM API key ready (e.g., OpenAI, Anthropic, or OpenRouter). Optionally, a Telegram Bot Token or Discord Bot Token if you want to connect a chat platform.

# 1. Clone & Install
git clone https://github.com/substratum-labs/tiphys.git
cd tiphys
uv sync

# 2. Configure (interactive wizard — have your API keys ready!)
uv run tiphys onboard

# 3. Launch
uv run tiphys gateway

Your agent is now live! Open http://localhost:8000 to chat via WebChat, or message your configured Telegram/Discord bot.

Deployment (Production)

For 24/7 availability, deploy Tiphys to a VPS (DigitalOcean, Hetzner, AWS) using Docker.

# 1. Clone & Configure
git clone https://github.com/substratum-labs/tiphys.git
cp .env.example .env   # edit with your API keys

# 2. Start with Docker Compose
docker compose up -d

Key environment variables:

Variable	Description
TIPHYS_LLM__API_KEY	Your LLM provider API key
TIPHYS_LLM__PROVIDER	Provider name (openai, anthropic, openrouter, ...)
TIPHYS_SECRET_KEY	Secret key for session encryption

Architecture

Tiphys uses an async, modular "Hub & Spoke" architecture:

graph TD
    User((User)) <-->|Telegram/Discord| Channel[Channel Adapters]
    Channel <--> Gateway[Tiphys Gateway]

    subgraph "Tiphys Core"
        Gateway <--> Agent[Agent Runtime]
        Agent <--> Kernel[Castor Kernel]
        Agent <--> Memory[(ChromaDB Memory)]
        Agent <--> Scheduler[Task Scheduler]
        Agent <--> Tools[Tool Registry]
    end

    Kernel -.->|Checkpoint/Replay| Store[(Checkpoint Store)]
    Kernel -.->|Budget & HITL| Tools
    Tools -.->|Policy Check| Policy[Security Policy]
    Tools --> Sandbox[Docker Sandbox]

Documentation

Section	Description
API Reference	Auto-generated API documentation
Security	Security policy and architecture
Contributing	Development setup and PR workflow
Changelog	Release notes

License

Apache 2.0 © Tiphys Contributors