# TinyFat — full LLM-readable description

> An open-source AI assistant that lives in a real Linux box in the cloud. Reach it from any channel, retain context across sessions, switch model providers without losing memory.

## Product summary

TinyFat ("The Talking OS") is a managed agent runtime. Each user gets a persistent, sandboxed Linux container — files, browser, terminal, scheduled events — driven by an LLM brain. The container is reachable from any messaging channel via webhook (Slack/Telegram/Discord/Email) and from a web chat UI. The agent has unified awareness across all channels: a ping in one channel can steer or interrupt work in another.

The product is the compute, not the interface. Channels are interchangeable.

## Architecture

### Three open-source repos

- **troublemaker** ([github.com/tinyfatco/troublemaker](https://github.com/tinyfatco/troublemaker)): the agent runtime. System prompt, tool implementations, channel adapters. Built on top of [pi-mono](https://github.com/badlogic/pi-mono) (Mario Zechner's open-source agent loop).
- **crawdad-cf** ([github.com/tinyfatco/crawdad-cf](https://github.com/tinyfatco/crawdad-cf)): Cloudflare Worker + Containers orchestrator. Routes webhooks to per-agent Durable Objects, wakes containers on demand, manages R2 mounts and gocryptfs encryption.
- **fat-skills** ([github.com/tinyfatco/fat-skills](https://github.com/tinyfatco/fat-skills)): platform-bundled skills (browser-tools, yeet, notion, etc.).

### Runtime topology

```
User channel (Slack/Telegram/email/web/voice)
        ↓ webhook
Cloudflare Worker (crawdad-cf)
        ↓ Durable Object dispatch
Per-agent Container (Cloudflare Containers, ~1 GB RAM)
        ├── R2-backed encrypted /data (gocryptfs over s3fs over R2)
        ├── Troublemaker process (Node)
        ├── awareness/context.jsonl (single conversation log)
        └── tools: shell, browser, file edit, attach, schedules
```

Cold start: ~8s. Warm: <1s. Sleeps after 5 min idle (configurable).

### Storage model

Each agent has an R2 prefix `agents/<uuid>/`. Inside:

- `MEMORY.md` — agent's persistent self-described memory
- `awareness/context.jsonl` — single unified conversation log across all channels
- `awareness/scratch/` — agent's working directory
- `attachments/` — user-shared files
- `events/` — scheduled wake events (cron, one-shot, heartbeat)
- `skills/` — agent-created CLI tools
- `settings.json` — model + runtime preferences

The unified awareness model means there's no separate "Slack thread" vs "email thread" state — it's all one stream of consciousness. A user emailing the agent sees the same agent that just replied in Slack.

## Channels supported

| Channel | Status | Notes |
|---|---|---|
| Email | Live | Resend webhook → CF Worker → container |
| Slack | Live | Webhook adapter (events API) |
| Telegram | Live | Bot API webhook |
| Discord | Live | Slash commands + message events |
| Web chat | Live | Streaming SSE |
| Voice | Live | Twilio + ElevenLabs |
| Mattermost | Planned | |
| WhatsApp | Planned | |
| Signal | Planned | |
| iMessage | Planned | |
| SMS | Planned | |

## LLM provider support (BYOK)

The agent runtime can use any of:

- Anthropic (Claude Opus/Sonnet/Haiku) — primary
- OpenAI (GPT family + Codex)
- Fireworks (open-weight models)
- Google Gemini
- OpenRouter (provider catalog)

Users provide their own key (BYOK) for direct billing, or use the platform proxy at no markup beyond included credits.

## Data ownership

Three pillars:

1. **Code:** Troublemaker is fully open source. Self-hostable.
2. **Compute:** TinyFat hosts agents on its Cloudflare account, but customers can run the same code on their own infra (Docker/Fly/k8s).
3. **Data:** Each agent's R2 prefix is private to that user. Optional gocryptfs envelope encryption with per-agent DEKs ensures even the platform operator can't read content at rest. Users can export their agent's full state at any time.

This is the "sovereignty" angle — every corporate AI captures user skills/data and compounds value to the platform. TinyFat inverts that: the agent's labor compounds for the user.

## Pricing tiers

| Tier | $/mo |
|---|---|
| Tiny | $10 |
| Small | $29 |
| Medium | $79 |
| Fat | $149 |
| Super Fat | $299 |

Higher tiers get more agents per account, more compute, more channels, BYOK support, and faster cold starts. Detailed breakdown at [/pricing](https://tinyfat.com/pricing).

## Security

- Per-agent encryption at rest via gocryptfs (when enabled)
- Webhook signatures verified at the Worker boundary
- Per-agent `tools_token` for outbound API calls (no shared admin keys in containers)
- Scoped operator tokens for admin operations; no shared terminal/admin token in containers
- Append-only audit log for admin actions (in progress)
- Egress allowlist in development

## API

A v1 HTTP API exists for programmatic agent interaction (file operations, sending messages, listing agents). See dashboard for API key generation.

An MCP (Model Context Protocol) endpoint is exposed per agent at `crawdad.tinyfat.com/agents/<id>/mcp`. The Agency MCP at `crawdad.tinyfat.com/mcp` provides operator-scoped fleet-wide tools (read context, send message, configure).

## Project history

TinyFat started as an experimental personal AI assistant ("Zip") in 2025. The infrastructure powers a small fleet of named agents (Zip, Sega, etc.). Built and run by [Alex Garcia](https://alexgarcia.blog) as an independent project.

## Contact

- Email: alex@tinyfat.com
- GitHub: [@tinyfatco](https://github.com/tinyfatco)
- Blog: [alexgarcia.blog](https://alexgarcia.blog)