self-hosted-sandboxes-memory changedmanaged-agents/self-hosted-sandboxes-memory
Nearest release: v2.1.311, published 4 hours before this site recorded the change. Shown because the two are within 24 hours of each other. Nothing here says the release caused the edit.
Recorded here
Lines+59added
Lines−2removed
From line
17
where the diff opens
First seen
2 Oct 2026
this site's first read of the page
Recorded edits11to this page, all time
### Prepare a macOS host
The whole hunk
from line 17, old and new numbered
/
from line 17
1717## Requirements
1818
1919* **A worker that mounts memory stores:** Use `ant` CLI 1.33.0 or later, or `EnvironmentWorker` from the Python, TypeScript, or Go SDK.
20* **A POSIX filesystem:** Windows hosts are not supported, because the worker requires `O_NOFOLLOW` when it opens memory files. A case-sensitive filesystem is recommended, so that memory paths that differ only in case do not collide.
21* **A writable `/mnt/memory` directory:** See [Prepare the host](https://platform.claude.com/docs/en/managed-agents/self-hosted-sandboxes-memory#prepare-the-host).
20* **A POSIX filesystem:** Windows hosts are not supported, because the worker requires `O_NOFOLLOW` when it opens memory files. A case-sensitive filesystem is recommended, so that memory paths that differ only in case do not collide. macOS volumes are case-insensitive by default, so such paths collide there.
21* **A writable `/mnt/memory` directory:** See [Prepare the host](https://platform.claude.com/docs/en/managed-agents/self-hosted-sandboxes-memory#prepare-the-host). On macOS, see [Prepare a macOS host](https://platform.claude.com/docs/en/managed-agents/self-hosted-sandboxes-memory#prepare-a-macos-host).
2222* **The work item's secret:** If your own code launches the worker, [forward the work item's secret](https://platform.claude.com/docs/en/managed-agents/self-hosted-sandboxes-workers#forward-the-work-items-secret) to it.
2323
2424<Note>
from line 29
2929
3030## Prepare the host
3131
32On macOS, skip the next command and follow [Prepare a macOS host](https://platform.claude.com/docs/en/managed-agents/self-hosted-sandboxes-memory#prepare-a-macos-host) instead.
33
3234Before you start the worker, create the parent directory and make it writable by the user the worker runs as:
3335
3436```bash
from line 40
3840Do not create the per-store directories yourself. The worker creates each store's `mount_path` (java, php: `mountPath`; csharp, go: `MountPath`) directory (for example, `/mnt/memory/user-preferences`) when a session starts and removes it when the session ends. If something already exists at that path, the worker refuses to start the session's work.
3941
4042In the [sandbox-per-session pattern](https://platform.claude.com/docs/en/managed-agents/self-hosted-sandboxes-workers#run-one-sandbox-per-session), the sandbox image needs a writable `/mnt/memory`. You don't need to bind-mount the memory directories to the host, because the worker uploads their contents to the store before the sandbox exits.
43
44### Prepare a macOS host
45
46On macOS, the root volume is read-only, so `mkdir` can't create `/mnt`. Instead, create `/System/Volumes/Data/mnt/memory` on the data volume, which is writable. Then add a line to `/etc/synthetic.conf`, so that macOS creates `/mnt` as a symbolic link to `/System/Volumes/Data/mnt`. These steps need administrator rights.
47
48Without this setup, the worker can't create a store's directory, so it fails the work item. The session then stays idle with no error event. See [Memory stores fail to mount](https://platform.claude.com/docs/en/managed-agents/self-hosted-sandboxes-operations#memory-stores-fail-to-mount).
49
50<Steps>
51 <Step title="Create the directory on the data volume">
52 Create the `memory` directory and make the worker's user its owner. `$USER` is your own username. If the worker runs as another user, replace `"$USER"` with that user's name.
53
54 ```bash
55 sudo mkdir -p /System/Volumes/Data/mnt/memory && sudo chown "$USER" /System/Volumes/Data/mnt/memory
56 ```
57
58 This location is only one option. If you use another, change the path in the `synthetic.conf` line to match. Anthropic has tested only `/System/Volumes/Data/mnt`.
59 </Step>
60
61 <Step title="Add a line to synthetic.conf">
62 Run `cat -et /etc/synthetic.conf`, which shows each tab as `^I` and each line end as `$`.
63
64 * If a line reads `mnt^ISystem/Volumes/Data/mnt$`, this step is already done. Go to the next step.
65 * If another line starts with `mnt`, stop. Something else on this Mac already defines `/mnt`.
66 * If the last line doesn't end with `$`, run `echo | sudo tee -a /etc/synthetic.conf` to end it.
67 * If it prints nothing or reports `No such file or directory`, continue. The `printf` command creates the file if it's missing.
68
69 Then add the line, unless one of the first two cases applies. Run this command only once, because each run appends another line.
70
71 ```bash
72 printf 'mnt\tSystem/Volumes/Data/mnt\n' | sudo tee -a /etc/synthetic.conf
73 ```
74
75 The command prints the line that it adds. The line maps the name `mnt` to the directory that holds `memory`. The file needs a tab between the two columns, which `\t` writes.
76 </Step>
77
78 <Step title="Create the link">
79 Run `apfs.util` with the `-t` option. It creates the link from the line you added, without a restart.
80
81 ```bash
82 sudo /System/Library/Filesystems/apfs.fs/Contents/Resources/apfs.util -t
83 ```
84 </Step>
85
86 <Step title="Check the result">
87 List `/mnt` and `/mnt/memory`.
88
89 ```bash
90 ls -ld /mnt /mnt/memory
91 ```
92
93 The first line ends with `/mnt -> System/Volumes/Data/mnt`. The second line shows the worker's user as the owner of `/mnt/memory`. You can now start the worker.
94 </Step>
95</Steps>
96
97Anthropic has tested this setup on macOS 26.7.1 with the `ant` CLI worker.
4198
4299### Isolate sessions that share a store
43100
No line in this hunk matches that.