← CatchUpCast·Install CatchUpGist·FAQ·Feedback·Privacy

Subscriptions aren't on sale yet. Testers who already have a token can follow the subscription path below. Everyone else can set it up on their own AI key today, or ask to be told when subscriptions open.

Installing CatchUpCast

Pulls labeled Gmail into a synthesized digest — delivered as a plain-text email or a private podcast feed, your choice.

This covers installing the packaged release on Linux — any distro, including a Raspberry Pi. You don't need to build anything from source, install Python, or even install Docker yourself — the setup script in Step 1 installs Docker for you if it isn't already on your machine.

What you're installing

One Docker container running the scheduler + a local Flask admin UI (the “Admin Console”), plus a small companion container that checks for updates automatically. All state lives in a Docker volume on your own machine. Provider credentials are entered through the Admin Console and encrypted at rest — nothing is typed into a config file.

Choose your setup

Two questions decide everything else, and the Admin Console asks both when you first open it.

1. Who writes your briefing?

2. How do you want it? By email, to your own inbox, or as a podcast your podcast app plays. You can switch later on the Settings page without reinstalling.

Requirements

• Docker — the setup script installs this for you if it's missing (Docker Engine plus the Compose v2 plugin), so there's nothing to do here ahead of time.
• Outbound internet access to: Gmail (IMAP, port 993), your chosen LLM provider, and — full podcast path only — Google Cloud Text-to-Speech and Cloudflare R2
• No inbound ports need to be opened on your router by default
• Accounts to have ready:
  • Everyone: a Gmail account with 2-Step Verification turned on (Step 2)
  • With a subscription: your subscription token — nothing else
  • With your own key: a Google AI Studio or Anthropic account (Step 3), and for a podcast, Google Cloud (Step 4) and Cloudflare (Step 5)

Step 1: Download and run the setup script

Download the setup script for your platform and run it — it does everything by itself: installs Docker if it isn't already on your machine, creates the deployment file, generates your encryption key, and starts the containers.

⇩ install-catchupcast-linux.sh Windows — coming soon macOS — join the waitlist

• Windows: coming soon. A native app is in testing.
• macOS: not yet, and further out than Windows. Join the waitlist and we'll tell you when it lands.
• Linux: whether double-click runs it depends on your desktop environment (GNOME/KDE/etc. all handle executable scripts a little differently), so the reliable path is a terminal:

  chmod +x install-catchupcast-linux.sh
  ./install-catchupcast-linux.sh

  On a headless box (a Raspberry Pi over SSH, say) this is the whole install — there's no desktop to double-click from anyway, so the terminal command above is the normal way to run it, not a fallback. If Docker isn't installed yet, you'll be asked for your sudo password partway through.

The script creates a catchupcast/ folder next to itself and installs into that — a docker-compose.release.yml file and a secrets/ folder inside it. Note where you saved the script, because that folder is where your data lives from then on. It has its own folder deliberately: Docker names your data volume after the folder it runs in, so anything else installed the same way into the same place would collide with it. Re-run the script later to update — it finds the existing folder rather than making a second one. It mentions a key file, secrets/bootstrap_key; you don't need to copy it — once setup is done, the Admin Console's Backup is the backup to keep (see Backups). It finishes by telling you to open http://127.0.0.1:5000 — the Admin Console, covered in Step 6.

mkdir catchupcast && cd catchupcast
mkdir -p secrets
cat > docker-compose.release.yml <<'EOF'
services:
  app:
    image: ghcr.io/pppoole/email-podcast-pipeline:${APP_IMAGE_TAG:-latest}
    labels:
      - "com.centurylinklabs.watchtower.enable=true"
    network_mode: host
    volumes:
      - db-data:/app/data
    environment:
      - DB_PATH=/app/data/podcast.db
      - MESSAGES_DB_PATH=/app/data/messages.db
      - CONFIGURATOR_PORT=5000
      - TLS_CERT_DIR=/app/data/tls
    secrets:
      - bootstrap_key
    restart: unless-stopped
    healthcheck:
      test: ["CMD", "python", "-m", "email_podcast_pipeline.healthcheck"]
      interval: 30s
      timeout: 5s
      retries: 3
      start_period: 10s
    logging:
      driver: json-file
      options:
        max-size: "10m"
        max-file: "3"

  watchtower:
    image: ghcr.io/nicholas-fedor/watchtower
    volumes:
      - /var/run/docker.sock:/var/run/docker.sock
    environment:
      - WATCHTOWER_LABEL_ENABLE=true
      - WATCHTOWER_CLEANUP=true
      - WATCHTOWER_SCHEDULE=0 0 4 * * *
    restart: unless-stopped

