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


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);

Python


from computer_agents import ComputerAgentsClient
import os
 
client = ComputerAgentsClient(api_key=os.environ["COMPUTER_AGENTS_API_KEY"])
 
# Get or create default environment
env = client.environments.get_default()
 
# Update runtimes
client.environments.set_runtimes(env["id"], {
    "python": "3.12",
    "nodejs": "22",
})
 
# Install packages
client.environments.install_packages(env["id"], "python", ["pandas", "numpy"])
 
# Trigger build
client.environments.trigger_build(env["id"])

cURL


# Get default environment
curl https://api.computer-agents.com/environments/default \
  -H "Authorization: Bearer $API_KEY"
 
# Update runtimes
curl -X PUT https://api.computer-agents.com/environments/env_xyz/runtimes \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"runtimes": {"python": "3.12", "nodejs": "22"}}'

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: computer-agents-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"

TypeScript


const response = await fetch(
  'https://api.computer-agents.com/environments',
  { headers: { 'Authorization': `Bearer ${API_KEY}` } }
);
const { data: environments } = await response.json();

Python


environments = client.environments.list()

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


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

TypeScript


const env = await client.environments.create({
  name: 'data-science',
  description: 'Environment for data science tasks',
  runtimes: { python: '3.12' },
  packages: {
    system: ['ffmpeg'],
    python: ['pandas', 'numpy', 'matplotlib']
  }
});

Python


env = client.environments.create(
    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


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

TypeScript


const env = await client.environments.get('env_xyz789');

Python


env = client.environments.get("env_xyz789")

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

cURL


# 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"

TypeScript


// Soft delete
await client.environments.delete('env_xyz789');

Python


# Soft delete
client.environments.delete("env_xyz789")

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


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

TypeScript


await client.environments.setRuntimes('env_xyz789', {
  python: '3.12',
  nodejs: '20'
});

Python


client.environments.set_runtimes("env_xyz789", {
    "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


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

TypeScript


await client.environments.installPackages('env_xyz789', 'python', ['requests', 'beautifulsoup4']);

Python


client.environments.install_packages("env_xyz789", "python", ["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": "computer-agents-base:latest",
  "dockerfileExtensions": "RUN pip install custom-package",
  "effectiveDockerfile": "FROM computer-agents-base:latest\nWORKDIR /workspace\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 computer-agents-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