Knitly Documentation

Knitly Documentation

Self-hosted, invite-only social network for families, churches, clubs, and communities.

Overview

Knitly is a private social network designed for small, trusted circles. Each instance is a closed network for ~120 people — roughly the size of a real-world social circle.

Knitly is:

• a private timeline for friends & family
• a shared memory space
• a calm alternative to algorithmic feeds
• infrastructure for trusted communities

Knitly is not:

• a public social network
• an influencer platform
• an ad network
• a discovery feed
• a dopamine machine

Start Here

Get up and running quickly:

• Getting Started - Installation and first steps
• Configuration - Environment variables and settings
• Deployment - Production deployment guide

For Developers

Technical documentation for developers:

• Architecture - System design and tech stack
• API Reference - Complete API documentation
• Agent API - Bot accounts and programmatic access
• Custom Extensions - Add deployment-specific features
• Contributing - How to contribute code and issues

Features

Moments

• Text posts with photos (up to 6 images) or video (60s max)
• Chronological feed (no algorithm)
• Reactions (love, haha, hugs, celebrate)
• Comments on any post
• Light text formatting: bold, italic, and @mentions (not full markdown)
• Edit/delete your own content
• Image lightbox with gallery navigation

Profiles

• Bio, avatar, header/cover image
• Location and website links
• Posts and media tabs

Circles

• Create private groups within your network
• Share posts with specific circles only
• Manage circle membership

The Lobby

• Ephemeral group chat room (IRC/AOL vibes)
• Messages disappear after 24 hours
• See who’s online, join/leave announcements
• No chat history anxiety — conversations are fleeting

Polls

• Create polls on any post
• Multiple choice with customizable options

Network

• Invite-only membership
• Closed member directory
• No public access or guest viewing

Notifications

• Reactions, comments, and @mentions on your moments
• In-app only (no email spam)

Account

• Self-service password reset (forgot/reset via email)
• Email change with confirmation link
• Account deletion with a 30-day grace period (log back in to cancel)

Bot Accounts

• Admin-created accounts that authenticate with a knitly_ API key
• Blocked from form login; usable on the standard API
• See the Agent API for programmatic access

Admin

• Generate and revoke invite links
• User management (disable/enable, promote/demote, transfer ownership, remove)
• Bot accounts (create, regenerate/revoke key, delete)
• Content moderation (delete posts/comments)
• Audit log for accountability
• Session revocation and on-screen password-reset links
• Customize instance name and logo icon

Tech Stack

Layer	Tech
Backend	Bun + Hono
Database	SQLite
Frontend	Preact + TanStack Query/Router
Styling	Tailwind v4
Storage	S3-compatible (or local filesystem)
Auth	Session cookies (Argon2 hashing) + Bearer API keys for bots

Quick Start

Docker (recommended)

git clone https://github.com/knitly-app/knitly.git
cd knitly
docker compose up -d

Open http://localhost:3000 — the first user to sign up becomes admin.

Local Development

Requirements: Bun, ffmpeg (optional, for video processing)

git clone https://github.com/knitly-app/knitly.git
cd knitly
bun install
bun run dev

• Frontend: http://localhost:5173
• API: http://localhost:3000

Links

• Main README - Project overview
• Landing Page - Marketing site
• GitHub - Source code

---

Knitly is a digital living room.

A place for the people you trust. A network that belongs to you. A timeline that moves at the speed of real life.

Welcome home.