Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.qoder.com/llms.txt

Use this file to discover all available pages before exploring further.

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

FieldTypeRequiredDescription
idstring—System-generated, prefixed with env_
namestringYesEnvironment name
configobjectYesEnvironment configuration (type, networking, packages)
config.typestringYesContainer type, currently fixed at "cloud"
config.networkingobjectNoNetworking policy; must be an object. Valid values: {"type": "unrestricted" | "limited" | "allowed_hosts"}
config.packagesobjectNoPreinstalled package configuration
statusstring—Environment status: ready
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.
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

​
networking object fields

FieldTypeDescription
networking.typestringPolicy type: unrestricted / limited / allowed_hosts
networking.allow_package_managersbooleanIn limited mode, allow package managers (pip / npm / apt …) outbound traffic
networking.allowed_hostsarrayList of reachable hosts in allowed_hosts mode

​
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 (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_ds456",
  "name": "data-science",
  "config": {
    "type": "cloud",
    "networking": {"type": "unrestricted"},
    "packages": {
      "apt": ["build-essential"],
      "pip": ["pandas", "numpy", "matplotlib", "scikit-learn", "jupyter"]
    }
  },
  "status": "ready",
  "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.

​
Delete an Environment

# Delete a custom Environment
curl -s -X DELETE https://api.qoder.com/api/v1/cloud/environments/env_ds456 \
  -H "Authorization: Bearer $QODER_PAT"
When an environment is still referenced by unarchived sessions, DELETE returns 409 “Environment is in use and cannot be deleted”. You must first archive/delete the referencing sessions, or use POST /environments/{id}/archive for soft-delete (no reference constraint).

​
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 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