# 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](https://docs.kosa8.com/guides/cloud-previews/) 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`, or `503` when 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_hour` wakes from preview requests in a rolling hour (default 12, at most 120). Past that, visitors get `429` with `Retry-After`. The most running time strangers can cost you in an hour is `wake_per_hour × sleep_after_s`.

- **On the record.** Each wake is in the audit log as `sandbox.wake` with actor `preview:<port>`. It is also sent as a `sandbox.woke` webhook with `reason: "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](https://docs.kosa8.com/guides/cloud/) 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}/schedules` shows each schedule's last run: `status` (`ok`, `failed` or `skipped`), `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}/run` runs 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.

---
Source: https://docs.kosa8.com/guides/cloud-wake-cron/
