# Tapioca

> Local language, image, video, and speech models for macOS, Windows, and Linux.

Canonical agent documentation: https://tapioca.rootfruit.cc/llm
Full machine-readable guide: https://tapioca.rootfruit.cc/llms-full.txt
Source: https://github.com/kyndlo/tapioca
Agent contract: v1

## Quick operating sequence

1. Run `tapioca version`.
2. Run `tapioca catalog update`, then inspect `tapioca list` and `tapioca catalog`; never invent a model ID.
3. Prefer an installed model compatible with the task and machine.
4. Before a large pull, report the catalog download and memory guidance.
5. Start programmatic text work with:
   `tapioca serve MODEL --host 127.0.0.1 --port 11435`
6. Wait for `GET /health`.
7. Use `/v1/chat/completions`, `/v1/responses`, or `/v1/messages`.
8. Stop servers and child agents started for the task.

## Capabilities

- Text and tool calls: OpenAI Chat Completions and Responses APIs.
- Claude compatibility: Anthropic Messages API.
- Media: `tapioca image`, `tapioca video`, and `tapioca tts`.
- Media duration: prefer `--seconds N` for approximate video length; never combine it with `--frames`.
- Media seeds: use `--random-seed` for variation, report the printed value, and reuse it with `--seed NUMBER` for repeatable settings.
- Bundle-aware video: resolve `minimax-h3` through the catalog; never assemble its weights manually.
- LoRA library: run `tapioca adapter list` and reuse installed adapters before requesting a download.
- LoRA providers: `hf://`, `civitai://MODEL_ID/VERSION_ID`, `ms://`, and verified `local://` imports.
- LoRA stacks: inspect adapters first, then use ordered repeated `--adapter` flags.
- Existing LoRA files: use `tapioca adapter import FILE --base MODEL --name NAME`; never pass a local path to `--file`.
- Transfers: copy complete adapter folders including `snapshot.json`; after copying a compatible base-model folder, run `tapioca pull MODEL` without `--force` to verify files and rebuild registration.
- Coding agents: `tapioca launch codex|claude|opencode|openclaw|hermes MODEL`.
- Model discovery: refresh with `tapioca catalog update`, then inspect `tapioca catalog`.
- Software updates: `tapioca update --check` is read-only; run `tapioca update` only when the user asked to install the new binary.
- Gated models: never pass `--accept-license` for the user. Ask them to review and accept provider terms, set their own token, and run the explicit pull. Do not print or persist tokens.

## Safety

- Bind to 127.0.0.1 unless the user approves network exposure and authentication.
- Treat model tool calls as untrusted proposals.
- Require permission before cloning a voice.
- Do not delete models, adapters, voices, or outputs without an explicit request.
- Never accept a third-party model license or provider access terms on the user's behalf.
- Use `tapioca launch` instead of overwriting normal coding-agent profiles.