Skip to main content
An Environment defines the container template a Session runs on: its environment type, networking policy, preinstalled dependencies, setup script, and metadata. You can build different Environments for different scenarios: a strictly isolated audit environment, an analytics environment with data-science libraries, or an open-network environment for general development.

​
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.
  • Networking policy - controls outbound network access.
  • 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, an isolated runtime is created from the specified Environment template.

​
Field Reference

FieldTypeRequiredDescription
idstring-System-generated, prefixed with env_
typestring-Always "environment"
namestringYesEnvironment name
descriptionstringNoFree-form description; defaults to ""
configobjectYesEnvironment configuration
config.typestringYesEnvironment type: "cloud" or "self_hosted"
config.networkingobjectNoNetworking policy for cloud environments
config.packagesobjectNoPreinstalled package configuration for cloud environments
config.setup_scriptstringNoShell script run during sandbox preparation (max 64 KB)
metadataobjectNoCustom key/value metadata
archived_atstring|null-Archive time (ISO 8601), null when not archived
created_atstring-Creation timestamp
updated_atstring-Last update timestamp

​
Config Types

config.type can be "cloud" or "self_hosted". For self_hosted, the config must be exactly: 
{"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. For cloud, the config can include networking, packages, and setup_script.

​
Networking Policies

config.networking supports three request modes. All modes require the object form - passing a string shorthand like "unrestricted" returns 400.
ModeValueDescription
Open{"type": "unrestricted"}The container can reach any external address
Limited{"type": "limited", "allow_package_managers": true}Only known-safe public services and package managers are reachable
Allowlist{"type": "allowed_hosts", "allowed_hosts": [...]}Only the listed hosts are reachable
Cloud Environment responses include these networking fields. Omitted fields are returned with defaults.
FieldTypeDefault
typestringlimited
allowed_hostsarray of string[]
allow_package_managersbooleanfalse
allow_mcp_serversbooleanfalse

​
Open

{
  "config": {
    "type": "cloud",
    "networking": {"type": "unrestricted"}
  }
}
Use this for general development tasks that need to download dependencies or call external APIs.

​
Limited

{
  "config": {
    "type": "cloud",
    "networking": {
      "type": "limited",
      "allow_package_managers": true
    }
  }
}
Use this when you don’t need arbitrary outbound traffic but still want package managers to fetch dependencies.

​
Allowlist

{
  "config": {
    "type": "cloud",
    "networking": {
      "type": "allowed_hosts",
      "allowed_hosts": [
        "api.github.com",
        "registry.npmjs.org",
        "pypi.org"
      ]
    }
  }
}
Use this for security-sensitive workloads where you must whitelist exactly which external services are reachable.

​
Preinstalled Packages

Use config.packages to specify dependencies installed 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 managerFieldDescription
aptpackages.aptDebian/Ubuntu system packages
pippackages.pipPython packages
npmpackages.npmNode.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.
ConstraintValue
Typestring
Max length64 KB
Interpreter/bin/bash -lc
Timeout10 minutes
When it runsSandbox preparation, after packages installation
# Create an environment that clones the project and warms its dependency cache
curl -s -X POST https://api.qoder.com/api/v1/cloud/environments \
  -H "Authorization: Bearer $QODER_PAT" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "node-with-init",
    "config": {
      "type": "cloud",
      "networking": {"type": "unrestricted"},
      "packages": {
        "npm": ["pnpm@9"]
      },
      "setup_script": "set -euo pipefail\n[ -d /workspace/.git ] || git clone https://github.com/me/repo /workspace\ncd /workspace && 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.

​
Create an Environment

# Create a data-science Environment
curl -s -X POST https://api.qoder.com/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 .
A successful call returns 200 OK: 
{
  "id": "env_019e44eb66bb748cabcd1489f6fa4428",
  "type": "environment",
  "name": "data-science",
  "description": "",
  "config": {
    "type": "cloud",
    "networking": {
      "type": "unrestricted",
      "allowed_hosts": [],
      "allow_package_managers": false,
      "allow_mcp_servers": false
    },
    "packages": {
      "type": "packages",
      "apt": ["build-essential"],
      "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"
}

​
Create a Restricted-Network Environment

# An environment that can only reach internal APIs
curl -s -X POST https://api.qoder.com/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 .

​
Read Environments

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

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

​
Update an Environment

# Add new dependencies to an existing Environment
curl -s -X POST https://api.qoder.com/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 to Sessions created after the update.

​
Choosing an Environment

ScenarioRecommended configuration
General developmentdefault Environment, no extra setup
Data analysisPreinstall pandas/numpy with open networking
Security auditsAllowlist networking with minimal dependencies
Frontend developmentPreinstall the Node.js toolchain with open access to the npm registry
CI/CD integrationPreinstall git/docker CLI with allowlist networking

​
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: An incorrect networking setting is breaking my Agent. What should I do? A: Create a new Environment (or update the existing one) with corrected networking, then start a new Session. 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.

​
Next steps

Start a session

Combine an Agent and an Environment to start running tasks.

Agent setup

Review Agent configuration.