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:
- Payment and limits. The organization's payment method, spending cap, new-account
limit and running limit are checked first. If any of them refuses, the sandbox stays asleep.
The visitor gets
402, or503when the running limit is full. - A cap per hour. Anyone with a public URL can load it. So each sandbox takes at
most
wake_per_hourwakes from preview requests in a rolling hour (default 12, at most 120). Past that, visitors get429withRetry-After. The most running time strangers can cost you in an hour iswake_per_hour × sleep_after_s. - On the record. Each wake is in the audit log as
sandbox.wakewith actorpreview:<port>. It is also sent as asandbox.wokewebhook withreason: "preview".
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.
- Asleep. When a run is due, a sleeping sandbox is woken for it, after the same
payment and limit checks as any wake. With
wake: false, a run that falls due while the sandbox sleeps is skipped instead. - Each run is kept.
GET /v1/sandboxes/{id}/schedulesshows each schedule's last run:status(ok,failedorskipped),exit,error(why it failed or was skipped), the last 4 KiB of output and how long it took. - Run it now.
POST /v1/sandboxes/{id}/schedules/{sid}/runruns it once, under the same rules, and leaves its next time unchanged.DELETE /v1/sandboxes/{id}/schedules/{sid}removes it. - Limits. A sandbox has at most 10 schedules, and runs at most once a minute. If the control plane was down when runs were due, the schedule runs once and moves to its next time; missed runs are not replayed. Schedules go away with their sandbox.
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.