# TinyTank — Full Documentation (Markdown)

> Single-file documentation for LLMs and agents. Human version: https://tinytank.app/#/docs
> Agent setup: https://tinytank.app/install.md

## Overview

TinyTank turns a plain-language description into a running full-stack app — pages,
API, database and sign-in — then keeps it running with a resident agent that
monitors, fixes and ships the changes the owner asks for.

Lifecycle: Describe (one sentence) → Preview (pages, data, auth) → Live (domain +
SSL) → Resident agent loop (watch → fix → report; request → approve → ship; every
change has one-tap undo).

Plans: Hobby $0 (1 project) · Builder $5/mo (unlimited projects, resident agent,
custom domains) · Pro $19/mo (adds dfctl CLI, REST API, OpenAPI, 3 environments) ·
Team $79/mo (3 seats included, +$20/seat, roles & permissions, 24/7 support).
Paid plans start with a 14-day free trial. Apps scale to zero when idle; usage is
metered by the second.

## Quickstart

1. Sign in at https://tinytank.app/#/login — GitHub, Google, or email code.
   First sign-in creates the account.
2. In the dashboard, describe the app in 1–2 concrete sentences (who uses it, what
   they do, what data is tracked). Example: "A booking site for my pottery studio.
   Customers pick a class from a weekly calendar, pay a deposit, and get a
   confirmation email. I manage classes in a private admin page."
