Home Docs Claude Developer Platform

One capture · api

One read of Claude Developer Platformapi-20261027T003712Z

3 pages moved out of 821 read.

Pages moved 3 significant first

Pages read 821 in this capture

Captured 27 Oct 2026 00:37 UTC

Corpus hash bea83572cce4 corpus-hash

What this read moved

1-3 of 3

managed-agents/self-hosted-sandboxes-memory Changed · +59 / -2 lines

### Prepare a macOS host

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).

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.

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.

44### Prepare a macOS host

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.

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).

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.

54 ```bash

55 sudo mkdir -p /System/Volumes/Data/mnt/memory && sudo chown "$USER" /System/Volumes/Data/mnt/memory

56 ```

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>

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 `$`.

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.

69 Then add the line, unless one of the first two cases applies. Run this command only once, because each run appends another line.

71 ```bash

72 printf 'mnt\tSystem/Volumes/Data/mnt\n' | sudo tee -a /etc/synthetic.conf

73 ```

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>

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.

81 ```bash

82 sudo /System/Library/Filesystems/apfs.fs/Contents/Resources/apfs.util -t

83 ```

84 </Step>

86 <Step title="Check the result">

87 List `/mnt` and `/mnt/memory`.

89 ```bash

90 ls -ld /mnt /mnt/memory

91 ```

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>

97Anthropic has tested this setup on macOS 26.7.1 with the `ant` CLI worker.

4198

4299### Isolate sessions that share a store

43100

managed-agents/self-hosted-sandboxes-operations Changed · +6 / -6 lines

from line 331

331331

332332If the worker cannot mount a memory store when it claims a session, it fails the work item. The session emits no error event and stays idle.

333333

334| Symptom | Cause | Fix |

335| --------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |

336| The worker log contains `the work item carried no sessions token` (in Go, the `ErrSessionMemoryNoToken` error) and the work item fails. | The work item's per-session `secret` (csharp, go: `Secret`) did not reach the worker. Either your code did not forward it, or memory stores on self-hosted sandboxes are not enabled for your organization. | [Forward the work item's secret](https://platform.claude.com/docs/en/managed-agents/self-hosted-sandboxes-workers#forward-the-work-items-secret). If the worker polls and runs sessions in one process and still logs this, contact support. |

337| The worker log contains `something already exists at the memory store's path`. | A directory left over from a previous session, usually one whose worker was killed before its teardown ran. | Remove the leftover directory that the log line names. Edits in it that had not synced are lost. |

338| The worker log contains `cannot create the memory store's folder` and `the worker host must make this mount path writable`. | The user the worker runs as cannot create directories under `/mnt/memory`. | Create `/mnt/memory` and `chown` it to that user. See [Prepare the host](https://platform.claude.com/docs/en/managed-agents/self-hosted-sandboxes-memory#prepare-the-host). |

339| The session sits `idle` with a `requires_action` stop reason and no error event shortly after a worker claimed it. | The worker failed the work item because it could not mount a memory store, for one of the preceding reasons. | Fix the cause on the host, then send a [`user.interrupt`](https://platform.claude.com/docs/en/managed-agents/events-and-streaming#interrupt-the-agent) event. The session's work is queued again, and the next worker that claims it retries the mount. |

334| Symptom | Cause | Fix |

340340

341341### A custom tool call never returns

342342

managed-agents/self-hosted-sandboxes-reference Changed · +7 / -5 lines

from line 42

4242

4343## Host requirements

4444

45| Worker | Requirement |

46| ------------------ | ------------------------------------------------------------------------------------------------------------------------ |

47| All workers | A Linux host with `/bin/bash` at that exact path. The worker's bash tool invokes it directly, without consulting `PATH`. |

48| TypeScript SDK | `unzip` and `tar` on the `PATH`, and Node.js 22 or later. |

49| Python and Go SDKs | No additional binaries. These SDKs use their standard libraries for archive extraction. |

45| Worker | Requirement |

46| ------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |

47| All workers | A Linux or macOS host with `/bin/bash` at that exact path. The worker's bash tool invokes it directly, without consulting `PATH`. On macOS, that is the system Bash 3.2. |

48| TypeScript SDK | `unzip` and `tar` on the `PATH`, and Node.js 22 or later. |

49| Python and Go SDKs | No additional binaries. These SDKs use their standard libraries for archive extraction. |

5050

5151[Memory stores](https://platform.claude.com/docs/en/managed-agents/self-hosted-sandboxes-memory#requirements) add their own requirements.

53On macOS, the root volume is read-only, so `mkdir` can't create `/workspace`. Set the worker's working directory to one that you can write to, such as a `workspace` directory in your home directory. To use memory stores on macOS, first [prepare the macOS host](https://platform.claude.com/docs/en/managed-agents/self-hosted-sandboxes-memory#prepare-a-macos-host).

5254

5355## Sandbox filesystem

5456