# Project pack: Tube Archivist @ 1cf5518

Facts about **Tube Archivist** for an AI following the [BespokeAI handover guide](https://handoff.bespokeai.software/guide/v4.md). Pinned to one version; never changes after publication.

> Tube Archivist is a self-hosted YouTube media server. You subscribe to channels and playlists, it downloads the videos and metadata with yt-dlp, and gives you a searchable library with a player, subtitles, comments and watch progress. It keeps videos watchable even if they disappear online.

## Setup path (checked 2026-11-03)
- **Needs Docker.** Tell the person before any setup work; no light non-Docker route is documented upstream. Docker Desktop on Windows may need a computer restart and an admin-only Windows feature (virtualisation); say so and let the person decide.
- Verdict source: https://docs.tubearchivist.com
- You may be unable to download source archives or run commands in this session. The person downloads and runs things; if you cannot fetch something, give any changed file in full in chat with its path.

## Version and source
- Repository: https://github.com/tubearchivist/tubearchivist
- Pinned commit: `1cf55183fa8c4aad7022e7c8a9b59f1069b78fbe`. Use exactly this version.
- Zip the person can download in a browser: https://github.com/tubearchivist/tubearchivist/archive/1cf55183fa8c4aad7022e7c8a9b59f1069b78fbe.zip
- Fresh checkout (only if you have a shell and git): use the commands below in an empty folder. If this exact source is already checked out, keep your branch and use the development command; do not clone again or reset local changes.
- Official docs: https://docs.tubearchivist.com
- Licence: **GPL-3.0-only**. Free to use and change. If you share your changed version with other people (give them the code or app), you must share your source code under the same licence. Using it privately for yourself or your household has no extra obligations.

## Commands from the pinned source
- Developer commands (they may use Docker):

  ```sh
  git clone https://github.com/tubearchivist/tubearchivist bespoke-tube-archivist
  cd bespoke-tube-archivist
  git checkout --detach 1cf55183fa8c4aad7022e7c8a9b59f1069b78fbe
  # Prepare development requirements and local configuration first.
  docker compose up -d archivist-es archivist-redis
  cd backend
  pip install -r requirements-dev.txt
  python manage.py runserver
  ```

- Separate trial of the current upstream release (not your changes; sample data and a separate data directory only):

  ```sh
  curl -O https://raw.githubusercontent.com/tubearchivist/tubearchivist/master/docker-compose.yml
  # edit TA_HOST, TA_USERNAME, TA_PASSWORD and ELASTIC_PASSWORD in the file first
  docker compose up -d
  # then open http://localhost:8000
  ```
- Tools these commands use: Docker with at least 4 GB of memory and plenty of disk space; Python and Node for development
- Develop: `cd backend && python manage.py runserver`
- Test: `cd backend && pytest`
- Stack: python, typescript (Django, React, Celery, yt-dlp). Difficulty for a non-developer with an AI: **advanced**. A Django back end with a React front end, Redis and Elasticsearch. Subscriptions and download rules are settings; code changes need the full stack running.
- The project's own AI instructions, in the repository: `AGENTS.md`, `CLAUDE.md`.
Personal data: **yes**. Stored in: Video files in a media folder plus the Elasticsearch index and a cache folder. Secrets are entered by the person, never in chat.

---
Later, only when a step needs it: [reference.md](https://handoff.bespokeai.software/p/tube-archivist/1cf5518/r3/reference.md) (customisation points, must-keep-working, data and costs, coding conventions) · [hosting.md](https://handoff.bespokeai.software/p/tube-archivist/1cf5518/r3/hosting.md) (long-term hosting; hosts are paid third parties) · [bespoke.yaml](https://handoff.bespokeai.software/p/tube-archivist/1cf5518/r3/bespoke.yaml) · [SKILL.md](https://handoff.bespokeai.software/p/tube-archivist/1cf5518/r3/SKILL.md)