kosa8 docs

Guides / kosa8 Cloud / Wake on request and schedules

Wake on request and schedules

A kosa8 Cloud sandbox can go to sleep when it is idle and keep its memory and disk. While it sleeps you pay only for its snapshot. With two settings it still answers the web and runs its jobs: a preview URL that wakes it when a request arrives, and schedules that run a command on a cron time.

Wake on request

Open a preview with wake: true:

curl -s -X POST https://api.kosa8.com/v1/sandboxes/sbx_…/previews \
  -H "Authorization: Bearer $KOSA8_API_KEY" -H 'Content-Type: application/json' \
  -d '{"port":3000,"public":true,"wake":true,"wake_per_hour":12}'
# {"preview":{"port":3000,"public":true,"url":"https://3000-….kosa8.dev/","wake":true,"wake_per_hour":12, …}}

A request that reaches the URL while the sandbox sleeps is held while the sandbox wakes. This usually takes a few seconds and never more than 30. The request is then served as if the sandbox had been awake. The sandbox goes back to sleep after its sleep_after_s of idle time, as usual. Every request in a page load shares one wake.

A wake starts billing at the running rate again, so it follows the same rules as POST /v1/sandboxes/{id}/wake:

Without wake (the default), a sleeping sandbox's preview answers 503 until it is woken through the API. Turn wake off with {"port":3000,"wake":false}. Opening the port again without naming wake keeps the current setting.

Only GET and HEAD requests are retried. That matters when the host puts the sandbox to sleep in the seconds after the control plane last heard from it. A POST body cannot be replayed, so that rare request gets 503 with Retry-After.

Schedules

curl -s -X POST https://api.kosa8.com/v1/sandboxes/sbx_…/schedules \
  -H "Authorization: Bearer $KOSA8_API_KEY" -H 'Content-Type: application/json' \
  -d '{"name":"backup","cron":"*/15 * * * *","cmd":["sh","-c","date >> /workspace/ticks"],"wake":true}'
# {"schedule":{"id":"sch_…","cron":"*/15 * * * *","next_run_at":"2026-11-14T12:15:00.000Z","last_run":null, …}}

cron has five fields in UTC: minute, hour, day of month, month, day of week. It uses the same syntax as function schedules: numbers, ranges, steps and lists, with no names. Each run is the command run as a buffered exec, stopped at 90 seconds. For longer work, use a persistent sandbox and have the command start a background job and return.

Schedules run in the control plane, not on the sandbox's host. A host-side timer could not check whether your organization may pay for the wake, and it would keep firing while the organization is frozen. The control plane checks both. A frozen or suspended organization's runs are skipped and recorded as skipped.