Reference

Mount syntax

Mounts control which host directories are available inside the container. By default, Moat mounts the workspace directory at /workspace. Additional mounts are configured with the --mount CLI flag or the mounts field in moat.yaml.

To persist data across runs, use volumes instead. Volumes are managed by moat and survive container destruction.

Mount string format

Each mount is a colon-separated string:

<source>:<target>[:<mode>]

Field	Description
`source`	Path on the host. Absolute or relative to the workspace directory.
`target`	Path inside the container. Must be absolute.
`mode`	`ro` (read-only) or `rw` (read-write). Default: `rw`.

The mode field is optional. When omitted, the mount is read-write.

Examples

Mount string	Source	Target	Mode
`./data:/data`	`./data` (relative)	`/data`	read-write
`./data:/data:ro`	`./data` (relative)	`/data`	read-only
`/host/path:/container/path`	`/host/path` (absolute)	`/container/path`	read-write
`./cache:/cache:rw`	`./cache` (relative)	`/cache`	read-write

Object form

For advanced configuration like directory exclusion, use the object form:

Field	Type	Required	Default	Description
`source`	`string`	yes		Host path. Absolute or relative to the workspace directory.
`target`	`string`	yes		Container path. Must be absolute.
`mode`	`string`	no	`rw`	`ro` (read-only) or `rw` (read-write).
`exclude`	`[]string`	no	`[]`	Paths relative to `target` to overlay with tmpfs.

String and object forms can be mixed in the same mounts array.

CLI usage

The --mount flag adds mounts from the command line. It is repeatable. CLI mounts are combined with any mounts defined in moat.yaml. Duplicate targets are rejected.

# Mount a directory read-only
moat run --mount ./data:/data:ro ./my-project

# Mount multiple directories
moat run --mount ./configs:/app/configs:ro --mount /tmp/output:/output:rw ./my-project

# Combine with other flags
moat run --grant github --mount ./data:/data:ro ./my-project

If a --mount targets /workspace, it replaces the automatic workspace mount. The workspace directory will not be available unless you mount it explicitly.

moat.yaml usage

The mounts field accepts a list of mount strings, objects, or both.

mounts:
  - ./data:/data:ro
  - /host/path:/container/path:rw
  - source: .
    target: /workspace
    exclude:
      - node_modules

CLI --mount flags are additive with moat.yaml mounts. Both sources are combined at runtime.

Default workspace mount

Moat always mounts the workspace directory at /workspace as read-write. This mount is added automatically and does not need to be specified.

$ moat run ./my-project -- pwd
/workspace

$ moat run ./my-project -- ls
moat.yaml
src/
package.json

The workspace path is resolved to an absolute path on the host before mounting. Changes the agent makes in /workspace are written directly to the host filesystem and persist after the run completes.

To add excludes to the workspace mount, declare it explicitly with the object form. This replaces the automatic mount:

mounts:
  - source: .
    target: /workspace
    exclude:
      - node_modules

Path resolution

Relative source paths are resolved against the workspace directory. The target path must be absolute.

Source in mount string	Resolved host path (workspace: `/home/user/my-project`)
`./data`	`/home/user/my-project/data`
`../shared`	`/home/user/shared`
`/opt/datasets`	`/opt/datasets`

Access modes

Mode	Behavior
`rw`	Container reads and writes to the mounted directory. Changes are reflected on the host.
`ro`	Container reads from the mounted directory. Write attempts fail.

rw is the default when no mode is specified.

Excluding directories

Excluded directories are overlaid with tmpfs (in-memory) mounts inside the container. The host files at those paths are hidden, and the container sees an empty directory. Files written to excluded paths live in memory and do not touch the host filesystem. Each tmpfs mount defaults to 50% of system RAM (Docker’s default). On machines with many excludes or large dependency trees, monitor memory usage.

This is useful for large dependency trees (node_modules, .venv, vendor/) that cause performance problems with shared filesystem mounts — particularly VirtioFS on Apple Containers, where open file handles accumulate over time.

mounts:
  - source: .
    target: /workspace
    exclude:
      - node_modules
      - .venv

Since excluded directories start empty, install dependencies inside the container. Use a pre_run hook:

hooks:
  pre_run: npm install

mounts:
  - source: .
    target: /workspace
    exclude:
      - node_modules

On Docker, tmpfs overlays are always writable, even when the parent mount is read-only. This allows installing dependencies on tmpfs while keeping source files read-only. On Apple Containers, this behavior has not been verified — test with your setup if combining read-only mounts with excludes.

Excludes are only available in moat.yaml (object form). The --mount CLI flag uses the string format and does not support excludes.

Runtime differences

Both Docker and Apple containers support directory mounts with read-only and read-write modes. The mount syntax is identical across runtimes.

One difference: Apple containers only support directory mounts, not individual file mounts. Moat handles this internally (for example, mounting a directory containing a CA certificate rather than the certificate file directly). If a mount source is a file, Moat mounts the containing directory instead.

Global mounts

Global mounts are personal mounts that apply to every run. Configure them in ~/.moat/config.yaml:

mounts:
  - source: ~/.moat/scripts/statusline.sh
    target: /home/user/.claude/moat/statusline.sh

Global mounts use the same syntax as moat.yaml mounts (both string and object forms) with these constraints:

Source paths must be absolute (or use ~ for home directory). There is no workspace to resolve relative paths against.
Always read-only. Moat enforces read-only mode on global mounts regardless of the mode field.
Excludes are not supported.

Global mounts are appended after project mounts and before volumes.

CLI reference — moat run flags including --mount
moat.yaml reference — mounts field, volumes field, and all configuration options
Recipes — Complete project examples using volumes and excludes for dependency caching
Sandboxing — Workspace mounting and filesystem isolation
Security model — Trust boundaries and defense in depth