Sprite Patterns

Sprites are persistent, sandboxed environments (docs) that execute subscription actions. This page covers patterns for working with sprites effectively in components.

Shared Sprites

By default, each subscription gets its own sprite. Use --sprite-name to share a single sprite across multiple subscriptions:

wh sub create rk/find-papers --repo org/repo \
  --kind cron --cronspec "0 4 * * *" \
  --executor sprite --sprite-name research-sprite \
  --command '...' --input-mode stdin

wh sub create rk/analyze-papers --repo org/repo \
  --kind cron --cronspec "0 7 * * *" \
  --executor sprite --sprite-name research-sprite \
  --command '...' --input-mode stdin

Benefits:

• Reduces clone duplication — the repo is already on disk after the first run
• Simplifies debugging — one environment to inspect
• Shared filesystem state across runs
• Faster wake times — shared sprites stay warm longer (~100-500ms warm wake vs 1-2s cold)

Filesystem Persistence

The entire sprite filesystem persists across runs — not just /tmp. Files written in one run are available in the next, surviving hibernation between invocations. Use a pull-or-clone pattern to avoid re-cloning on every run:

cd /home/sprite/component && git pull --ff-only 2>/dev/null || {
  rm -rf /home/sprite/component
  git clone https://github.com/owner/repo.git /home/sprite/component
}
cd /home/sprite/component

Token TTL

The default token TTL for sprite actions is 10 minutes. For actions that invoke claude -p (which typically runs 15-20 minutes), increase the TTL:

wh sub create cd/digest-worker --repo org/repo \
  --token-ttl 30 \
  ...

Without sufficient TTL, WH_TOKEN expires before post-processing can write results back.

Credentials and Environment Variables

Credentials and environment variables for action scripts are configured declaratively in the manifest’s actions[].env section. See the Manifest Reference for details on injecting WarmHub tokens and credential set values into the action runtime.

For private component repos, set source.auth in the manifest action definition. The installer generates an authenticated clone wrapper automatically. See Authoring Components for the private repo pattern.

Debugging

Checking Logs

View recent deliveries for a subscription:

wh sub log <subscription-name> --repo org/repo

View per-attempt detail for a specific delivery:

wh sub attempts <subscription-name> <commitId> --repo org/repo