Environments API

Environments are isolated execution contexts for agent operations. Each environment has its own workspace, runtime configurations, packages, environment variables, and MCP servers.

Quick Start with SDK

TypeScript SDK


import { ComputerAgentsClient } from 'computer-agents';
 
const client = new ComputerAgentsClient({ apiKey: process.env.API_KEY });
 
// Get or create default environment
const env = await client.environments.getDefault();
 
// Update runtimes
await client.environments.setRuntimes(env.id, {
  python: '3.12',
  nodejs: '22'
});
 
// Install packages
await client.environments.installPackages(env.id, 'python', ['pandas', 'numpy']);
 
// Trigger build
await client.environments.triggerBuild(env.id);

The Environment Object


{
  "id": "env_kJDvlIZ0mXZI0JrqbHj25",
  "userId": "user_abc123",
  "name": "production",
  "description": "Production environment for data processing",
  "baseImage": null,
  "dockerfileExtensions": "RUN pip install pandas numpy",
  "runtimes": {
    "python": "3.12",
    "nodejs": "20"
  },
  "packages": {
    "system": ["ffmpeg", "imagemagick"],
    "python": ["pandas", "numpy"],
    "node": ["typescript", "tsx"]
  },
  "environmentVariables": [
    { "key": "NODE_ENV", "value": "production" }
  ],
  "secrets": [],
  "setupScripts": [],
  "mcpServers": [],
  "documentation": [],
  "internetAccess": true,
  "buildStatus": "ready",
  "buildHash": "abc123def456",
  "buildError": null,
  "buildLogs": null,
  "lastBuildAt": "2025-01-15T14:22:00.000Z",
  "imageTag": "env-production:abc123def456",
  "isDefault": false,
  "isActive": true,
  "createdAt": "2025-01-15T10:30:00.000Z",
  "updatedAt": "2025-01-15T14:22:00.000Z"
}

Core Attributes

Attribute	Type	Description
`id`	string	Unique identifier (`env_*`)
`userId`	string	Owner user ID
`name`	string	Human-readable name
`description`	string	Optional description
`isDefault`	boolean	Whether this is the user’s default environment
`isActive`	boolean	Whether the environment is active

Runtime & Package Configuration

Attribute	Type	Description
`runtimes`	object	Runtime version configuration (python, nodejs, go, etc.)
`packages`	object	Installed packages by type (system, python, node)
`dockerfileExtensions`	string	Additional Dockerfile instructions
`baseImage`	string	Custom base image (default: testbase-base)

Build Status

Attribute	Type	Description
`buildStatus`	string	`pending`, `building`, `ready`, `failed`
`buildHash`	string	Configuration hash for cache invalidation
`buildError`	string	Error message if build failed
`buildLogs`	string	Build output logs
`lastBuildAt`	string	ISO 8601 timestamp of last build
`imageTag`	string	Built Docker image tag

Build Status Values

Status	Description
`pending`	Environment created but not yet built
`building`	Docker image is being built
`ready`	Build complete, ready for use
`failed`	Build failed (check buildError)

List Environments


GET /environments

Query Parameters

Parameter	Type	Default	Description
`isActive`	boolean	`true`	Filter by active status
`isDefault`	boolean	-	Filter by default status
`limit`	number	50	Max results (1-100)
`offset`	number	0	Pagination offset

Example

cURL


curl https://api.computer-agents.com/environments \
  -H "Authorization: Bearer $API_KEY"

Response


{
  "object": "list",
  "data": [
    {
      "id": "env_kJDvlIZ0mXZI0JrqbHj25",
      "name": "production",
      "buildStatus": "ready",
      "isDefault": false,
      "createdAt": "2025-01-15T10:30:00.000Z"
    }
  ],
  "has_more": false,
  "total_count": 1
}

Get Default Environment


GET /environments/default

Returns the user’s default environment, creating one if it doesn’t exist.

Example


curl https://api.computer-agents.com/environments/default \
  -H "Authorization: Bearer $API_KEY"

Create Environment


POST /environments

Request Body

Parameter	Type	Required	Description
`name`	string	Yes	Environment name
`description`	string	No	Environment description
`runtimes`	object	No	Runtime versions
`packages`	object	No	Packages to install
`dockerfileExtensions`	string	No	Custom Dockerfile instructions
`environmentVariables`	array	No	Environment variables
`mcpServers`	array	No	MCP server configurations
`isDefault`	boolean	No	Set as default environment

Example


curl -X POST https://api.computer-agents.com/environments \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "data-science",
    "description": "Environment for data science tasks",
    "runtimes": {
      "python": "3.12"
    },
    "packages": {
      "system": ["ffmpeg"],
      "python": ["pandas", "numpy", "matplotlib"]
    }
  }'

Get Environment


GET /environments/:environmentId

Example


curl https://api.computer-agents.com/environments/env_xyz789 \
  -H "Authorization: Bearer $API_KEY"

Update Environment


PATCH /environments/:environmentId

Request Body

