An Environment defines the container template a Session runs on — its operating system, networking policy, and preinstalled dependencies. 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:
Container type — currently cloud (managed cloud container).Networking policy — controls outbound network access.Packages — preinstalled system, Python, and Node.js dependencies.
When a Session starts, an isolated runtime is created from the specified Environment template.
Field reference Field Type Required Description idstring — System-generated, prefixed with env_ typestring — Always "environment" namestring Yes Environment name descriptionstring No Free-form description; defaults to "" configobject Yes Environment configuration (type, networking, packages) config.typestring Yes Container type, currently fixed at "cloud" config.networkingobject No Networking policy; must be an object. Valid values: {"type": "unrestricted" | "limited" | "allowed_hosts"} config.packagesobject No Preinstalled package configuration statusstring — Environment status: ready archivedboolean — Whether archived (default false) archived_atstring|null — Archive time (ISO 8601), null when not archived created_atstring — Creation timestamp updated_atstring — Last update timestamp
Networking policies config.networking supports three modes. All modes require the object form — passing a string shorthand like "unrestricted" returns 400.Mode Value Description 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
networking object fieldsField Type Description networking.typestring Policy type: unrestricted / limited / allowed_hosts networking.allow_package_managersboolean In limited mode, allow package managers (pip / npm / apt …) outbound traffic networking.allowed_hostsarray List of reachable hosts in allowed_hosts mode
{ "config" : { "type" : "cloud" , "networking" : { "type" : "unrestricted" } } }
Use this for general development tasks that need to download dependencies or call external APIs. { "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. { "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 manager Field Description apt packages.aptDebian/Ubuntu system packages pip packages.pipPython packages npm packages.npmNode.js packages (installed globally)
Preinstalled packages add to environment startup time. Only include packages you really need; install the rest on demand within the Session.
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 201 Created :
{ "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 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 PUT 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 Scenario Recommended configuration General development default Environment, no extra setupData analysis Preinstall pandas/numpy with open networking Security audits Allowlist networking with minimal dependencies Frontend development Preinstall the Node.js toolchain with open access to the npm registry CI/CD integration Preinstall 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 goes straight to ready and 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.
