To give sandbox agents a persistent workspace across restarts, keep the workspace directory on a network disk that outlives the sandbox and mount that disk in every new sandbox. The agent keeps its files instead of rebuilding its working directory each time. With Archil, files on the disk remain when a sandbox is killed or times out. The sandbox can be disposable without making the agent’s progress disposable too.
How to give sandbox agents a persistent workspace across restarts
Put the agent’s working directory on an Archil disk and mount it wherever the agent runs. This keeps the compute environment that does the work separate from the files that record it. A sandbox can end while the workspace remains available for the next session.
That separation also defines what “picks up where it stopped” means. A persistent workspace preserves files, including the repository, notes and intermediate results that the agent writes there. It does not, by itself, mean a new sandbox resumes the previous sandbox’s running processes. Archil sandboxes also support pause behavior that saves memory and running processes, but the workspace pattern starts with the simpler requirement of keeping the agent’s work.
What a sandbox restart erases
In many sandbox setups, the sandbox filesystem is disposable. When a sandbox is killed, times out or is recreated, files written inside it are gone. For an agent, those files can be a cloned repository, generated output, notes and intermediate results. The loss reaches beyond the final deliverable. It also wipes out the work the next session would need to pick up without going through setup again.
That is why a restart can become more than a compute event. If the repository and the agent’s notes lived only inside the sandbox, the next session starts without them and has to redo setup work. A generated file survives the sandbox when it is saved in a persistent location.
The cloned repository and intermediate results belong in the persistent working directory if they need to survive. Files left on a disposable filesystem still follow that filesystem’s lifecycle. The agent must do its workspace work in the directory backed by that disk.
Keep the workspace on a disk that outlives the sandbox
An Archil disk is durable independently of any sandbox. Once fsync returns, data is stored redundantly across multiple Availability Zones. That gives the workspace a durability boundary separate from the process using it. Keeping the disk alive and getting recent writes onto it are distinct, related requirements.
In particular, the archil client buffers recent writes and sends them in the background. A claim that files on the disk survive a killed sandbox should not be read as a claim that every buffered write has already reached the disk. For planned shutdowns, archil unmount returns once every write has reached the disk, so the session’s file work is done before the sandbox goes away.
Archil mounting takes about 50 ms at p50, so mounting at the start of each session adds little to start-up time. That figure describes the median mount time. It supports a straightforward pattern, though. Each new sandbox attaches the durable directory before the agent starts working, rather than treating that directory as something to reconstruct inside fresh compute.
The same disk can mount in Archil sandboxes and in sandboxes from E2B, Daytona, Modal and Vercel Sandbox, so the workspace is not tied to one compute provider. This portability applies to the workspace itself. It keeps the files separate from the choice of where the agent executes, without making a broader claim that every part of the environment moves with them.
Example: one persistent workspace across two sandboxes
For a sandbox from another provider, install the archil client in the image and mount the disk as root at the start of the session. The agent then works in the mounted directory, and the session unmounts it before the sandbox goes away. In a Linux sandbox with the client installed, the sequence looks like this. The path /workspace is the agent’s working directory in the example.
# Start of every sandbox session
export ARCHIL_MOUNT_TOKEN="<disk-token>"
mkdir -p /workspace
archil mount dsk-0123456789abcdef /workspace --region aws-us-east-1
# ... the agent works in /workspace ...
# Before the sandbox is killed: flush buffered writes and release the disk
archil unmount /workspace
To use that workspace across two sandboxes, the second sandbox mounts the same disk when its session starts. The directory path gives the agent a place to work, while the disk identifier selects the persistent workspace. A fresh sandbox does not require a fresh set of workspace files. The important continuity is the disk being attached.
The unmount belongs in a finally block or a shell trap, rather than only at the end of the successful work path. Because the client sends buffered writes in the background, unmounting is more than removing a directory attachment. It waits until every write has reached the disk and releases the disk for the next session.
A plain mount is exclusive, so one sandbox holds the workspace at a time. This fits the example’s hand-off from one sandbox to another. If several sandboxes need to mount the disk at once, use --shared or --conditional.
An abrupt kill needs separate handling because the sandbox may not get to unmount. If it is killed before unmounting, its lock is marked orphaned and can be released with the SDK’s listDelegations and revokeDelegation. Releasing the orphaned lock addresses access to the workspace. It does not replace the write-flushing step that a clean session ending would have performed.
With Archil sandboxes, attach the disk when creating the sandbox. The following example writes a progress note, stops the sandbox, starts it again and reads the note. Saved mounts are kept across that cycle.
import { Archil } from "disk";
const client = new Archil({
apiKey: process.env.ARCHIL_API_KEY,
region: "aws-us-east-1"
});
const sandbox = await client.sandboxes.create({
mounts: [{
disk: "dsk-0123456789abcdef",
path: "/workspace"
}],
});
await sandbox.exec("echo 'step 1 done' >> /workspace/progress.md");
await sandbox.stop();
await sandbox.start(); // saved mounts are kept
console.log(
(await sandbox.exec("cat /workspace/progress.md")).stdout
);
Persistent workspaces in Archil sandboxes
Archil sandboxes have a further distinction from the disposable-filesystem pattern. Their root filesystem itself lives on an Archil disk, so files and installed packages survive stop, start and pause without an extra mount. The root filesystem already has durable backing. The extra mount gives the workspace its own disk.
Additional disks passed as mounts when a sandbox is created are kept across stop and start, and across pause and resume. That is why the code example does not attach /workspace again after calling start. The saved mount remains part of the sandbox’s setup. This behavior avoids turning each restart into another manual attachment step. It also lets the example focus on the useful test, which is reading the progress file after the stop-and-start cycle.
A clean stop or pause flushes the root filesystem and every mounted disk before the sandbox reaches the stopped or paused state. The ordering is the key detail here. The completed transition follows the flush, rather than leaving that file work as an afterthought. This is different from a sandbox being killed before it can unmount.
Pause saves memory and running processes as well as workspace files. A progress note on disk and a process in memory do different jobs. For the full environment, including installed tools and isolation, see Archil’s article on keeping an AI agent’s environment across sandbox restarts.
Reading the workspace from your app
Because the workspace is a disk rather than a sandbox, an application can read it while no sandbox is running. The agent’s compute session does not have to remain alive just to make saved output accessible. That changes the role of the workspace. It is not only a place for the next agent session to find its files, but also a hand-off point for the application that needs the results.
The TypeScript and Python SDKs read files on a disk by key with getObject and get_object, without mounting it. Archil’s S3-compatible API also provides access to the disk. The application does not need to take the agent’s route through a mounted working directory to read them.
An agent can therefore write results into the workspace, and a web app or a human reviewer can read them directly. The sandbox can finish its job without also becoming the permanent serving point for those results.