Parameter	Type	Description
`name`	string	New environment name
`description`	string	New description
`runtimes`	object	Updated runtime versions
`packages`	object	Updated packages
`dockerfileExtensions`	string	Updated Dockerfile extensions
`isDefault`	boolean	Set as default

Delete Environment


DELETE /environments/:environmentId

Query Parameters

Parameter	Type	Default	Description
`hard`	boolean	`false`	If `true`, permanently deletes the environment

By default, this soft-deletes the environment. Use ?hard=true for permanent deletion.

Example


# Soft delete (can be restored)
curl -X DELETE https://api.computer-agents.com/environments/env_xyz789 \
  -H "Authorization: Bearer $API_KEY"
 
# Hard delete (permanent)
curl -X DELETE "https://api.computer-agents.com/environments/env_xyz789?hard=true" \
  -H "Authorization: Bearer $API_KEY"

Set Default Environment


POST /environments/:environmentId/set-default

Sets the specified environment as the user’s default. The previous default (if any) is unset.

Example


curl -X POST https://api.computer-agents.com/environments/env_xyz789/set-default \
  -H "Authorization: Bearer $API_KEY"

Response


{
  "environment": {
    "id": "env_xyz789",
    "isDefault": true,
    ...
  }
}

Runtime Management

Manage language runtime versions for your environment.

List Available Runtimes


GET /environments/runtimes/available

Returns all supported runtime versions.

Example


curl https://api.computer-agents.com/environments/runtimes/available \
  -H "Authorization: Bearer $API_KEY"

Response


{
  "runtimes": {
    "python": ["3.9", "3.10", "3.11", "3.12", "3.13"],
    "nodejs": ["18", "20", "22"],
    "go": ["1.20", "1.21", "1.22", "1.23"],
    "php": ["8.1", "8.2", "8.3"],
    "java": ["11", "17", "21"],
    "ruby": ["3.1", "3.2", "3.3"],
    "rust": ["stable", "1.75", "1.76", "1.77"]
  }
}

Get Environment Runtimes


GET /environments/:environmentId/runtimes

Get current runtime versions for an environment.

Example


curl https://api.computer-agents.com/environments/env_xyz789/runtimes \
  -H "Authorization: Bearer $API_KEY"

Response


{
  "runtimes": {
    "python": "3.12",
    "nodejs": "20"
  }
}

Update Environment Runtimes


PUT /environments/:environmentId/runtimes

Set runtime versions for an environment. This triggers a rebuild.

Request Body


{
  "runtimes": {
    "python": "3.12",
    "nodejs": "20",
    "go": "1.22"
  }
}

Example


curl -X PUT https://api.computer-agents.com/environments/env_xyz789/runtimes \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"runtimes": {"python": "3.12", "nodejs": "20"}}'

Package Management

Install, list, and uninstall packages in your environment.

List Packages


GET /environments/:environmentId/packages

Example


curl https://api.computer-agents.com/environments/env_xyz789/packages \
  -H "Authorization: Bearer $API_KEY"

Response


{
  "packages": {
    "system": ["ffmpeg", "imagemagick"],
    "python": ["pandas", "numpy"],
    "node": ["typescript"]
  }
}

Install Packages


POST /environments/:environmentId/packages

Request Body

Parameter	Type	Required	Description
`type`	string	Yes	`system`, `python`, or `node`
`packages`	array	Yes	Package names to install

Example


curl -X POST https://api.computer-agents.com/environments/env_xyz789/packages \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"type": "python", "packages": ["requests", "beautifulsoup4"]}'

Response


{
  "environment": { ... },
  "installed": ["requests", "beautifulsoup4"]
}

Uninstall Package


DELETE /environments/:environmentId/packages/:type/:name

Parameters

Parameter	Type	Description
`type`	string	`system`, `python`, or `node`
`name`	string	Package name to uninstall

Example


curl -X DELETE https://api.computer-agents.com/environments/env_xyz789/packages/python/requests \
  -H "Authorization: Bearer $API_KEY"

Dockerfile Management

Customize the Docker image for your environment.

Get Dockerfile


GET /environments/:environmentId/dockerfile

Returns the base image, custom extensions, and effective Dockerfile.

Example


curl https://api.computer-agents.com/environments/env_xyz789/dockerfile \
  -H "Authorization: Bearer $API_KEY"

Response


{
  "baseImage": "gcr.io/firechatbot-a9654/testbase-base:latest",
  "dockerfileExtensions": "RUN pip install custom-package",
  "effectiveDockerfile": "FROM gcr.io/firechatbot-a9654/testbase-base:latest\nWORKDIR /workspace\nENV CODEX_HOME=/workspace/.codex\n# Python 3.12\nRUN pyenv install 3.12 && pyenv global 3.12\n..."
}

The effectiveDockerfile field shows the complete generated Dockerfile including base image, runtime installations, packages, user extensions, and setup scripts.

Update Dockerfile Extensions


PUT /environments/:environmentId/dockerfile

Request Body


{
  "dockerfileExtensions": "RUN apt-get update && apt-get install -y custom-tool\nRUN pip install custom-package"
}

Dockerfile extensions are added after runtime and package installation but before the entrypoint.

