Tiri Agent

Tiri is a local-first agent product shell built on the standalone agent-runtime core. It packages the runtime into a practical personal-agent experience: CLI chat, FastAPI APIs, a Next.js web shell, sandbox tools, channel integrations, local skills, and SQLite persistence.

Highlights

• Local-first backend with durable SQLite sessions, settings, channel state, event streams, and outbox records.
• Runtime composition around agent-runtime, keeping product policy here and neutral agent mechanics in the sibling core package.
• CLI and web entry points through the same TiriBackend configuration path.
• Local and Docker-backed sandbox tools for file access and shell execution.
• Prompt assembly from base identity, runtime environment, optional profile context, and local skill registry.
• Channel adapters for Telegram, Weixin/WeChat, and Feishu/Lark, including inbound listeners and proactive outbound messaging.

Repository Map

Path	Purpose
agent/	TiriBackend, backend config, logging hooks, and collaboration modes.
prompts/	Base prompt, profile prompt, environment prompt, and skill index assembly.
tools/	Tool registry composition and concrete Tiri tool sets.
sandbox/	Local and Docker sandbox implementations exposed as runtime tools.
channels/	Provider adapters, listeners, gateway, targets, settings, and outbox worker.
server/	FastAPI app, SQLite storage, event queues, and local server runner.
cli/	Thin tiri command entrypoint.
web/	Next.js web shell for Tiri-specific backend integration.

Top-level backend.py, config.py, and collaboration.py are compatibility re-export modules. New implementation should live under the structured packages above.

Quick Start

Install the sibling runtime and this product repo into a local virtual environment:

uv venv --python 3.11 .venv
uv pip install -e ../agent-runtime -e ".[server]" --python .venv/bin/python
uv pip install pytest --python .venv/bin/python

Configure a model:

export TIRI_LLM_API=openai-chat-completions
export TIRI_MODEL=your-model-name
export TIRI_LLM_API_KEY=your-api-key
export TIRI_LLM_BASE_URL=https://api.openai.com/v1

Run CLI chat:

.venv/bin/tiri

Start the local API and web shell:

.venv/bin/tiri server start

The server command starts:

• FastAPI at http://127.0.0.1:8000
• Next.js at http://127.0.0.1:3000

To run only the FastAPI backend:

.venv/bin/tiri server start --no-web

Configuration

Variable	Purpose
TIRI_LLM_API	Provider API shape, such as openai-chat-completions.
TIRI_MODEL	Model name. Required unless passed with --model.
TIRI_LLM_API_KEY	Provider API key.
TIRI_LLM_BASE_URL	Optional provider base URL.
TIRI_PROMPT_PATH	Optional file overriding the base system prompt.
TIRI_PROFILE_PATH	Optional local user/profile prompt file.
TIRI_SKILLS_PATH	Optional local skills directory.
TIRI_DATA_DIR	Local data directory, defaulting to ~/.tiri when configured.
TIRI_DB_PATH	Explicit SQLite database path.
TIRI_COLLABORATION_MODE	Collaboration mode, currently default or plan.

CLI flags mirror the most common settings:

.venv/bin/tiri --model your-model --data-dir /path/to/tiri-data
.venv/bin/tiri server start --db-path /path/to/tiri.sqlite

Prompts And Skills

Tiri builds the system prompt from:

• prompts/base.py for the base identity, operating loop, tool rules, workspace rules, safety guidance, and voice.
• The runtime environment, such as cli, web, or channel:<provider>.
• Optional profile context from TIRI_PROFILE_PATH.
• Optional skill registry context from TIRI_SKILLS_PATH.

If TIRI_SKILLS_PATH is unset, it defaults to ~/.tiri/skills when TIRI_DATA_DIR is configured, otherwise ./skills.

Sandbox Tools

Enable local workspace tools:

export TIRI_SANDBOX_ROOT=/path/to/workspace
export TIRI_SANDBOX_BACKEND=local

Use Docker-backed shell execution while keeping the same mounted workspace:

export TIRI_SANDBOX_BACKEND=local-docker
export TIRI_SANDBOX_DOCKER_IMAGE=python:3.12-slim

The Docker backend keeps one container per Tiri session. The container name is derived from the session id, mounted workspace, and image, so resumed sessions reuse their sandbox container and later run_shell calls execute through docker exec.

Sandbox tools currently include read_file, write_file, list_files, and run_shell.

Local Data And Channels

Tiri stores local backend data in SQLite. By default, the durable database is:

~/.tiri/tiri.db

The database stores chat sessions, message history, event-stream records, local settings, channel settings, proactive targets, and channel outbox entries.

Supported local channel providers:

• Telegram long polling via the Bot API.
• Weixin polling via the ilink bot API.
• Feishu/Lark websocket via lark-oapi.

Inbound channel events are routed through:

POST /api/channels/inbound

When exposed beyond localhost, set an inbound token and send it as Authorization: Bearer ... or X-Tiri-Channel-Token:

export TIRI_CHANNEL_INBOUND_TOKEN=local-secret

Background channel services are enabled by default and can be disabled with:

export TIRI_CHANNEL_GATEWAY_ENABLED=false
export TIRI_CHANNEL_OUTBOX_ENABLED=false

Development

Run Python tests:

.venv/bin/python -m pytest tests -q

Run frontend checks:

cd web
npm run lint
npm run build

License

Tiri Agent is licensed under the GNU Affero General Public License, version 3 only. See LICENSE for details.