Skip to main content
Configure agent environment

Container Reference

Container types, network policies, and preinstalled packages.

This page describes the container available to Agents in managed cloud Environments. For self_hosted Environments, the operating system, tools, and resources are determined by the self-hosted runtime. In a managed Environment, you can rely on the following behavior:
  • Agent tools start in /data by default.
  • config.packages supports apt, pip, and npm dependencies.
  • config.setup_script runs after package installation.
  • The container filesystem is an ephemeral workspace; durable outputs must be stored externally.

Runtime and operating system

The standard image for managed Environments is currently based on Ubuntu 22.04 LTS. CPU architecture, kernel, and container engine can vary by runtime environment. Inspect the actual environment inside a Session: 
cat /etc/os-release
uname -m
uname -r
If you use native binaries, detect the architecture inside the Session or provide builds for every required architecture.

Tools in the current standard image

The current standard image includes common system tools such as git, curl, wget, jq, vim, ssh, make, cmake, gcc, ripgrep, tar, and unzip. It also includes these major language runtimes:
RuntimeCurrent major version
Python3.12
Node.js20
Go1.22
Java21
Ruby3.3
PHP8.3
Ruststable
Preinstalled tools and patch versions can change as the image is upgraded. If a task needs an exact version, pin it in the Environment and inspect it in the Session: 
python --version
node --version
go version
java -version
ruby --version
php --version
rustc --version

Working directory

The default working directory for Agent tools is: 
/data
In managed Environments, WORK_DIR is /data, and tools such as Bash start in /data when no directory is provided. Put repositories and working files under a directory such as /data/workspace/. For uploaded files and repository resources, use each resource's mount_path to select the mount location; see Files and Mounts.

Installing extra software

Managed cloud Environments support these config.packages fields:
FieldInstallation behavior
aptSystem packages through apt-get install
pipPython packages through pip install
npmNode.js packages through npm install -g
{
  "config": {
    "type": "cloud",
    "packages": {
      "apt": ["postgresql-client", "redis-tools"],
      "pip": ["pandas==2.2.3"],
      "npm": ["typescript@5.8.3"]
    }
  }
}
For initialization that cannot be expressed with packages, use config.setup_script. It runs after package installation through /bin/bash -lc, with /data as its working directory, a maximum size of 64 KiB, and a 10-minute timeout.

Resources and timeouts

Available CPU, memory, disk, and execution timeouts depend on the runtime environment and service configuration. Do not make a task depend on fixed resource values. If a task has minimum resource requirements, validate them in the target environment first. Processes can be terminated or writes can fail when memory or disk is exhausted. Long-running tasks must also account for per-tool and per-turn timeouts.

File persistence

  • Files normally remain between turns while the same runtime instance is retained.
  • The container's ephemeral storage may be reclaimed after 24 consecutive hours of inactivity.
  • When a Session is resumed after reclamation, the platform reinitializes the container and prepares the Environment and mounted resources again as needed. Files that were not saved to external storage may be lost.
  • After a Session is archived or ends, do not rely on its container files remaining available.
Treat the container filesystem as an ephemeral workspace. Store durable outputs through the Files API, a Git repository, or another external store. Commit and push important code changes promptly.

Execution user and environment variables

The execution user and the values of HOME, USER, SHELL, and LANG can vary by runtime environment or custom image. Do not make scripts depend on a specific UID or assume that system directories are always writable. Inspect the current Session when needed: 
id
whoami
printf 'HOME=%s\nUSER=%s\nSHELL=%s\nLANG=%s\nWORK_DIR=%s\n' \
  "$HOME" "${USER:-}" "${SHELL:-}" "${LANG:-}" "${WORK_DIR:-}"
Session environment_variables and environment-variable credentials from linked Vaults are injected for tool calls. Never print secrets in logs or task output.