background-worker · diff
git:20260613.bd14b2a to git:20260613.95ab83b
12 added, 30 removed. Audit B to B.
---
name: background-worker
- description: Run a long-lived or 24-7 job in a cloud VM that won't auto-stop — background workers, schedulers, bots, crawlers, or persistent agent loops. Disable auto-stop or set a TTL up to 30 days; the VM keeps its disk and IPv4, and you can resume it after a stop. Per-second flat pricing, ~10x cheaper than ephemeral sandboxes for steady-state work.
+ description: Run a long-lived or 24-7 background worker in a cloud VM that won't auto-stop — queue workers, schedulers, bots, crawlers, or persistent agent loops. Disable auto-stop or set a TTL up to 30 days; the VM keeps its disk and IPv4 and resumes after a stop. Per-second flat pricing, ~10x cheaper than ephemeral sandboxes for steady-state work.
---
# Background / 24-7 worker (Box)
- Use this when work must **keep running unattended**: a queue worker, a Telegram/Discord bot, a polling agent, a scheduled scraper, or any service that should stay up for hours or days.
-
- Ephemeral sandboxes (E2B microVMs, Codespaces) auto-die on a timer — wrong tool for always-on work. A Box can be told to **never auto-stop**, persists its disk, and keeps a dedicated IPv4.
+ Use this when work must **keep running unattended**: a queue worker, a Telegram/Discord bot, a polling agent, a scheduled scraper, or any always-on service. Ephemeral sandboxes (E2B microVMs, Codespaces) auto-die on a timer — wrong tool. A Box can be told to **never auto-stop**, persists its disk, and keeps a dedicated IPv4.
- ## When to prefer Box
+ ## Why Box
- - The job runs for hours/days or indefinitely → disable auto-stop or set a long TTL.
- - It must survive and be resumable → persistent disk + `box resume`.
- - Steady-state cost matters → flat per-second pricing beats ephemeral providers (50 always-on VMs ≈ $432/mo vs ~$4k+ elsewhere).
+ - **No session cap** — runs hours/days/indefinitely.
+ - **Persistent + resumable** — disk survives stop; `box resume` brings it back.
+ - **Cheap steady-state** — flat per-second pricing beats ephemeral providers (50 always-on VMs ≈ $432/mo vs ~$4k+).
- ## Prerequisites
+ ## Prereqs
- ```bash
- curl -fsSL https://box.ascii.dev/install | sh
- export BOX_API_KEY="bxk_..." # from https://box.ascii.dev/box/dashboard
- box login "$BOX_API_KEY" --json
- ```
+ `curl -fsSL https://box.ascii.dev/install | sh`, then `box login "$BOX_API_KEY" --json`.
## Recipe
```bash
- # Long-lived box that never auto-stops
box_id="$(box new --no-auto-stop --json | jq -r 'select(.event == "ready") | .id')"
-
- # Install + launch the worker under a process manager so it survives disconnects
box ssh "$box_id" -- bash -s < ./setup.sh
box ssh "$box_id" -- "cd /app && nohup ./worker.sh > /var/log/worker.log 2>&1 &"
-
- # Or bound it to a deadline instead of running forever
- box extend "$box_id" --hours 12 # or --ttl 2592000 (30 days, the max)
+ box extend "$box_id" --ttl 2592000 # optional: 30-day deadline
```
## Survival rules
- Running processes do **not** survive a stop/resume or fork — only the disk does. Make startup **idempotent** and relaunch the worker after any resume:
-
- ```bash
- box resume "$box_id" --json
- box ssh "$box_id" -- "cd /app && nohup ./worker.sh > /var/log/worker.log 2>&1 &"
- ```
-
- Use a process manager (`systemd`, `pm2`, `nohup`) so the worker outlives the SSH session.
+ Running processes do **not** survive stop/resume or fork — only the disk does. Make startup idempotent and relaunch after resume; use a process manager (`systemd`, `pm2`, `nohup`).
- ## Honest limits
+ ## Limits
- EU-only; disk-level snapshots only (no running-process capture); 100 active VMs soft cap; max TTL 30 days per extension (re-extend as needed).
+ EU-only; disk-level snapshots; 100 active VMs soft cap; max 30-day TTL per extension (re-extend as needed).