Host mounts

TX9 can expose a host directory or a host-mounted NAS share inside one box's agent container. The host remains responsible for mounting the filesystem and for its credentials; TX9 stores only the source path, container target, and access policy.

Add the Nexus agents share to media-bot

Mount the NAS on the host first, then add it to the box:

findmnt --target "$HOME/agents"
tx9 mount add media-bot "$HOME/agents" /mnt/agents --require-mountpoint
tx9 mount list media-bot

The default is read/write. Add --read-only when the agent should only consume the data:

tx9 mount add media-bot "$HOME/agents" /mnt/agents \
  --require-mountpoint --read-only

mount add recreates only the disposable agent container. It does not remove or rewrite the agent's durable /data volume, its Executor container, or either container's named volume. If the box was running, TX9 starts the new agent container and runs the normal readiness checks.

TX9 records the desired mount in ~/.tx9/boxes/<box>.env. A later tx9 upgrade <box> reapplies it automatically. A portable .tx9 backup does not contain this host-local configuration; add the appropriate host mounts after importing a box on another machine.

Why targets live below /mnt

tx9 backup archives the agent's /data volume. External mounts must target a child of /mnt so a backup cannot accidentally walk a NAS, copy a large media library into the box archive, or make restores depend on host storage.

The mounted files are still fully visible to the free-rein agent container. Read/write mounts let the agent modify or delete host data, so use --read-only unless writes are intentional.

NAS safety and permissions

Use --require-mountpoint for network storage. Before every add, remove, or upgrade, TX9 verifies that the exact source path appears in the host's mount table. If the NAS is unavailable, TX9 stops before removing a container instead of binding the empty directory underneath the missing mount. Because mount remove recreates the agent with the remaining desired mounts, an offline --require-mountpoint source can also block removing a different mount until the share is back (or removed first).

NAS mounts commonly map all files to the host user's numeric group. TX9 checks the source directory permissions and adds the required non-root host GID as a supplemental group inside the agent container. This is why a share owned by host GID 1000 remains accessible to TX9's agent user even though the agent's primary UID/GID is 1001.

The permission check reads only the classic owner/group/other mode bits. Directories whose access is granted purely through POSIX ACLs are rejected; grant access through a group bit (e.g. chgrp + chmod g+rwx) instead.

The host mount itself must persist across reboots and be available before the agent container starts. On Linux, a systemd .mount/.automount unit or an equivalent _netdev mount is preferable to an interactive desktop mount.

Inspect or remove mounts

tx9 mount list media-bot
tx9 mount remove media-bot /mnt/agents

Removal updates the desired state and recreates only the agent container, just like addition. Removing a TX9 mount never unmounts the source on the host.