# Project pack: ArchiveBox @ d1c5a50

Facts about **ArchiveBox** for an AI following the [BespokeAI handover guide](https://handoff.bespokeai.software/guide/v2.md). This pack is pinned to one version and never changes after publication.

> ArchiveBox takes a list of links, such as bookmarks, browser history or an RSS feed, and saves a durable copy of each page in several formats: HTML, PDF, screenshot, text, and video where available. You browse and search your archive in a web interface, and the files remain readable without any special software.

## Version and source
- Repository: https://github.com/ArchiveBox/ArchiveBox
- Pinned commit: `d1c5a50b7f14a97be4a0af98623e14379fad5dde`. Use exactly this version.
- Fresh checkout: use the setup below in an empty folder. If you already have this exact source checked out, keep your branch and use the development command instead; do not clone again or reset local changes.
- Or download a zip: https://github.com/ArchiveBox/ArchiveBox/archive/d1c5a50b7f14a97be4a0af98623e14379fad5dde.zip
- Official docs: https://docs.archivebox.io
- Licence: **MIT**. Free to use, change and share, even commercially. Keep the original copyright notice.

## Running the pinned source
- Fresh pinned-source setup (skip clone and checkout in an existing worktree):

  ```sh
  git clone https://github.com/ArchiveBox/ArchiveBox bespoke-archivebox
  cd bespoke-archivebox
  git checkout --detach d1c5a50b7f14a97be4a0af98623e14379fad5dde
  # Prepare development requirements and local configuration first.
  uv sync
  uv run archivebox init
  uv run archivebox server 0.0.0.0:5797
  ```

The commands below are a starting point from the reviewed source. Prepare the listed tools, local configuration and companion services before starting the app. These instructions have not yet been validated in participant sessions.

### Separate trial of the current release
This tries an upstream release, which may differ from the pinned source above. It does not run your source changes. Use only sample data and a separate data directory or volume. Check the upstream documentation before running it.

  ```sh
  mkdir -p archivebox-data
  docker run -d --name archivebox -v "$PWD/archivebox-data:/data" -p 5797:5797 archivebox/archivebox:latest
  # then open http://localhost:5797
  ```

- Needs: Docker for a trial, Python 3.11+ and uv for development, plenty of disk space
- Develop: `uv run archivebox server 0.0.0.0:5797`
- Test: `uv run pytest`
- Stack: python, javascript (Django, Playwright, wget, yt-dlp, SingleFile). Difficulty for a non-developer with an AI: **moderate**. A Python and Django project that coordinates many command-line tools. It has plugin folders, and adding a new archive method is a small plugin.

## The project's own AI instructions
Read these in the repository before changing code: `AGENTS.md`.

## Customisation points (settings → extend → code)
- **archive-methods** [settings]: Which formats are saved per page. → `ArchiveBox config (SAVE_PDF, SAVE_SCREENSHOT, SAVE_MEDIA and so on)`
- **schedules-and-feeds** [settings]: Archive an RSS feed or bookmarks list on a timer. → `archivebox schedule and the Admin → Schedules page`
- **access** [settings]: Who can see or add pages. → `PUBLIC_INDEX, PUBLIC_SNAPSHOTS and users`
- **plugins** [extend]: Add a new way of saving or extracting pages. → `archivebox/plugins/`
- **web-ui** [code]: Screens and views. → `archivebox/templates and archivebox/core`

## Must keep working
- Archive folder structure, since users rely on stable paths.
- Django migrations. Add new ones; never edit old ones.
- Access controls for private archives.

## Staying updatable
Use configuration and plugins. Keep new extractors self-contained and don't change the archive layout.

## Data, costs and safety
- Personal data: **yes**. Stored in: A data folder containing the index and one folder per archived page. Archives can be very large and may contain private pages you were logged in to. Back up the data folder.
- Service: Browser extension (optional, free): Archive pages as you browse.
- Setting `ADMIN_USERNAME`: Name of the first admin user.
- Setting `ADMIN_PASSWORD` (**secret**: the person enters it themselves, never in chat): Password of the first admin user. Never paste it into an AI chat.
- Setting `PUBLIC_INDEX`: Set to False to require login to view the archive.
- Archived pages can contain private data from sites you were logged in to. Keep the archive private.
- Only enable the public index on purpose.
- Respect copyright when sharing archives.

---

# Customising ArchiveBox

ArchiveBox has an AGENTS.md in the repo. Most changes are configuration or small plugins.

## How the code is laid out

| You want to change… | Look in |
|---|---|
| Core Django app and models | archivebox/core/ |
| Command-line commands | archivebox/cli/ |
| Extractor plugins | archivebox/plugins/ |
| Configuration | archivebox/config/ |
| Importers | archivebox/importers/ |
| Templates | archivebox/templates/ |
| Agent skills | skills/ |

## Use the gentlest change first

1. **Settings (no code):** archive methods, schedules and access.
2. **Extend:** plugins and API.
3. **Code:** the core, templates and importers.

## Recipes

- **New importer:** add a parser in `archivebox/importers` that returns links and titles, and register it.
- **New extractor:** add a plugin that runs a command on a URL and writes its output into the snapshot folder.

## Running and checking your changes

- `uv run pytest` for the area you changed.
- Add one URL and confirm the saved copy opens.

## Pitfalls

- Archiving runs real browsers and downloads media. Test with a few URLs.
- Keep logged-in cookies out of Git.

---
Machine-readable: [bespoke.yaml](https://handoff.bespokeai.software/p/archivebox/d1c5a50/r2/bespoke.yaml) · Hosting options: [hosting.md](https://handoff.bespokeai.software/p/archivebox/d1c5a50/r2/hosting.md) · Agent skill: [SKILL.md](https://handoff.bespokeai.software/p/archivebox/d1c5a50/r2/SKILL.md)