Skip to Content
ConceptsHibernation

Hibernation

Cages automatically hibernate when idle to save costs. When something needs the cage (a webhook, a cron job, or a manual wake), it starts back up with all data intact.

How it works

  1. Idle detection — Every 60 seconds, the system checks if a running cage has been idle
  2. Grace period — When idle timeout is reached (default: 30 minutes), the cage receives a POST /system/hibernate signal with a 30-second grace period
  3. Shutdown — The ECS task stops, security groups are cleaned up, and the billing segment closes
  4. Data persists — EFS storage is preserved across hibernate/wake cycles

Wake triggers

Cages can be woken by:

  • Webhook — An incoming HTTP request to the cage’s webhook URL triggers a wake
  • Cron schedule — The wake scheduler starts cages 5 minutes before their next scheduled cron job
  • Manual — lobster wake <name> or the dashboard start button
  • API — POST /cages/{cageId}/start

Cron-aware hibernation

Before hibernating, the system checks if the cage has a cron job due within the next 10 minutes. If so, hibernation is cancelled — it’s not worth stopping the cage just to restart it moments later.

If the next cron is further out, a wake schedule is written so the cage starts 5 minutes before the job is due.

Wake-on-webhook flow

Incoming webhook request
        │
  Gateway proxy checks cage status
        │
  Cage hibernated?
  ├─ Yes: buffer request (encrypted), return 202, trigger async wake
  └─ No:  forward to cage immediately
        │
  Cage wakes → health check passes → buffered requests drain in order

Buffered requests are AES-256-GCM encrypted at rest and expire after 5 minutes.

Configuration

The idle timeout is configurable per cage. The default is 30 minutes (1,800,000 ms).

# Set via the API when creating or updating a cage
# idleTimeoutMs: milliseconds before auto-hibernate
CagesBilling