Skip to content

Lifecycle

Sandbox statuses, suspend and resume, idle suspend, stop and start, and why a sandbox has its status.

Updated View as Markdown

Statuses

Status Means
starting It’s being started.
running It’s running. Commands and file calls work.
suspending Its memory and files are being saved.
suspended Its memory and files are saved. A command or file call resumes it.
resuming It’s being resumed.
stopping Its processes are being ended.
stopped Its processes ended. Its files are kept. Start it to run it again.
impaired It can’t be reached right now. Its files are kept.
failed It couldn’t be created or started.
deleting It’s being deleted.

New statuses may appear. statusReason says why a sandbox has its status, when there’s something to say: see Reasons.

Create

Create waits up to 10 seconds and answers with the sandbox as it is by then: usually running, otherwise starting, or failed with a statusReason. Suspend, resume, stop and start wait up to 10 seconds the same way. To wait longer, read the sandbox until its status settles.

Suspend and resume

Suspend saves the sandbox’s memory and files. A suspended sandbox runs nothing and doesn’t count toward the running vCPU and memory quotas.

Resume carries its processes on from where they were. Two things change across a suspend:

  • Its outbound addresses can be different. See Networking.
  • Connections that were open are closed.

You don’t have to resume a sandbox yourself: a command or a file call on a suspended sandbox resumes it first.

memoryRestored on the sandbox says how its last resume or start went: true when it resumed with its memory, false when it started again from its disk, null before the first one.

Idle suspend

A sandbox suspends by itself after idleSeconds with no command, no file call and no open interactive command. The default is 300. Set it at create to 0 for never, or to between 60 and 86400.

ezgh sandboxes create "$IMAGE" --idle-seconds 3600

Stop and start

Stop ends the sandbox’s processes and keeps its files. Start runs it again from its disk: its files are there and its processes aren’t. A command or a file call on a stopped sandbox is refused with 409 sandbox_not_running: start it first.

Maintenance

During maintenance a running sandbox is suspended and then resumed by itself. Its processes carry on, its open connections are closed, and its outbound addresses can change.

Reasons

statusReason With status Means
idle suspended, suspending Suspended after no commands or file calls for its idle time.
drain suspended, suspending, resuming Suspended for maintenance. It resumes by itself.
no_capacity suspended There was no room to resume it. Resume it to try again.
no_capacity stopped There was no room to start it. Start it to try again.
no_capacity failed There was no room for it when it was created.
vpc_unavailable stopped Its VPC network wasn’t ready. Start it to try again.
vpc_unavailable suspended Its VPC network wasn’t ready. Resume it to try again.
host_lost, host_rebooted stopped, starting Starting again from its disk.
suspend_failed running The last suspend didn’t finish. The sandbox kept running.
suspend_failed stopped Its memory couldn’t be saved. Start it to run it from its disk.
snapshot_unusable stopped Its saved memory couldn’t be restored. Start it to run it from its disk.
image_prepare_failed failed The image couldn’t be prepared.
start_failed failed The sandbox couldn’t be started.
reboot_loop failed It restarted 5 times in a minute and was stopped.
guest_halted stopped It was shut down from inside.
interrupted stopped It stopped unexpectedly.
operator_hold stopped, suspended EZGH stopped it or put it on hold. It can be deleted, but not started or resumed until EZGH lifts the hold. Contact support.

New reasons may appear.

While a hold is in place, these requests are refused:

Answer Means Do
409 sandbox_held A start or resume of a sandbox EZGH has stopped. Contact support.
409 organization_held A create, start or resume while EZGH has the organization’s sandboxes on hold. Contact support.

Network turned off

EZGH can turn off a sandbox’s network. The sandbox keeps running, and you can still run commands in it and read its files, but nothing in it can reach the internet and its open connections end. Its status doesn’t change; egressBlocked on the sandbox is true. It stays off when the sandbox is suspended and resumed or stopped and started. Contact support.

Delete

Delete answers with the sandbox as deleting, and it’s 404 once it’s gone. Deleting a sandbox removes its files and its saved memory. It can’t be undone.

Navigation

Type to search…

↑↓ navigate↵ selectEsc close