Cloud environments

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

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.

networking fields

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"]
    }
  }
}

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

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.