Skip to main content
Schedules run a process inside a sandbox automatically, without you triggering it from your client. Use them for recurring jobs (a nightly cleanup, a periodic sync), a one-off task at a future time, or a task that runs once after a delay. Each schedule fires a command through the sandbox process API and records the outcome in an execution history. A sandbox can hold up to 100 schedules.

​
Schedule types

Every schedule has a type and a value that together define when it fires:
  • cron: recurring. value is a 5-field cron expression (e.g. 0 8 * * 1-5 for 8am on weekdays). Cron granularity is one minute.
  • at: one-off. value is an RFC 3339 datetime (e.g. 2026-07-01T09:00:00Z). The schedule fires once, then deletes itself.
  • sleep: one-off. value is a duration from now (e.g. 2h, 30m, 7d). On creation it is resolved to an at schedule, so a created sleep is returned with type: at and a concrete datetime.
One-off schedules (at and sleep) are removed automatically after they fire. A cron schedule keeps firing until you delete it.

​
Schedule input

The input object configures the process that each firing starts:
FieldTypeDescription
commandstringShell command to run inside the sandbox. Required.
namestringOptional process name, used to look up status and logs.
envobjectEnvironment variables for the process. Values are encrypted at rest and masked in API responses.
workingDirstringWorking directory for the command.
keepAlivebooleanKeep the sandbox awake (disable scale-to-zero) while the process runs. Defaults to true.
timeoutintegerProcess timeout in seconds. Defaults to 600. Set to 0 for no timeout.

​
Create a schedule

Create a recurring schedule on an existing sandbox: 
import { SandboxInstance } from "@blaxel/core";

const sandbox = await SandboxInstance.get("my-sandbox");

const schedule = await sandbox.schedules.create({
  type: "cron",
  value: "0 8 * * 1-5",
  input: {
    command: "python cleanup.py",
    env: { TARGET: "staging" },
  },
});
Create a one-off task that runs once, 2 hours from now: 
const schedule = await sandbox.schedules.create({
  type: "sleep",
  value: "2h",
  input: { command: "python report.py" },
});
// Returned resolved to type "at" with a concrete datetime

​
List and manage schedules

Read, update, and delete schedules by their id: 
// List every schedule on the sandbox
const schedules = await sandbox.schedules.list();

// Get one by id
const schedule = await sandbox.schedules.get("schedule-0");

// Update it
await sandbox.schedules.update("schedule-0", {
  type: "cron",
  value: "0 9 * * 1-5",
  input: { command: "python cleanup.py" },
});

// Delete it (stops further firings)
await sandbox.schedules.delete("schedule-0");
Deleting a schedule removes it from the underlying scheduler, so no further runs fire.

​
Execution history

Each firing records one execution. The statusCode is the HTTP status returned when the command was submitted to the sandbox, not the command’s own exit code: the scheduler does not wait for the command to finish. A 2xx or 3xx status means the command was accepted. List the execution history of a sandbox. It returns the runs of every schedule on the sandbox, newest first: 
const executions = await sandbox.schedules.executions();

for (const execution of executions) {
  console.log(execution.scheduleId, execution.statusCode, execution.processName);
}
Each record carries scheduleId, statusCode, executedAt, and the processName used to start the process, so you can look up its logs (see Log streaming). History is a ring buffer per schedule: once it reaches maxExecutions (default 100), recording a new run drops the oldest.

​
Manage from the console

You can create and inspect schedules from the Blaxel Console, on the Schedules tab of a sandbox. The tab lists every schedule with its type, timing, and command, and shows the execution history for each one.

Processes and commands

Execute and manage processes in sandboxes.

Log streaming

Access logs generated in a sandbox.

Expiration policies

Automatically delete sandboxes based on specific conditions.
Last modified on June 30, 2026