Lifecycle

A sandbox moves through a lifecycle as PHPSandbox prepares, runs, stops, restarts, and eventually removes it.

The runtime is the execution environment used to operate the sandbox during this lifecycle. It is not a separate resource you need to manage.

Preparing

After a sandbox is created, PHPSandbox prepares it. Depending on how it was created and configured, preparation can restore or import files, install dependencies, apply environment configuration, run setup commands, and start required services and processes.

The Workspace waits for preparation before exposing tools that need the sandbox to be ready. SDK operations also wait when they require a ready sandbox. If preparation fails, PHPSandbox reports the setup stage or operation that prevented it from completing.

See Project setup to define repeatable preparation for an imported project.

Ready

Once preparation succeeds, the sandbox is ready. It can run commands, operate configured processes and services, and serve previews.

Actions that require a ready sandbox wait for this stage before running.

Stopped and restarted

Stopping a sandbox ends its running compute without deleting the sandbox. Restarting it prepares the sandbox again from its current files and configuration, then starts its configured processes and services.

Streams, terminals, and running processes end when a sandbox stops. Work saved to the sandbox remains available when it restarts, subject to its retention policy.

Removed

Deleting a sandbox removes it and makes its files and runtime unavailable. A sandbox can also be removed automatically when its retention policy considers it stale.

SDK-created and SDK-forked sandboxes are automatically removed when they become stale unless persistence was requested and is available to the account. The applied policy determines when a sandbox is considered stale and when it may be removed.

See Persistence and limits for retention policies and resource limits.

What to read next

• Persistence and limits to design around retention and resource limits.
• Project setup to control how a sandbox prepares and starts a project.
• Managing sandboxes to manage a sandbox programmatically.