Tycho

Autonomous Server Management CLI backed by Podman & Git — v0.9.10 (2026-06-13)

Download as .zip Download as .tar.gz View on GitHub

Tycho HOWTO

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

This guide provides detailed instructions on how to customize and extend your Tycho infrastructure depending on your needs.

1. Choice of Deployment Mode

Tycho allows you to choose between two architectural patterns.

Personal Mode (Single User)

Everything (including Traefik) runs in your user space using Podman Rootless.

Infrastructure Mode (Shared Server)

Traefik runs at the system level (Rootful), while applications run in individual user spaces (Rootless).

2. Configuration (.env)

The .env file is located at ~/.tycho/.env (User) or /etc/tycho/.env (System).

3. Managing Repositories (User Guide)

Tycho supports third-party recipe repositories similar to Helm. This allows you to add repositories hosted by the community or within your organization.

Managing Repositories

Listing & Installing Third-Party Recipes

4. Being a Recipe Provider (Provider Guide)

If you are a developer or team lead, you can easily host your own Tycho recipe repository on GitHub to share custom services with your users.

Repository Structure

Any GitHub repository can act as a Tycho recipe repository as long as it contains the designated .tycho root directory:

<your-repository-root>/
└── .tycho/
    ├── core/
    │   └── podman/                 # Core services (e.g., custom gateways)
    └── recipes/
        └── podman/                 # Platform recipes (e.g. podman, k8s coming soon)
            └── quatrain-studio/    # The recipe directory
                ├── compose.yaml    # Docker/Podman compose template
                ├── package.json    # Recipe metadata
                └── README.md       # Individual deployment instructions

Recipe Components

Each recipe directory must include:

  1. compose.yaml (or compose.yml): The Podman compose template. Route public HTTP services by declaring standard Traefik routing labels: ```yaml labels:
    • traefik.enable=true
    • traefik.http.routers..rule=Host(`${_SUBDOMAIN:-}.${DOMAIN_NAME}`)
    • traefik.http.routers..tls=true
    • traefik.http.routers..entrypoints=websecure
    • traefik.http.routers..tls.certresolver=${TRAEFIK_RESOLVER:-myresolver}
    • traefik.http.services..loadbalancer.server.port= ```
  2. package.json: Metadata defining user query questions: 
    {
  "name": "quatrain-studio",
  "description": "Visual data modeling and developer dashboard",
  "requiredEnv": [
    "STUDIO_SUBDOMAIN",
    "STUDIO_DATA_LOCATION"
  ]
}
  3. README.md: Descriptive setup, customization options, and volume mount documentation for users.

Recipe Hooks (pre-install & post-install)

To enable advanced configuration, environment checks, or post-deployment seeding, Tycho supports dynamic execution of shell hooks inside your recipe directory.

If these optional scripts are provided, the Tycho CLI will run them automatically during deployment:

1. Pre-installation Hook (pre-install.sh)

This script runs before standard volumes are initialized and podman compose is triggered.

2. Post-installation Hook (post-install.sh)

This script runs after the Tycho CLI has fully successfully deployed and started the container services via podman compose up -d.

[!NOTE] Interactivity Safeguard: Since the hooks run in the active terminal environment, you can use interactive prompts using standard shell input (like read or using custom safe_read scripts to ensure compatibility with redirected streams).

Publishing & Sharing Your Custom Recipes

To publish and share your custom recipes:

  1. Bootstrap the repository structure: Run tycho repo boilerplate <folder> to initialize the required directory structure and repository.json metadata file in your local directory.
  2. Add your recipes: Place your recipe directories under .tycho/recipes/podman/<recipe_name>/ including the compose.yaml, package.json, and README.md files.
  3. Commit and push: Initialize git in the folder, commit all your files, and push them to a public GitHub repository (e.g. https://github.com/username/my-tycho-recipes).
  4. Publish releases: Tag your repository commits with semantic versions (e.g., v1.0.0, v1.1.0).
  5. Share with users: Users can then register your repository using: 
    tycho repo add <alias_name> <username>/<my-tycho-recipes>[@version_tag]

    And deploy your custom recipe via:

    tycho install <alias_name>/<recipe_name>

Best Practices for Recipe Providers

5. Domain Alias Management (Dynamic DNS)

Tycho comes with support for wildcard dynamic subdomains via a free alias service integrated at api.tycho.cc. This is particularly useful for exposing containers via Traefik without setting up or purchasing your own custom domain.

Registering and Updating Aliases

6. Monitoring & Maintenance

Backup & Restore

Tycho features built-in server backup and restoration capabilities. These commands ensure that all your configurations, added third-party repositories, local recipe definitions, and persistent databases/application storage are backed up and restored safely.

Backups are self-aware: every backup contains a shell-sourceable .tycho-backup-meta manifest declaring its type (full vs. service-specific), date, and storage scope. The restore command reads this manifest first to automatically isolate target boundaries and verify safety.

1. Scope and Separation (Metadata vs. Data)

2. Non-Interactive Operations (CRON Automation)

For automated backups (e.g., via CRON), append the --non-interactive or -y flag to bypass all interactive prompts:

tycho backup --non-interactive

[!IMPORTANT] Downtime Prevention: By default, Tycho does not stop active container services in non-interactive mode. To explicitly stop active containers temporarily to guarantee complete transaction/database consistency, you must pass the --stop-services flag:

tycho backup --non-interactive --stop-services

3. Remote Transport & Incremental Syncing

4. Retention Policy Pruning (--keep <N>)

Specify a maximum number of historical backups to retain. Tycho will automatically sort matching archives chronologically and prune the oldest:

# Keep only the 5 newest nextcloud backups locally
tycho backup --service nextcloud --keep 5

# Works over remote standard connections as well
tycho backup --remote user@host:/backups --keep 7

5. Restore from Backup

The restore command safely stops active containers (either globally or for the specific service) before overwriting, and will offer to restart services sequentially (core Traefik gateway first, then application recipes) once restored.

tycho restore <backup_file.tar.gz_or_dir>

To run non-interactively without overwrite confirmations:

tycho restore <backup_file.tar.gz> --non-interactive

[!CAUTION] Destructive Operation: Restoring from a backup will overwrite current configurations and persistent data directories under $WORK_DIR and $BASE_STORAGE_PATH within the backup’s scoped boundaries (e.g., overwriting ONLY the target service files if it was a service-level backup).

7. Core CLI Development & Releases (Developer Guide)

If you are contributing to the core Tycho project, this guide explains how the installation, versioning, and release pipeline are structured.

Installation Versioning Options

The quick installer supports the TYCHO_VERSION environment variable. This allows developers and administrators to deploy and test different states of the CLI:

Release Automation

We use a GitHub Actions workflow to publish releases automatically:

  1. Trigger: Pushing any tag starting with v* (e.g. v0.9.0) triggers the .github/workflows/release.yaml workflow.
  2. Release Notes: A GitHub Release is created, and release notes are automatically compiled by listing all commits and pull requests since the previous tag.
  3. Packaged Assets: The following assets are packaged and attached directly to the release page:
    • tycho (The main CLI executable script)
    • install.sh (The quick installation script)
    • LICENSE (The licensing terms)
    • All root markdown documentation (*.md files: README.md, HOWTO.md, PHILOSOPHY.md, COOKBOOK_MUSIC.md)

8. Troubleshooting