Container Mounts

Container Mounts allow administrators to configure fixed mounts that are automatically injected into every persistent container and agent container. Docker deployments use host bind mounts; Kubernetes deployments can mount administrator-managed PVCs.

Overview

When configured, mount entries are stored as system-level settings and applied during container creation:

• Persistent containers — mounts are included when the container is created or recreated
• Agent (ephemeral) containers — mounts are included on each Docker run or Kubernetes Job
• Agent tool runtime — read-only file browsing tools inherit these mount settings so shared data can be read from controlled paths
• All mount paths are validated for uniqueness and correctness before saving

Prerequisites

• Administrator role — only admins can manage container mount settings
• Docker host path mounts require Docker to access the configured host path
• Kubernetes PVC mounts require the PVC to exist in the configured runtime namespace and the target subdirectory to be prepared

Access

Navigate to: Admin → Container Mounts (/workspace/admin/container-mounts)

Configuration

Each mount entry has these fields:

Example Mounts

Kubernetes PVC example:

Kubernetes PVC mounts always use mnt, at the same level as global and projects. The main app ensures that directory exists on startup.

How to Configure

1. Go to Admin → Container Mounts
2. Choose the source type, then fill in the Host Path or select a PVC name
3. Docker host path mounts require a Container Path; Kubernetes PVC mounts always use /mnt
4. Toggle Read-only if the mount should not be writable from the container
5. Click Add mount to add additional entries
6. Click Save to apply

When Mounts Take Effect

• New containers — mounts are applied automatically on creation
• Running persistent containers — require a restart to pick up the new mount configuration
• If bind mounts have changed since the container was created, the system will automatically detect this and recreate the container on the next start

Validation Rules

The system enforces the following rules:

• Container paths must be unique across all mount entries
• Container path cannot be / (root)
• Container path cannot overlap with reserved system paths such as /workspace, /app, /etc, /proc, /sys, /dev, /usr, /var, or /tmp
• Host paths must be absolute
• PVC names must be valid Kubernetes resource names
• Kubernetes PVC subPath is fixed to mnt, and the container path is fixed to /mnt
• During main app startup, the system runs a simple mkdir -p mnt against the workspace root; existing files under mnt are preserved
• Duplicate container paths will be rejected with an error

Security Considerations

• Host path mounts use Docker bind mount semantics — the container has direct access to host files
• PVC mounts use Kubernetes persistentVolumeClaim volumes and are mounted into persistent Deployments and ephemeral Jobs
• Use Read-only mounts for data that should not be modified from inside containers
• The system validates that mount paths do not conflict with the container workspace path
• Only administrators can configure mounts — regular users cannot modify mount settings

Troubleshooting

"Container path must be unique"

Two mount entries have the same container path. Remove or change one of them.

"container_path must be an absolute POSIX path"

Container paths must start with / (e.g., /mnt/data, not mnt/data).

Mounts not appearing in container

Restart the persistent container — running containers do not pick up mount changes until they are restarted.

Permission denied accessing mounted files

For host path mounts, ensure the path exists and Docker has access. For PVC mounts, ensure the PVC is bound in the runtime namespace and the stored files are readable by the runtime UID/GID.

Related Docs

• Container Management
• Resource Quotas
• Execution Platform