Twtxt & Yarns Protocol
Indie in a Box treats Twtxt and Yarns as first-class citizens alongside IndieWeb and ActivityPub. Publish, consume, mention, thread, and embed rich media using simple, human-readable flat text feeds.
01 // What is Twtxt?
Twtxt is a minimalist, decentralized microblogging format that operates entirely through static plain-text files served over standard HTTP/HTTPS GET requests. There are no databases to query, no central hubs, and no proprietary APIs.
Zero-Overhead Plain Text
Each entry is a single line consisting of an ISO 8601 UTC timestamp, a TAB character separator, and the message content.
Static & Edge Cacheable
Because twtxt.txt is a static text file, it can be cached indefinitely on Cloudflare edge nodes or served from minimal low-power servers.
Modern Yarns Extensions
Supports the Yarns metadata specification, including threaded conversation tags, avatars, nicknames, markdown formatting, and media extraction.
02 // Automated Feed Generation (/twtxt.txt)
Whenever a post or short note is published, Indie in a Box compiles your public feed directly to public_html/twtxt.txt. Multi-line markdown notes are automatically collapsed into single-line entries with links and wikilinks cleanly formatted.
# nick = lumen
# link = https://indieinabox.2lp.in/twtxt.txt
# author = Lumen Pink
# description = Indie in a Box official updates and cyberpunk devlog
# avatar = https://indieinabox.2lp.in/assets/avatar.png
2026-09-22T06:59:00Z Indie in a Box v1.0.0 is officially released! https://codeberg.org/indieinabox/indieinabox (#release)
2026-09-22T07:45:00Z Documentation live at https://indieinabox.2lp.in with Triple Protocol mastery!
2026-09-22T08:15:00Z @<alice https://alice.example.com/twtxt.txt> Welcome to the decentralized web! (#greetings)| Header Attribute | Specification | Purpose |
|---|---|---|
| # nick = <str> | Twtxt Metadata Spec | Short identifier/handle for mentions (e.g. lumen). |
| # link = <url> | Twtxt Metadata Spec | Canonical URL pointing back to the feed itself. |
| # author = <str> | Yarns Extension | Full human display name of the feed owner. |
| # description = <str> | Yarns Extension | Short profile bio or feed description. |
| # avatar = <url> | Yarns Extension | Direct URL to the author's profile portrait image. |
03 // Yarns Protocol Extensions
Indie in a Box implements the complete Yarns specification for extended rich interaction over plain text:
| Feature | Syntax | Rendered HTML Output & Behavior |
|---|---|---|
| Mentions | @<nick https://url/twtxt.txt> |
Autolinked anchor tag: <a href="url" class="mention">@nick</a>. |
| Subject / Thread Tags | (#subject_name) |
Categorizes or threads the twt: <span class="twtxt-subject">(#subject)</span>. |
| Inline Formatting | **bold**, *italic*, ~~strike~~, `code` |
Standard semantic HTML: <strong>, <em>, <del>, <code>. |
| Blockquotes | > quoted text |
Rendered as stylized blockquote container: <blockquote class="twtxt-quote">. |
| Media Embeds |  |
Automatic visual media card: <figure class="twtxt-media"><img ...></figure>. |
| Audio & Video Detection | Bare audio (.mp3, .ogg) or video (.mp4, .webm) URLs |
Automatically converted into interactive native HTML5 <audio controls> or <video controls> players! |
| Hashtags | #hashtag |
Autolinked to global Twtxt search hubs: <a href="...search?tag=hashtag">#hashtag</a>. |
04 // Ingestion & Microsub Reader Integration
You don't need a separate app to read Twtxt feeds. Indie in a Box unifies Twtxt directly into its Microsub Reader:
Subscribing to a Twtxt Feed
1. Open Admin → Timeline.
2. Select or create a channel (e.g. #twtxt or #inbox).
3. Click + Subscribe and paste the remote twtxt.txt URL.
4. The engine resolves author metadata, avatars, and begins tracking updates.
CLI Feed Polling
Run the feed crawler manually or in your cron tasks:
# Fetch all RSS, Atom, and Twtxt subscriptions
php indieinabox.php fetch
# Alias command:
php indieinabox.php microsub:fetch05 // Spam Filters & Moderation
Twtxt feeds ingested by Indie in a Box pass through the unified MicrosubFilterService:
- Mute Nicknames: Silences entries from toxic nicknames across all subscribed feeds.
- Mute Feed URLs: Drops malicious or abusive twtxt endpoints permanently.
- Keyword Blacklist: Automatically discards spam messages matching configured regex patterns or blocked keyword lists.
06 // Client Ecosystem & Interoperability
Because Indie in a Box outputs standard twtxt.txt and parses Yarns specifications cleanly, you can interact with your feed using any client across the Twtxt ecosystem:
twtxt (CLI)
The original Python CLI client. Follow feeds, read timelines, and post tweets from your terminal.
Yarn (Golang)
Full-featured Twtxt/Yarns server and client supporting rich threads, avatars, and media.
Jenny & Goryon
Modern mobile and desktop graphical readers for reading flat feeds on Android, iOS, and Linux.