> ## Documentation Index
> Fetch the complete documentation index at: https://docs.nanovm.dev.lithosai.cloud/llms.txt
> Use this file to discover all available pages before exploring further.

# Core concepts

> Understand sandboxes, images, snapshots, and the states you use to manage your work.

## Sandboxes

A sandbox is an isolated Linux environment with its own files, installed packages,
and running processes. Use it to run a task, host a development service, or give a
coding agent a workspace.

Every sandbox has an ID. Save that ID if you want to reconnect from another script:

```python theme={null}
from lithosbox import LithosBox

with LithosBox() as box:
    sandbox = box.sandboxes.get("YOUR_SANDBOX_ID")
    print(sandbox.run("pwd").check().stdout)
```

Files remain between commands. A regular `run()` starts a new shell, so use a
[session](/guides/run-commands#keep-shell-state) when you need a working directory
or environment variables to carry over.

## Images and templates

An **image** defines the software your sandbox starts with. Use the default image
or provide an OCI image reference, such as `python:3.12-slim`.

A **template** is a reusable starting environment prepared from an image with a
chosen CPU, memory, and runtime configuration. Create a named template when you
want to prepare an environment ahead of time and reuse it across tasks.

A sandbox created from a template or snapshot uses that source's CPU and memory
configuration. See [Custom images](/guides/images) for setup examples.

## Snapshots and forks

A **snapshot** saves a sandbox's files, memory, and running processes at a point in
time. Restore it to create a new sandbox from that checkpoint. Snapshots remain
available after you delete the original sandbox.

A **fork** creates one or more independent copies of a sandbox's current state.
Use forks to compare approaches, run tests in parallel, or give several agents the
same starting environment. Changes in one copy do not change the others.

See [Save, restore, fork](/guides/save-restore) for examples and guidance on
processes and network connections.

## Rest states

| State    | What happens to your work                                                     | How to continue                                         |
| -------- | ----------------------------------------------------------------------------- | ------------------------------------------------------- |
| Running  | Commands and background processes can run.                                    | Use the sandbox.                                        |
| Sleeping | Files and processes are held while the sandbox is idle.                       | Run a command or access a file; it wakes automatically. |
| Paused   | Files and processes are held until you explicitly resume.                     | Call `resume()`.                                        |
| Archived | Files, memory, and processes are saved; the sandbox releases its active slot. | Call `unarchive()`.                                     |
| Deleted  | The sandbox and its working files are removed.                                | Restore a retained snapshot into a new sandbox.         |

Idle sandboxes sleep automatically. Servers and background jobs keep a sandbox
awake while they are active. Archive a sandbox when you want to keep it for later
and release its active slot; delete it when you no longer need its working state.

## Durability rules

A snapshot marked **durable** has finished saving and can be used for recovery if
the original sandbox becomes unavailable. Use `snapshot(wait_durable=True)` when
saving a checkpoint you intend to keep. A snapshot may be restorable before it is
durable, but it is not yet protected against loss of the original environment.

Archived sandboxes also retain their saved state for recovery. Pausing and sleeping
preserve your current session but do not create a recovery checkpoint.

Rebooting preserves files and restarts the environment; running processes and shell
sessions are lost. Deleting a sandbox preserves only separately retained snapshots
and exports. See [Manage sandbox lifecycle](/guides/lifecycle) for the relevant commands.