Example


curl -X PUT https://api.computer-agents.com/environments/env_xyz789/dockerfile \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"dockerfileExtensions": "RUN pip install custom-package"}'

Validate Dockerfile


POST /environments/:environmentId/dockerfile/validate

Validates Dockerfile syntax without building.

Request Body


{
  "dockerfileExtensions": "RUN pip install package"
}

Response


{
  "valid": true,
  "warnings": [],
  "effectiveDockerfile": "..."
}

Build Management

Build and manage Docker images for your environment.

Trigger Build


POST /environments/:environmentId/build

Triggers an asynchronous build of the environment image.

Query Parameters

Parameter	Type	Default	Description
`force`	boolean	`false`	Force rebuild even if up to date

Example


curl -X POST https://api.computer-agents.com/environments/env_xyz789/build \
  -H "Authorization: Bearer $API_KEY"

Response


{
  "message": "Build started",
  "environmentId": "env_xyz789",
  "buildStatus": "building"
}

Get Build Status


GET /environments/:environmentId/build/status

Example


curl https://api.computer-agents.com/environments/env_xyz789/build/status \
  -H "Authorization: Bearer $API_KEY"

Response


{
  "buildStatus": "ready",
  "buildError": null,
  "imageTag": "env-xyz789:abc123def456",
  "lastBuildAt": "2025-01-15T14:22:00.000Z"
}

Poll this endpoint to monitor build progress. The buildStatus will transition from building to either ready or failed.

Get Build Logs


GET /environments/:environmentId/build/logs

Example


curl https://api.computer-agents.com/environments/env_xyz789/build/logs \
  -H "Authorization: Bearer $API_KEY"

Response


{
  "buildLogs": "Step 1/10: FROM testbase-base:latest\n...",
  "buildStatus": "ready"
}

Test Build


POST /environments/:environmentId/build/test

Performs a test build to validate the configuration without caching.

Example


curl -X POST https://api.computer-agents.com/environments/env_xyz789/build/test \
  -H "Authorization: Bearer $API_KEY"

Response (Success)


{
  "success": true,
  "imageTag": "env-xyz789:abc123def456",
  "message": "Build test completed successfully"
}

Response (Failure)


{
  "success": false,
  "error": "Dockerfile syntax error on line 5"
}

MCP Servers Configuration

Configure MCP servers available in this environment:


{
  "mcpServers": [
    {
      "type": "stdio",
      "name": "filesystem",
      "command": "npx",
      "args": ["@modelcontextprotocol/server-filesystem", "/workspace"],
      "enabled": true
    },
    {
      "type": "http",
      "name": "database",
      "url": "https://db-mcp.example.com/mcp",
      "bearerToken": "token",
      "enabled": true
    }
  ]
}

Environment Variables

Set environment variables accessible to agents:


{
  "environmentVariables": [
    { "key": "NODE_ENV", "value": "production" },
    { "key": "DATABASE_URL", "value": "postgres://..." }
  ]
}

Environment variables are securely stored and only accessible during agent execution.

Error Handling

All errors follow a consistent format:


{
  "error": "Error type",
  "message": "Detailed error description"
}

Common Error Codes

Status	Error	Description
400	`Bad Request`	Invalid request body or parameters
401	`Unauthorized`	Missing or invalid API key
403	`Forbidden`	Insufficient permissions
404	`Not Found`	Environment not found or not owned by user
409	`Conflict`	Build already in progress
500	`Internal Server Error`	Server error during operation

Package-Specific Errors

Error	Description
`Invalid package type`	Type must be `system`, `python`, or `node`
`packages must be a non-empty array`	At least one package name required

Build Errors

Error	Description
`Dockerfile syntax error`	Invalid Dockerfile instructions
`Package not found`	System/Python/Node package doesn’t exist
`Build timeout`	Build exceeded maximum time limit

Threads - Run conversations in environments
Agents - Configure agents for environments
Files - Manage workspace files

Environments API

Quick Start with SDK

TypeScript SDK

REST API

The Environment Object

Core Attributes

Runtime & Package Configuration

Build Status

Build Status Values

List Environments

Query Parameters

Example

cURL

JavaScript

Response

Get Default Environment

Example

Create Environment

Request Body

Example

Get Environment

Example

Update Environment

Request Body

Delete Environment

Query Parameters

Example

Set Default Environment

Example

Response

Runtime Management

List Available Runtimes

Example

Response

Get Environment Runtimes

Example

Response

Update Environment Runtimes

Request Body

Example

Package Management

List Packages

Example

Response

Install Packages

Request Body

Example

Response

Uninstall Package

Parameters

Example

Dockerfile Management

Get Dockerfile

Example

Response

Update Dockerfile Extensions

Request Body

Example

Validate Dockerfile

Request Body

Response

Build Management

Trigger Build

Query Parameters

Example

Response

Get Build Status

Example

Response

Get Build Logs

Example

Response

Test Build

Example

Response (Success)

Response (Failure)

MCP Servers Configuration

Environment Variables

Error Handling

Common Error Codes