secrets:
  bootstrap_key:
    file: ./secrets/bootstrap_key

volumes:
  db-data:
EOF

docker run --rm -v "$(pwd)/secrets:/app/secrets" ghcr.io/pppoole/email-podcast-pipeline:latest \
  python -m email_podcast_pipeline.cli init-secret

docker compose -f docker-compose.release.yml up -d
docker compose -f docker-compose.release.yml logs -f

Step 2: Gmail App Password

Gmail auth here is IMAP-based, not OAuth. Needed for both paths.

1. Go to myaccount.google.com and sign in with the Gmail account you want this to read from.
2. Click Security. Under “How you sign in to Google,” turn on 2-Step Verification if it's off — App Passwords require it.
3. Go to myaccount.google.com/apppasswords. Type an app name and click Create.
4. Copy the 16-character password shown — it's shown exactly once.
5. Nothing to save to disk — you'll enter this in the Admin Console's Connect Gmail page later.

Step 3: An LLM API key (Gemini or Claude)

Only for your own AI key — with a subscription, skip to Step 6. Gemini is simpler to set up (no Google Cloud project required) and the cheaper of the two to run — the recommended default unless you have a reason to prefer Claude. There's no model to pick: CatchUpCast uses a strong, current model from whichever provider you choose, and moves to its replacement by itself when the provider retires one.

Gemini (recommended default)

1. Go to aistudio.google.com/apikey and sign in with any Google account.
2. Click Create API key.
3. If asked which project, choose Create API key in new project if you don't have one.
4. Copy the key (starts with AIza).

Claude (alternative)

1. Go to console.anthropic.com and sign in or create an account.
2. API Keys → Create Key.
3. Copy the key (starts with sk-ant-).
4. Requires a payment method and prepaid credit — no free tier like Google AI Studio.

Step 4: Google Cloud Text-to-Speech API key (full podcast path only)

Written from a completely empty account — skip to sub-step 5 if you already have a project with billing enabled.

1. Go to console.cloud.google.com and sign in.
2. Create a project via the project dropdown → New Project.
3. Enable billing — menu (☰) → Billing. Required before any paid API responds, even usage that stays free.
4. Link billing to your project if not automatic.
5. Enable the API — search “Text-to-Speech API,” click Cloud Text-to-Speech API, then Enable.
6. Create an API key — menu → APIs & Services → Credentials → + Create Credentials → API key (not “Service account”).
7. Restrict the key (recommended): Edit API key → Restrict key → select Cloud Text-to-Speech API.

This is a different key from your Gemini key in Step 3.

Step 5: Cloudflare R2 setup (full podcast path only)

1. Create a Cloudflare account at dash.cloudflare.com/sign-up.
2. Find R2 Object Storage. Enabling it requires a payment method — normal use stays $0/month.
3. Create a bucket.
4. Enable Public Development URL in its settings — copy the URL, that's your R2 public base URL.
5. Create an API token: main R2 overview page → Manage R2 API Tokens → Account API Token → Object Read & Write, scoped to your bucket. Copy the Access Key ID and Secret Access Key (ignore the “Token value”).
6. Find your Account ID on the R2 overview page.

You should now have: Account ID, bucket name, public base URL, and Access Key ID/Secret Access Key.

Step 6: Reach the Admin Console and configure

The setup script already started everything. Open http://127.0.0.1:5000 on the same machine, or via an SSH tunnel for a remote host:

ssh -L 5000:127.0.0.1:5000 <user>@<host>

After setup, the Dashboard says how your briefing is made and delivered, lists anything still to do, and has a Run now button. For a podcast, it shows your feed URL to add to your podcast app.

What this costs

Precise about what's measured versus estimated. The main driver of your cost is how much you have your LLM read, not how many emails arrive.

Keeping costs in check

Why Inbox isn't allowed as the source label

