Cloud environments

An Environment defines the runtime used by a Session, including its environment type, preinstalled dependencies, setup script, and metadata. You can use the default managed Environment, create an Environment with tools for a specific task, or connect a self-hosted runtime.

What an Environment Is

An Environment is the infrastructure layer beneath a Session:

Environment type - cloud for managed cloud containers, or self_hosted for self-hosted execution.
Packages - preinstalled system, Python, and Node.js dependencies.
Setup script - a user shell script run after package installation during container preparation.

When a Session starts, a dedicated runtime instance is created from the specified Environment template.

Field Reference

Field	Type	Required	Description
`id`	string	-	System-generated, prefixed with `env_`
`type`	string	-	Always `"environment"`
`name`	string	Yes	Environment name
`description`	string	No	Free-form description; defaults to `""`
`config`	object	No	Environment configuration; omission defaults to `{"type":"cloud"}`
`config.type`	string	Yes when config is present	Environment type: `"cloud"` or `"self_hosted"`
`config.packages`	object	No	Preinstalled package configuration for `cloud` environments
`config.setup_script`	string	No	Shell script run during sandbox preparation (max 64 KB)
`config.storage`	object	No	Mounts of your own OSS buckets; `cloud` Environments only
`metadata`	object	No	Custom key/value metadata
`archived_at`	string\|null	-	Archive time (ISO 8601), `null` when not archived
`created_at`	string	-	Creation timestamp
`updated_at`	string	-	Last update timestamp

Config Types

config.type can be "cloud" or "self_hosted". For self_hosted, the config can contain the type and an optional setup_script:

{"type": "self_hosted"}

Self-hosted Environments do not launch a managed cloud container. External workers use the Work API to poll, acknowledge, heartbeat, and stop Session work for that Environment. A self_hosted config supports only type and an optional setup_script. For cloud, the config can include packages, setup_script, and storage.

Preinstalled Packages

Use config.packages to specify dependencies installed when the container starts:

{
  "config": {
    "type": "cloud",
    "packages": {
      "apt": ["git", "build-essential", "libssl-dev"],
      "pip": ["pandas", "numpy", "scikit-learn"],
      "npm": ["typescript", "eslint", "prettier"]
    }
  }
}

Package manager	Field	Description
apt	`packages.apt`	Debian/Ubuntu system packages
pip	`packages.pip`	Python packages
npm	`packages.npm`	Node.js packages

Preinstalled packages add to environment startup time. Only include packages you really need; install the rest on demand within the Session.

Setup Script

config.setup_script is a shell script executed during sandbox preparation, after packages are installed. It runs through /bin/bash -lc. Use it for initialization steps that cannot be expressed as packages - for example, cloning a repository, writing config files, or warming caches.

Constraint	Value
Type	string
Max length	64 KB
Interpreter	`/bin/bash -lc`
Timeout	10 minutes
When it runs	Sandbox preparation, after `packages` installation

# Create an environment that clones the project and warms its dependency cache
curl -s -X POST https://api.qoder.com.cn/api/v1/cloud/environments \
  -H "Authorization: Bearer $QODER_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "node-with-init",
    "config": {
      "type": "cloud",
      "packages": {
        "npm": ["pnpm@9"]
      },
      "setup_script": "set -euo pipefail\n[ -d /data/workspace/repo/.git ] || git clone https://github.com/me/repo /data/workspace/repo\ncd /data/workspace/repo && pnpm install --frozen-lockfile"
    }
  }' | jq .

On success a completion marker is written inside the sandbox so the script does not run twice in the same sandbox; when the sandbox is recreated, the script runs again. A non-zero exit aborts session startup, and the error response includes the exit code and a stderr excerpt.

Mount Your Own OSS Buckets (Beta)

config.storage.buckets[] mounts your Alibaba Cloud OSS buckets at /mnt/buckets/<name> in the sandbox:

cloud Environments only, at most 8 buckets per Environment.
Read-only and read-write mounts; credentials can be a RAM role (recommended) or an AccessKey.
Reads download from OSS through a presigned URL; writes upload directly with multipart upload (writes smaller than 1 MiB are relayed by Qoder).
Saving the Environment probes each new or changed bucket as the saving user and reports the reason for a refusal.

