Stop and start a sandbox

You’ll stop a sandbox, which ends its processes but keeps its files, and start it again. You need a shard server and a client: see Create a sandbox, run commands and move files.

# Create a sandbox and write a file in it.
shard create --name agent --memory 512MiB python:3.12
shard exec agent sh -c 'echo kept > /srv/note.txt'

# Stop it. The list hides it and says 1 stopped sandbox.
shard stop agent
shard list

# The --all list shows it as stopped.
shard list --all

# Start it again. The cat prints kept: the stop kept the file.
shard start agent
shard exec agent cat /srv/note.txt

# Remove it.
shard remove --force agent

import { Shard } from "useshards";

const shard = new Shard();
try {
  // Create a sandbox and write a file in it.
  const sandbox = await shard.create({ name: "agent", image: "python:3.12", memoryMiB: 512 });
  try {
    await sandbox.files.write("/srv/note.txt", "kept\n");

    // Stop it. Prints stopped.
    await sandbox.stop();
    console.log((await sandbox.inspect()).state);

    // Start it again. Prints kept: the stop kept the file.
    await sandbox.start();
    console.log((await sandbox.exec(["cat", "/srv/note.txt"])).stdout);
  } finally {
    // Remove it.
    await sandbox.remove({ force: true });
  }
} finally {
  shard.close();
}

from useshards import Shard

with Shard() as shard:
    # Create a sandbox and write a file in it.
    sandbox = shard.create("python:3.12", name="agent", memory_mib=512)
    try:
        sandbox.files.write("/srv/note.txt", "kept\n")

        # Stop it. Prints stopped.
        sandbox.stop()
        print(sandbox.inspect().state)

        # Start it again. Prints kept: the stop kept the file.
        sandbox.start()
        print(sandbox.exec(["cat", "/srv/note.txt"]).stdout)
    finally:
        # Remove it.
        sandbox.remove(force=True)

What a stop keeps

A stopped sandbox uses no memory and no CPU on the host. It keeps:

Its files, so everything you installed or wrote is still there after start.
Its name, its ID, its granted secrets and its network policy.
Its port forwards, which carry traffic again once it runs.

It loses its memory, its processes and its open connections. start boots it fresh from its files.

A process that shard run started with the always restart policy starts again on start, and so does an unless-stopped one that shard kill did not end. See Run a long-running server.

How a stop ends the processes

stop sends SIGTERM to every process in the sandbox, waits 30 seconds, then kills what is left.

The 30 seconds are fixed.
stop succeeds only once the processes have ended. If the provider still reports a live process 5 seconds later, the stop fails and the state does not change.
A stop on a sandbox that is still being created cancels the create.

Remove a stopped sandbox

shard remove deletes the sandbox and its files. A stopped sandbox needs no --force. A running or paused one does, and the remove stops it first.

To keep the files of a sandbox you remove, make a snapshot of it first: see Snapshot a sandbox and create from it.

Sandboxes and the lifecycle lists every state and what moves a sandbox between them.