Long-running tasks

A single exec call is bounded: the maximum exec timeout is 300 seconds regardless of the sandbox’s own timeout. Work that runs longer - a dev server, a build, a watcher, a worker - should be started as a background process and inspected separately.

Start a background process

The body accepts cmd (required), cwd, env, and name. The sandbox must be running to start a process.

Check status and logs

Fetch the last N lines of stdout+stderr, or stream them live:

# Last 50 lines
curl "https://api.miosa.ai/api/v1/sandboxes/sbx_abc123/processes/proc_01hwxyz/logs?tail=50" 
  -H "Authorization: Bearer $MIOSA_API_KEY"

# Live stream (SSE)
curl "https://api.miosa.ai/api/v1/sandboxes/sbx_abc123/processes/proc_01hwxyz/stream" 
  -H "Authorization: Bearer $MIOSA_API_KEY"

Stop a process with DELETE, which sends SIGTERM and then SIGKILL after a grace period.

Services for long-lived daemons

Where a sandbox offers named services, they are the right home for a daemon you want to restart on demand rather than relaunch by hand:

miosa services create --name web --command "npm run dev" --cwd /workspace/app
miosa services logs web --tail 100
miosa services restart web

On Computers, services map directly to systemd units and restart automatically on failure; see the Services API.

Keep a sandbox alive

A background process only runs while the sandbox does. Two settings control that:

• always_on: true disables timeout and idle-timeout enforcement until an explicit lifecycle action, subject to tenant policy.
• idle_timeout_sec stops an abandoned persistent session after a period of inactivity; it is off unless you set it, and 0 disables it. A paused sandbox wakes on the next request.

For persistent sandboxes, hitting the timeout pauses the sandbox rather than destroying it. Explicitly non-persistent sandboxes are destroyed. See Timeouts and auto-stop.

See also