Tycho

Latest Release: v0.9.10 (June 13, 2026)

Tycho is an autonomous server management CLI designed to deploy and manage a complete, self-hosted infrastructure using Podman. It supports two primary deployment patterns.

Before diving in, check out the Tycho Philosophy to understand the project’s core principles. For comprehensive setup guides and architectural instructions, see the Tycho HOWTO.

Key Features

• Standalone CLI: One tool to rule them all.
• Dynamic Recipes: Fetches the latest configurations directly from GitHub.
• Rootless First: Optimized for rootless Podman environments with strict user isolation.
• Third-Party Repositories: Helm-like custom recipe repositories allowing you to add, list, and deploy recipes from your own GitHub repositories, complete with automatic semantic tag resolution. (See Repository User Guide and Recipe Provider Guide).
• Automated Storage: Each user gets their own isolated storage space (e.g., /data/users/username/app).
• Smart Routing: Automatic Traefik detection and subdomain conflict checks.

Quick Install

Deploy the latest stable release:

curl -fsSL https://tycho.cc/install.sh | bash

[!TIP] Developer Options: You can specify custom branches or tag versions during installation using the TYCHO_VERSION environment variable (e.g., run export TYCHO_VERSION=main to install the latest development state, or export TYCHO_VERSION=v0.9.0 to target a specific release before running the installer).

---

🏗 Choose your Architecture

1. Personal Server (Full User Mode)

The easiest way for a single user. Everything (including Traefik) runs in your user space.

• Prerequisite: Allow binding to ports 80/443 (configured automatically by the interactive installer, or manually via): echo "net.ipv4.ip_unprivileged_port_start=0" | sudo tee /etc/sysctl.d/99-rootless.conf && sudo sysctl --system
• Workflow:

  tycho setup
  tycho install traefik    # Installs core/traefik in your home
  tycho install core/smtp
  tycho install immich     # Or any other recipe
  

2. Infrastructure Server (Shared/System Mode)

More robust. Traefik is a system-level gateway, and users install their apps separately.

• Step A (Admin): Install the system gateway:

  sudo tycho setup
  sudo tycho install traefik  # Creates a systemd service
  

• Step B (Users): Install personal apps:

  tycho setup
  tycho install immich
  

---

Commands

• tycho setup: Interactive assistant to configure your domain and email.
• tycho list: Explore available recipes across all configured repositories.
• tycho install [repo/]<pkg>: Deploy a new service (interactive).
• tycho uninstall <pkg>: Cleanly remove a service and its data.
• tycho repo <cmd>: Manage third-party recipe repositories (add, list, remove, update, boilerplate). See the Repository User Guide for usage.
• tycho backup [file] [opts]: Backup configurations (metadata) and persistent databases. Supports CRON, service scoping, remote SSH scp/rsync transport, and incremental syncing. See the Backup Guide.
• tycho restore <file>: Overwrite configurations and databases from a backup archive or folder. Scoped boundaries prevent accidental data loss. See the Restore Guide.
• tycho stats: Monitor your server’s health.
• tycho ps: List active containers managed by Tycho for the current user.
• tycho alias <cmd>: Register or update dynamic wildcard subdomains (e.g. *.subdomain.tycho.cc) pointing to your server’s public IP. See Domain Alias Management.
• tycho upgrade: Self-update the CLI to the latest version.

📦 Included Recipes

Tycho comes with several pre-configured, production-ready application recipes:

• backup-receiver (License: AGPL-3.0): A dedicated system to securely receive and verify remote server backups.
• dashboard (License: AGPL-3.0): A central landing page with automated service discovery, cryptographic lock, and system resource indicators.
• devsecops-lab (License: AGPL-3.0): Cybersecurity pentest lab featuring OWASP Juice Shop and automated Trivy vulnerability scanning. (See Cybersecurity Lab Guide).
• gitea (License: MIT): Painless self-hosted Git service with a lightweight SQLite database backend.
• immich (License: AGPL-3.0): High-performance self-hosted photo and video management backup solution.
• jellyfin (License: GPL-2.0): Media server for streaming movies, shows, and music.
• mattermost (License: MIT): Open-source, self-hosted developer collaboration platform (Slack alternative) backed by PostgreSQL.
• n8n (License: FairCode): Workflow automation tool to integrate systems and build automations.
• nextcloud (License: AGPL-3.0): Enterprise-grade private cloud platform for file sharing, calendar, and collaboration.
• ollama (License: MIT): Local large language model (LLM) server with automatic GPU acceleration support.
• open-notebook (License: Apache-2.0): Self-hosted AI-powered knowledge management tool (NotebookLM alternative) backed by SurrealDB.

License

GNU AGPL-v3. See LICENSE for details.