The Source Label field on the Settings page still works exactly like before — type a name, and if it's a real label but doesn't exist yet, it gets created for you. Once Gmail is connected it also shows suggestions from your real labels as you type, but you're never limited to picking from that list: naming something brand new is expected, not an edge case. What's not allowed, suggested or typed, is Inbox itself (or Gmail's other built-in folders — All Mail, Sent, Spam, Drafts, Important, Starred): saving one of those is rejected, with an explanation, since they mix newsletters with personal mail, receipts, and whatever spam slipped through — exactly the scenario the caps below exist to guard against.

If a label collects more mail than expected

The numbers above assume a normal newsletter folder. Even with a real, dedicated label selected, one can still end up bigger than expected — a shared folder with years of backlog, say. A single digest run doesn't just try to summarize all of it at once. Three tunable settings guard against this, all on the Settings page:

• Max emails per digest (default 40) — how many emails one digest call can include; the rest wait for a later run.
• Max characters per email before it's shortened (default 20,000, roughly 3,300 words) — one unusually long email can't by itself use up a whole run's budget.
• Max combined characters per digest (default 300,000, roughly 50,000 words) — the real backstop against a handful of very large emails costing more than fifty small ones would.

Anything a cap leaves out simply waits for a later run — nothing is lost. You'll also get an email if a run ever actually hits one of these caps, so it's never silently slow. Lower any of these for tighter cost control, or raise them if you have a genuinely busy label and don't mind larger digests.

Setting a spending guardrail with your provider

The cap above bounds this project's own behavior. It's still worth knowing what your LLM provider itself offers as a backstop — confirmed by checking each provider's actual current behavior, not assumed to be equivalent:

• Claude (Anthropic Console): offers a real, enforced spending limit — Settings → Billing lets you cap a workspace, a user, or a specific API key at a fixed monthly dollar amount, and Anthropic stops honoring requests once it's hit. An actual hard stop, not just a notification.
• Gemini (Google Cloud Billing): budget alerts (Billing → Budgets & alerts) only send an email notification when a threshold is crossed — they don't pause or stop billing on their own. A true automatic cutoff requires building your own automation (a Pub/Sub notification triggering a Cloud Function that disables billing on the project) — see Google's own guide, Disable billing usage with notifications.

Either way, a budget alert is worth setting up regardless of the cap above — it's a second, independent signal if something unexpected happens.

Step 7: Reach it from elsewhere (optional)

Before switching away from loopback, set up a login on the Access page first.

Using Tailscale? By default Tailscale signs a machine out after 180 days, and then you can't reach the console remotely until you sign it back in. For a machine that's always on, turn on Disable key expiry for it in the Tailscale admin console. CatchUpCast itself keeps running either way.

Backups

Use Backup in the Admin Console. It makes one file, protected by a passphrase you choose, and a new machine is restored from it in a minute (choose Restore your settings from a backup on the first screen). Take a fresh one whenever you change a key or token.

The setup script also mentions secrets/bootstrap_key. You don't need it if you have a backup: it only helps in the rare case where this machine's data survives but that one file is lost.

Updating

Automatic — the companion container checks daily. To update immediately:

docker compose -f docker-compose.release.yml pull
docker compose -f docker-compose.release.yml up -d

Also installing CatchUpGist?

CatchUpGist is the companion product — it summarizes each email on its own instead of synthesizing a briefing across them. Plenty of people want both, for different mail. Installing it is the same shape as above, with the same setup script approach.

Full CatchUpGist install guide → — or grab the script directly:

⇩ install-catchupgist-linux.sh

Three differences worth knowing, all handled for you:

• It installs into its own catchupgist/ folder, separate from CatchUpCast's. They must not share one — Docker names the data volume after the folder, so a shared folder means the two fighting over a single volume.
• Its Admin Console is on http://127.0.0.1:5001, because CatchUpCast already uses 5000. If something else on your machine already has 5001, the installer picks the next free port and tells you which.
• It gets its own encryption key, in its own secrets/ folder. It has its own Backup in its own Admin Console; CatchUpCast's backup does not cover it.

Both products keep themselves updated independently and neither interferes with the other's updates.

Windows: coming soon for CatchUpGist too — a native app, a better fit for a laptop — see the FAQ.

Platform-specific notes

• Raspberry Pi / any headless Linux box: use a 64-bit OS (uname -m should say aarch64 or x86_64). Run install-catchupcast-linux.sh from Step 1 over SSH — it's the same script a desktop Linux user would run, no GUI required.
• Host networking (used by network_mode: host in the compose file) works natively on Linux — nothing extra to enable.

Troubleshooting

• install-catchupcast-linux.sh says Docker isn't reachable, but it's installed. Usually means your user isn't in the docker group yet — the script detects this, adds you, and tells you to log out and back in (or run newgrp docker) before running it again.
• Text-to-Speech API calls fail with a billing error. Check Step 4.3-4.4 — usually a project with no billing account linked.