3. Review the working preview; refine with short plain-language asks.
4. Press Deploy. The app is live on a platform subdomain (e.g.
   https://pottery.tinytank.app) with SSL, served from the global edge; data
   lives in the chosen residency region with automatic backups in a second region.

After launch, changes go through the resident agent (Builder+): type a request,
review the proposed plan and preview diff, approve with one tap; every shipped
change keeps a permanent one-tap rollback.

## Connect your AI agent

Coding agents learn TinyTank by reading one URL. The user pastes:

    Read https://tinytank.app/install.md and set up TinyTank for this project.

The agent then: (1) installs a TinyTank skill — `.claude/skills/tinytank/SKILL.md`
for Claude Code, or an AGENTS.md section for other tools; (2) verifies
connectivity via GET /api/health; (3) reports region and version to the user.

Machine-readable endpoints:
- /llms.txt — llms.txt-standard index
- /llms-full.txt — this file
- /install.md — agent setup instructions
- /api/health — GET, no auth: liveness, region, version

Security rule: never paste TinyTank tokens into a chat. Authenticated access goes
through `dfctl login` in the user's own terminal.

## Prompt-driven deploys

Good prompts name the user and the core action; describe data, not technology;
state who needs sign-in; give actionable style words. Infrastructure (frameworks,
hosting, SSL) never needs to be mentioned, but explicit constraints ("use
Postgres", "keep data in the EU") are honored.

Iterate in small rounds: ship the core flow first, then refine with short asks
("Calendar starts Monday", "Deposits are 20%"), then let the resident agent's
usage reports drive further improvements.

## Your resident agent

Included on Builder and above. Capabilities:

| Capability | Trigger | Approval |
|---|---|---|
| Watch — logs, metrics, uptime probes | continuous 24/7 | none (read-only) |
| Fix — restore last known-good state, restart, roll back bad deploy | detected failure | none; recovery only, reported after |
| Change — features, copy, design, data model | owner's request | always required |
| Upkeep — cert renewals, DB upgrades, backups | scheduled | announced in advance |

Auto-fix is deliberately narrow: the agent may restore a known-good state on its
own but may never ship new behavior without approval. Each project has a monthly
agent budget; anything exceeding it is quoted first. Notifications via email
digest, mobile push, or webhook.

## Custom domains

Builder+. Project → Settings → Domains → Add. Create the DNS records shown:
CNAME `www` → `edge.tinytank.app`, plus a TXT `_stratum-verify` record. Apex
domains via ALIAS/ANAME or TinyTank-hosted DNS. Certificates issue and renew
automatically.

## CLI — dfctl (Pro, beta)

Install: `curl -fsSL https://get.tinytank.app/install.sh | sh` ·
`brew install tinytank-cloud/tap/dfctl` · `winget install TinyTank.dfctl`

| Command | Purpose |
|---|---|
| dfctl login | browser auth; token stored in OS keychain |
| dfctl init | create tinytank.json (name, data region, services) |
| dfctl deploy | build & ship current dir; --data-region, --env staging |
| dfctl status | health, version, traffic per service |
| dfctl logs <svc> | tail logs; --follow, --since 1h, --grep |
| dfctl scale <svc> <n> | instance count, or --auto with scale-to-zero |
| dfctl env | list/set/unset env vars & secrets per environment |
| dfctl domains | attach & verify custom domains |
| dfctl db | console, branches, backups of built-in database |
| dfctl export | eject project to plain Git repo with Dockerfiles |
| dfctl token create | mint scoped API token for CI / agents |
| dfctl open | open project dashboard |

dfctl projects and described apps coexist in one workspace; any project can be
exported.

## REST API (Pro, beta)

Base URL: https://tinytank.app/api
Auth: `Authorization: Bearer st_live_…` (tokens via `dfctl token create`, scoped
per project and permission: read / deploy / admin).

Live today, no auth: `GET /api/health` →
`{ "ok": true, "service": "tinytank", "region": "<edge code>", "version": "<id>", "deployed_at": "<iso>" }`

Endpoints (beta): GET/POST /api/projects · GET /api/projects/:id ·
GET/POST /api/projects/:id/deploys · POST /api/projects/:id/rollback ·
GET /api/projects/:id/logs (?since, ?grep, ?follow=1 SSE) · GET /api/usage ·
POST /api/webhooks. OpenAPI 3.1 at /openapi for Pro workspaces.

Errors: JSON `{ "error": "snake_case_code", "trace_id": "…" }` — match the code,
not HTTP text; quote trace_id (also in the x-trace-id header) when reporting issues.
invalid_request 400 · unauthorized 401 · forbidden 403 · route_not_found 404 ·
too_many_requests 429 (back off per Retry-After) · provider_not_configured 501 ·
internal_error 500.

## Regions & limits

| Residency region | Slug | Location | Backup |
|---|---|---|---|
| Singapore | sin | Singapore | Tokyo |
| Japan | hnd | Tokyo | Seoul |
| Korea | icn | Seoul | Tokyo |
| EU | fra | Frankfurt | Amsterdam |
| US | iad | Ashburn, Virginia | Dallas |

Compute has no region — apps and static assets serve from the global edge.
Data lives in the chosen residency region + its backup region; EU data stays
in the EU.

| | Hobby | Builder | Pro | Team |
|---|---|---|---|---|
| Projects | 1 | unlimited | unlimited | unlimited |
| Storage | 100 MB | 5 GB | 50 GB | 200 GB |
| Log retention | 48 h | 7 d | 30 d | 90 d |
| Environments | 1 | 1 | 3 | 3 |
| Custom domains | — | 3/project | 20/project | 20/project |
| Resident agent | — | ✓ | ✓ | ✓ |
| dfctl + API | — | — | ✓ | ✓ |
| API rate limit | — | — | 600 req/min | 1,200 req/min |
| Seats | 1 | 1 | 1 | 3 incl., +$20/seat |
| Support | community | community | priority | 24/7 |

## FAQ

- Ownership: code, data and domain belong to the user; `dfctl export` produces a
  plain Git repo with Dockerfiles — no proprietary runtime.
- Wrong agent change: new behavior requires approval; permanent one-tap rollback;
  autonomous actions limited to restoring known-good states, always reported.
- Cold starts: warm pool per region; typical wake under a second; edge serves
  static assets while the backend wakes.
- Stacks: described apps use boring, exportable stacks (typed web framework,
  Postgres-compatible DB, standard Docker images).
- Billing: flat plan fee + by-the-second usage; hard budget caps per project.
- Trials: Builder and Pro include 14 days free; Hobby is free forever.