{
  "type": "cloud",
  "storage": {
    "buckets": [
      {
        "name": "datasets",
        "provider": "aliyun-oss",
        "region": "cn-hangzhou",
        "bucket": "my-bucket",
        "prefix": "team/data/",
        "access": "read_only",
        "credential": {"type": "ram_role", "role_arn": "acs:ram::1234567890123456:role/qoder-oss-mount"}
      }
    ]
  }
}

Requests must carry x-qoder-beta: oss-bucket-2026-09-23. For the full field reference, bucket authorization (tags and access list), permissions, and sandbox behavior, see Mount your own OSS buckets (Beta).

Create an Environment

# Create a data-science Environment
curl -s -X POST https://api.qoder.com.cn/api/v1/cloud/environments \
  -H "Authorization: Bearer $QODER_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "data-science",
    "config": {
      "type": "cloud",
      "packages": {
        "apt": ["build-essential"],
        "pip": ["pandas", "numpy", "matplotlib", "scikit-learn", "jupyter"]
      }
    }
  }' | jq .

A successful call returns 200 OK:

{
  "id": "env_019e44eb66bb748cabcd1489f6fa4428",
  "type": "environment",
  "name": "data-science",
  "description": "",
  "config": {
    "type": "cloud",
    "packages": {
      "type": "packages",
      "apt": ["build-essential"],
      "cargo": [],
      "gem": [],
      "go": [],
      "npm": [],
      "pip": ["pandas", "numpy", "matplotlib", "scikit-learn", "jupyter"]
    }
  },
  "metadata": {},
  "archived_at": null,
  "created_at": "2026-05-18T10:00:00Z",
  "updated_at": "2026-05-18T10:00:00Z"
}

Read Environments

# List all Environments
curl -s https://api.qoder.com.cn/api/v1/cloud/environments \
  -H "Authorization: Bearer $QODER_ACCESS_TOKEN"

# Get a single Environment
curl -s https://api.qoder.com.cn/api/v1/cloud/environments/env_ds456 \
  -H "Authorization: Bearer $QODER_ACCESS_TOKEN"

Update an Environment

# Add new dependencies to an existing Environment
curl -s -X POST https://api.qoder.com.cn/api/v1/cloud/environments/env_ds456 \
  -H "Authorization: Bearer $QODER_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "data-science",
    "config": {
      "type": "cloud",
      "packages": {
        "apt": ["build-essential", "libpq-dev"],
        "pip": ["pandas", "numpy", "matplotlib", "scikit-learn", "jupyter", "sqlalchemy"]
      }
    }
  }' | jq .

Updating an Environment does not affect running Sessions. The new configuration applies to Sessions created after the update.

Choosing an Environment

Scenario	Recommended configuration
General development	`default` Environment, no extra setup
Data analysis	Preinstall pandas/numpy and verify dependency-registry connectivity
Frontend development	Preinstall the Node.js toolchain and verify npm-registry connectivity
CI/CD integration	Preinstall the required CLIs and verify dependency connectivity in the target runtime

FAQ

Q: How long do I have to wait after creating an Environment before I can use it? A: A new Environment is immediately usable. The actual container provisioning, including dependency installation, happens when a Session starts. Q: Can I pin package versions? A: pip and npm packages support pinning, such as "pandas==2.1.0" or "typescript@5.0.0". apt packages use the default version from the system repository. Q: How many Environments can I create per account? A: There is no hard limit. Create only what you need and use a naming convention to keep things organized.

Cloud environments

What an Environment Is

Field Reference

Config Types

Preinstalled Packages

Setup Script

Mount Your Own OSS Buckets (Beta)

Create an Environment

Read Environments

Update an Environment

Choosing an Environment

FAQ

Next steps

Start a session

Agent setup

​What an Environment Is

​Field Reference

​Config Types

​Preinstalled Packages

​Setup Script

​Mount Your Own OSS Buckets (Beta)

​Create an Environment

​Read Environments

​Update an Environment

​Choosing an Environment

​FAQ

​Next steps

Start a session

Agent setup

What an Environment Is

Field Reference

Config Types

Preinstalled Packages

Setup Script

Mount Your Own OSS Buckets (Beta)

Create an Environment

Read Environments

Update an Environment

Choosing an Environment

FAQ

Next steps