Documentation

Installation

Tuis is distributed as a Docker image. The recommended way to run it is with Docker Compose.

Docker Compose

Create a docker-compose.yml file:

services:
  tuis:
    image: ghcr.io/3stacks/tuis:latest
    container_name: tuis
    restart: unless-stopped
    ports:
      - "6969:3000"
    volumes:
      - tuis-data:/app/data
    environment:
      - NODE_ENV=production

volumes:
  tuis-data:

Then start it:

docker compose up -d

Tuis will be available at http://your-server:6969. All data is stored in a SQLite database inside the tuis-data volume.

Demo data

If you want to explore Tuis before entering your own data, you can seed it with demo data:

docker exec tuis npm run seed:demo

Updating

# Pull the latest image
docker compose pull

# Restart with the new version
docker compose up -d

Your data is stored in a Docker volume and will persist across updates.

Self-hosting

Network access

Tuis is designed to be accessed via a WireGuard VPN. We use Tailscale, which takes about five minutes to set up and gives every device on your tailnet a stable IP. This means your data never leaves your network — no cloud accounts, no subscriptions, no data harvesting.

With Tailscale, you can access Tuis from your phone at the shops, from work, or from anywhere — without exposing any ports to the public internet.

Reverse proxy (HTTPS)

If you want HTTPS within your network (recommended), put Tuis behind a reverse proxy. Caddy handles automatic TLS with minimal configuration:

chores.home.yourdomain.com {
    reverse_proxy tuis:3000
}

Caddy will automatically provision and renew certificates. Pair this with a local DNS entry (e.g. via Pi-hole or your router) pointing chores.home.yourdomain.com to your server's IP.

Backups

Tuis stores everything in a single SQLite database inside the Docker volume. To back it up:

# Copy the database out of the volume
docker cp tuis:/app/data/chore-calendar.db ./backup-$(date +%Y%m%d).db

Or mount the volume to a host path and include it in your regular backup routine (rsync, borg, restic, etc.).

iOS companion app

Tuis has a native iOS companion app for quick access to shopping lists and meal planning on the go. It connects directly to your Tuis server over your local network or VPN.

Current features:

• Shopping lists with add, check-off, and swipe-to-delete
• Weekly meal planner with recipe picker and servings scaling
• Aggregated weekly ingredients with "add missing to shopping list"
• Ingredient scaling with smart formatting

Planned features include location-aware shopping notifications, Apple Watch companion, Siri Shortcuts, and home screen widgets.

Source code: github.com/3stacks/tuis-ios

Configuration

Environment variables

Google Calendar sync

The Google credentials are only needed if you want to sync chore due dates with Google Calendar. Without them, Tuis works fully standalone — you just won't get calendar integration.

To enable it, create a Google OAuth 2.0 client in the Google Cloud Console and set the GOOGLE_CLIENT_ID and GOOGLE_CLIENT_SECRET environment variables.

Actual Budget integration

Tuis integrates with Actual Budget to display your home maintenance budget alongside vendor quotes. This helps you make informed decisions about home repairs and improvements.

Actual Budget doesn't expose its data externally by default. To bridge this gap, you'll need a lightweight API harness like actual-widget-api which makes your Actual data available over HTTP for Tuis to consume.

To enable it, set ACTUAL_API_URL to the URL of your API harness. If you run both on the same Docker network, you can use the container name:

environment:
  - ACTUAL_API_URL=http://actual-widget-api:3100

Full Docker Compose example

Here's a complete example with all optional environment variables:

services:
  tuis:
    image: ghcr.io/3stacks/tuis:${TUIS_VERSION:-latest}
    container_name: tuis
    restart: unless-stopped
    ports:
      - "${WEB_PORT:-6969}:3000"
    volumes:
      - tuis-data:/app/data
    environment:
      - NODE_ENV=production
      - NEXTAUTH_URL=${NEXTAUTH_URL:-http://localhost:3000}
      - NEXTAUTH_SECRET=${NEXTAUTH_SECRET}
      - ACTUAL_API_URL=${ACTUAL_API_URL:-http://localhost:3100}
      - GOOGLE_CLIENT_ID=${GOOGLE_CLIENT_ID}
      - GOOGLE_CLIENT_SECRET=${GOOGLE_CLIENT_SECRET}

volumes:
  tuis-data:

Roadmap

Planned features and integrations:

• Vehicle management — track cars, service history, fuel logs, registration, and insurance renewals
• MCP server — expose Tuis data via the Model Context Protocol so AI assistants and LLMs can read and manage your household
• CLI — command-line interface for scripting and LLM tool-use integration
• Calendar sync — CalDAV and Outlook support (currently Google Calendar only)
• Budget integrations — PocketSmith, YNAB, and other budgeting tools alongside Actual Budget

Tech stack

• Framework: Next.js 16 with React 19
• Database: SQLite with Drizzle ORM
• UI: Tailwind CSS + Radix UI (shadcn/ui)
• Testing: Vitest (unit) + Playwright (e2e)
• Container: Docker (single image, single volume)
• iOS: Native SwiftUI app (tuis-ios)