An environment defines the container template for a session — the operating system, network policy, and pre-installed packages. Create tailored environments for different use cases, such as security audits, data analysis, or general-purpose development.
The new Qoder CN documentation site is now available. Content on this site may not reflect the latest product features and changes. Visit docs.qoder.cn for the latest product documentation.
What is an environment
An environment serves as the infrastructure layer for a session:
-
Container type — Currently supports
cloud(a cloud-hosted container). -
Network policy — Controls the container's outbound network access.
-
Packages — Pre-installs system, Python, and Node.js packages.
Each time a session starts, it creates an isolated instance based on the specified environment template.
Fields
|
Parameter |
Type |
Required |
Description |
|
|
string |
— |
System-generated ID with the |
|
|
string |
— |
Fixed to |
|
|
string |
Yes |
Name of the environment. |
|
|
string |
No |
Optional description. Defaults to |
|
|
object |
Yes |
Environment configuration (type, networking, packages). |
|
|
string |
Yes |
Container type. Currently fixed to |
|
|
object |
No |
Network policy object. The |
|
|
object |
No |
Configuration for pre-installed packages. |
|
|
string |
— |
Environment status. Always |
|
|
boolean |
— |
Indicates whether the environment is archived. Defaults to |
|
|
string|null |
— |
Archival timestamp (ISO 8601). |
|
|
string |
— |
Creation timestamp (ISO 8601). |
|
|
string |
— |
Last update timestamp (ISO 8601). |
Network policy
The config.networking field supports three modes. All modes must use the object form; string shorthands like "unrestricted" are unsupported and will cause a 400 error.
|
Mode |
Value |
Description |
|
Unrestricted |
|
The container can access any external address. |
|
Limited |
|
Allows access only to known-safe public services and package managers. |
|
Allowlist |
|
Restricts access to a specified list of hostnames. |
networking fields
|
Parameter |
Type |
Description |
|
|
string |
Network policy type: |
|
|
boolean |
Whether to allow package manager access (pip, npm, and apt) in |
|
|
array |
A list of allowed hostnames in |
Unrestricted mode
{
"config": {
"type": "cloud",
"networking": {"type": "unrestricted"}
}
}
Use this for general development tasks that need to download dependencies or access external APIs.
Limited mode
{
"config": {
"type": "cloud",
"networking": {
"type": "limited",
"allow_package_managers": true
}
}
}
Use this for tasks that do not need arbitrary internet access but still require pulling dependencies via package managers.
Allowlist mode
{
"config": {
"type": "cloud",
"networking": {
"type": "allowed_hosts",
"allowed_hosts": [
"api.github.com",
"registry.npmjs.org",
"pypi.org"
]
}
}
}
Use this for high-security or compliance scenarios where you must precisely control which external services are reachable.
Preinstalled packages
Use config.packages to specify packages to preinstall when the container starts:
{
"config": {
"type": "cloud",
"networking": {"type": "unrestricted"},
"packages": {
"apt": ["git", "build-essential", "libssl-dev"],
"pip": ["pandas", "numpy", "scikit-learn"],
"npm": ["typescript", "eslint", "prettier"]
}
}
}
|
Package manager |
Parameter |
Description |
|
apt |
|
Debian/Ubuntu system packages. |
|
pip |
|
Python packages. |
|
npm |
|
Node.js packages (installed globally). |
Preinstalling packages increases environment initialization time. Only add what you need; install other packages on demand during the session.
Create an environment
# Create a dedicated data science environment
curl -s -X POST https://api.qoder.com.cn/api/v1/cloud/environments \
-H "Authorization: Bearer $QODER_PAT" \
-H "Content-Type: application/json" \
-d '{
"name": "data-science",
"config": {
"type": "cloud",
"networking": {"type": "unrestricted"},
"packages": {
"apt": ["build-essential"],
"pip": ["pandas", "numpy", "matplotlib", "scikit-learn", "jupyter"]
}
}
}' | jq .
On success, the API returns a 201 Created status:
{
"id": "env_019e44eb66bb748cabcd1489f6fa4428",
"type": "environment",
"name": "data-science",
"description": "",
"config": {
"type": "cloud",
"networking": {"type": "unrestricted"},
"packages": {
"apt": ["build-essential"],
"pip": ["pandas", "numpy", "matplotlib", "scikit-learn", "jupyter"]
}
},
"status": "ready",
"archived": false,
"archived_at": null,
"created_at": "2026-05-18T10:00:00Z",
"updated_at": "2026-05-18T10:00:00Z"
}
Create a secure environment
# Create a secure environment that only allows access to internal APIs
curl -s -X POST https://api.qoder.com.cn/api/v1/cloud/environments \
-H "Authorization: Bearer $QODER_PAT" \
-H "Content-Type: application/json" \
-d '{
"name": "secure-internal",
"config": {
"type": "cloud",
"networking": {
"type": "allowed_hosts",
"allowed_hosts": ["internal-api.mycompany.com", "git.mycompany.com"]
},
"packages": {
"apt": ["git", "curl"]
}
}
}' | jq .
Get environments
# List all environments
curl -s https://api.qoder.com.cn/api/v1/cloud/environments \
-H "Authorization: Bearer $QODER_PAT"
# Get details for a single environment
curl -s https://api.qoder.com.cn/api/v1/cloud/environments/env_ds456 \
-H "Authorization: Bearer $QODER_PAT"
Update an environment
# Add new packages to an existing environment
curl -s -X PUT https://api.qoder.com.cn/api/v1/cloud/environments/env_ds456 \
-H "Authorization: Bearer $QODER_PAT" \
-H "Content-Type: application/json" \
-d '{
"name": "data-science",
"config": {
"type": "cloud",
"networking": {"type": "unrestricted"},
"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 only to sessions created after the update.
Delete an environment
# Delete a custom environment
curl -s -X DELETE https://api.qoder.com.cn/api/v1/cloud/environments/env_ds456 \
-H "Authorization: Bearer $QODER_PAT"
If an environment is in use by an active session, the DELETE request fails with a 409 Conflict error: "Environment is in use and cannot be deleted". Archive or delete the associated sessions first, or use POST /environments/{id}/archive to soft-delete the environment instead.
Recommended configurations
|
Scenario |
Recommended configuration |
|
General development |
Use the |
|
Data analysis |
Preinstall pandas/numpy; use unrestricted networking. |
|
Security audit |
Use an allowlist for the network and install minimal packages. |
|
Frontend development |
Preinstall Node.js ecosystem tools; allow access to the npm registry. |
|
CI/CD integration |
Preinstall the Git and Docker CLIs; use allowlist mode. |
FAQ
Q: How long do I have to wait to use an environment after creating it?A: After an environment is created, its status is immediately set to ready, and you can use it to create a session right away. The actual container initialization, which includes installing dependencies, occurs when the session starts.Q: Can I specify the versions of pre-installed packages?A: Yes, you can specify versions for pip and npm packages, such as "pandas==2.1.0" or "typescript@5.0.0". apt packages use the default version from the system's repository.Q: What should I do if the Agent fails to run because of an incorrect networking configuration?A: Create a new environment or update the existing one, modify the network policy, and then restart the session.Q: What is the maximum number of environments that an account can create?A: There is no hard limit. However, we recommend that you create environments based on your actual needs to prevent management issues. We suggest using naming conventions to organize them.