Container Management

This page collects the current user-facing container management features: project persistent containers, image and resource settings, fixed mount visibility, and project image builds in dev mode.

What You Can Do Today

• Enable or disable a persistent container environment for a project
• View the current container status, image, container name, and system fixed mounts
• Start, stop, or retry a project container after an error
• Choose a local image before enabling, or enter an image name to pull
• Save CPU, memory, GPU count, GPU driver, and GPU memory settings per project
• In Slurm deployments, choose whether supported project work runs as the user's bound Linux identity
• In dev mode projects, generate Dockerfile drafts, run image builds, inspect logs, and set a successful build as the project image

Persistent Container Environment

Entry: project workspace header Settings -> Persistent data environment

When enabled:

• Conversations in the same project share one container environment
• Agent Read, Bash, Edit, and Write operations prefer to run inside that container
• Python, pip, npm, and similar dependencies installed in the container can be reused across conversations
• The project working directory persists, which makes container-based workflows more stable

Status Meanings

• Running: the container is live and new tool calls can reuse it immediately
• Stopped: the container is currently stopped; when container-backed work is needed again, the system will usually wake it automatically
• Stopping: ResearchX is stopping the container; wait for the next status refresh before clicking again
• Waiting for resources: the container cannot start due to resource quota limits; it will auto-wake when other projects release resources; the status indicator shows an amber alert with bottleneck details
• Error: startup or runtime failed; the owner can retry or re-enable
• Disabled / Not Enabled: the project has not enabled a persistent container yet

Information Shown in Settings

The settings card can show:

• The current project container image
• The current container name
• The list of admin-configured system fixed mounts
• Whether the container is over quota
• The latest error message, if any

Image and Resource Settings

Owners can configure the following in project settings:

• Use local image: pick from images already available on the current machine
• Or pull image by name: type an image reference such as python:3.12-slim
• CPU count: CPU cores for the project container
• Memory (MB): memory limit for the project container
• GPU count: number of GPUs exposed to the project container
• GPU driver: GPU driver type, typically nvidia
• GPU memory (GB): GPU memory metadata

Guidance:

• Leaving CPU or memory empty, or setting 0, means use the default limit
• Leaving GPU count empty, or setting 0, disables GPU for that project container
• These values are saved on the project for future enables or recreations
• If the container is already running, you will usually need to stop and re-enable it, or wait for a rebuild/recreation, before new image and resource settings are fully applied

Run as Bound Linux User

In Slurm deployments where Linux user binding is enabled, project owners can turn on Run as bound Linux user in Persistent data environment settings. When enabled, supported Slurm-backed project work runs as the current member's bound Linux identity and uses workspace permissions prepared for that Linux user.

Requirements:

• An administrator has enabled Linux identity binding for the deployment
• The current user has bound a Linux user from /workspace/profile
• The project is using the Slurm execution platform

How to enable it:

1. Open the project workspace
2. Open Settings from the header
3. In Persistent data environment, select Run as bound Linux user
4. Click Save runtime mode

Notes:

• Only project owners can change this runtime mode
• The option cannot be enabled until a Linux user is bound
• Turning it off returns the project to the deployment's default Slurm runtime identity
• If the project environment has already been prepared, restart or re-enable the environment so the new identity mode is applied consistently

Enable, Start, Stop, and Disable

• Enable
  • Creates and enables the project's persistent container
  • Uses the currently saved image and resource settings
• Start
  • Starts an already-enabled container that is currently stopped
  • Useful when you want to continue with the same environment
• Stop
  • Stops the current container without deleting project workspace files
  • It can be started again later, or auto-woken when needed
  • Docker and Kubernetes backends both try to release resource leases and update project state
• Disable
  • Deletes the project's persistent container
  • Installed dependencies and the container system environment are lost
  • Local project workspace files remain
  • If runtime deletion fails, ResearchX rolls back the enabled state and keeps the error visible

State Consistency and Auto-Repair

A background controller periodically reconciles recorded project container state with the real Docker or Kubernetes runtime state. This prevents stale states such as "UI says running but the container is gone" or "container stopped but resources are still leased" from lingering.

ResearchX automatically handles:

• Mismatches between actual Docker / Kubernetes state and project records
• Lost container state after host or cluster restarts
• Lease cleanup after containers stop, are disabled, or release resources
• Kubernetes Jobs / Pods that have completed while the project still appears running

User guidance:

• If a container briefly shows Stopping, Waiting for resources, or Error, refresh status or wait for the next automatic sync
• If an abnormal state persists, a manager or owner can use Retry, Start, or Disable to clean up the environment
• Admins can stop abnormal project containers from the running-containers table in Resource Quotas

Permission Boundaries

• owner
  • Can Enable and Disable
  • Can edit image and resource settings
  • Can use Retry after an error
• manager
  • Can Start and Stop after the container has been enabled
  • Can view container status and current configuration
• editor / viewer
  • Can view container status
  • Cannot enable, disable, or edit project container configuration

Project Image Builds

Entry: Container Builds inside the project workspace

This feature is for preparing custom images for a project, such as images with preinstalled Python packages, system dependencies, CUDA tooling, or a preferred runtime stack.

Requirements

• The project must be in dev mode
• An administrator must have enabled the system-wide container build feature
• You need project workspace write access, usually editor or above

What You Can Do

• Generate a Dockerfile draft from a natural-language prompt
• Manually edit Dockerfile and .dockerignore
• Validate the draft
• Start a new build
• Review build status and logs
• Cancel an in-progress build
• Delete build records you no longer need
• Rename queued or successful build images

Set as Project Image

After a build succeeds:

• manager and above can click Set as project image
• This saves the built image as the project's container image configuration
• Future enables, recreations, or rebuilds of the persistent project container will prefer that image

Typical Scenarios

Scenario 1: Reuse one Python environment across conversations

1. An owner enables Persistent data environment
2. Install dependencies such as pandas or scanpy in one conversation
3. Reuse those dependencies directly in later conversations in the same project

Scenario 2: Prepare a stable GPU-backed project environment

1. The owner saves GPU count, driver, and memory values in project settings
2. If needed, choose a local image or enter a remote image reference
3. Enable or recreate the container so Agent container-backed work runs in that environment

Scenario 3: Build a custom image for a dev-mode project

1. Switch the project to dev mode
2. Open Container Builds
3. Describe the environment you want and generate a Dockerfile draft
4. Validate and start the build
5. After success, set it as the project image
6. Re-enable or recreate the project container so the new image takes effect

Related Docs

• Project Management
• Agent / Action / Runtime / Visualizer Management
• Container Mounts (Admin)
• Resource Quotas
• Execution Platform
• FAQ
• Troubleshooting and Support