Cloud environments

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.

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
`id`	string	—	System-generated ID with the `env_` prefix.
`type`	string	—	Fixed to `"environment"`.
`name`	string	Yes	Name of the environment.
`description`	string	No	Optional description. Defaults to `""`.
`config`	object	Yes	Environment configuration (type, networking, packages).
`config.type`	string	Yes	Container type. Currently fixed to `"cloud"`.
`config.networking`	object	No	Network policy object. The `type` property must be `"unrestricted"`, `"limited"`, or `"allowed_hosts"`.
`config.packages`	object	No	Configuration for pre-installed packages.
`status`	string	—	Environment status. Always `ready`.
`archived`	boolean	—	Indicates whether the environment is archived. Defaults to `false`.
`archived_at`	string\|null	—	Archival timestamp (ISO 8601). `null` if not archived.
`created_at`	string	—	Creation timestamp (ISO 8601).
`updated_at`	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	`{"type": "unrestricted"}`	The container can access any external address.
Limited	`{"type": "limited", "allow_package_managers": true}`	Allows access only to known-safe public services and package managers.
Allowlist	`{"type": "allowed_hosts", "allowed_hosts": [...]}`	Restricts access to a specified list of hostnames.

`networking` fields

Parameter	Type	Description
`networking.type`	string	Network policy type: `unrestricted`, `limited`, or `allowed_hosts`.
`networking.allow_package_managers`	boolean	Whether to allow package manager access (pip, npm, and apt) in `limited` mode.
`networking.allowed_hosts`	array	A list of allowed hostnames in `allowed_hosts` mode.

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	`packages.apt`	Debian/Ubuntu system packages.
pip	`packages.pip`	Python packages.
npm	`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 `default` environment; no extra configuration needed.
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.

Next steps

Start a session — Use an Agent and an environment to start a task.
Define an Agent — Review the Agent configuration.

​What is an environment

​Fields

​Network policy

​networking fields

​Unrestricted mode

​Limited mode

​Allowlist mode

​Preinstalled packages

​Create an environment

​Create a secure environment

​Get environments

​Update an environment

​Delete an environment

​Recommended configurations

​FAQ

​Next steps