Environments API

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

The Environment Object


{
  "id": "env_kJDvlIZ0mXZI0JrqbHj25",
  "userId": "user_abc123",
  "name": "production",
  "status": "running",
  "config": {
    "baseImage": "node:20-slim",
    "envVars": {
      "NODE_ENV": "production"
    },
    "mcpServers": [
      {
        "type": "stdio",
        "name": "filesystem",
        "command": "npx",
        "args": ["@modelcontextprotocol/server-filesystem", "/workspace"]
      }
    ]
  },
  "createdAt": "2025-01-15T10:30:00.000Z",
  "updatedAt": "2025-01-15T14:22:00.000Z"
}

Attributes

Attribute	Type	Description
`id`	string	Unique identifier (`env_*`)
`userId`	string	Owner user ID
`name`	string	Human-readable name
`status`	string	`stopped`, `building`, `running`, `error`
`config`	object	Environment configuration
`appId`	string	Associated application ID
`metadata`	object	Custom key-value metadata
`createdAt`	string	ISO 8601 timestamp
`updatedAt`	string	ISO 8601 timestamp

Environment Status

Status	Description
`stopped`	Container is not running
`building`	Container image is being built
`running`	Container is active and ready
`error`	Container failed to start or crashed

List Environments


GET /v1/environments

Query Parameters

Parameter	Type	Default	Description
`status`	string	-	Filter by status
`appId`	string	-	Filter by application
`limit`	number	50	Max results (1-100)
`offset`	number	0	Pagination offset

Example

cURL


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

Response


{
  "object": "list",
  "data": [
    {
      "id": "env_kJDvlIZ0mXZI0JrqbHj25",
      "name": "production",
      "status": "running",
      "createdAt": "2025-01-15T10:30:00.000Z"
    },
    {
      "id": "env_lK0Cu7erCnf0jQjXKDs26",
      "name": "staging",
      "status": "stopped",
      "createdAt": "2025-01-10T08:00:00.000Z"
    }
  ],
  "has_more": false,
  "total_count": 2
}

Create Environment


POST /v1/environments

Request Body

Parameter	Type	Required	Description
`name`	string	Yes	Environment name
`config`	object	No	Configuration settings
`appId`	string	No	Application ID
`metadata`	object	No	Custom metadata

Example


curl -X POST https://api.computer-agents.com/v1/environments \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "development",
    "config": {
      "baseImage": "python:3.11-slim",
      "envVars": {
        "DEBUG": "true"
      }
    }
  }'

Response


{
  "environment": {
    "id": "env_mL1Dv8fsDoc1kRkYLEt37",
    "userId": "user_abc123",
    "name": "development",
    "status": "stopped",
    "config": {
      "baseImage": "python:3.11-slim",
      "envVars": {
        "DEBUG": "true"
      }
    },
    "createdAt": "2025-01-20T12:00:00.000Z"
  }
}

Get Environment


GET /v1/environments/:environmentId

Example


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

Response


{
  "environment": {
    "id": "env_xyz789",
    "userId": "user_abc123",
    "name": "development",
    "status": "running",
    "config": {
      "baseImage": "python:3.11-slim",
      "envVars": {
        "DEBUG": "true"
      }
    },
    "createdAt": "2025-01-20T12:00:00.000Z"
  }
}

Update Environment


PATCH /v1/environments/:environmentId

Request Body

Parameter	Type	Description
`name`	string	New environment name
`config`	object	Updated configuration
`metadata`	object	Updated metadata

Example


curl -X PATCH https://api.computer-agents.com/v1/environments/env_xyz789 \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "config": {
      "envVars": {
        "LOG_LEVEL": "debug"
      }
    }
  }'

Delete Environment


DELETE /v1/environments/:environmentId

This stops any running container and deletes all environment configuration and files.

Example


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

Response


{
  "success": true
}

Environment Configuration

Base Image

Specify the container base image:


{
  "config": {
    "baseImage": "node:20-slim"
  }
}

Common images:

node:20-slim - Node.js applications
python:3.11-slim - Python applications
golang:1.21-alpine - Go applications

Environment Variables

Set environment variables accessible to agents:


{
  "config": {
    "envVars": {
      "NODE_ENV": "production",
      "DATABASE_URL": "postgres://...",
      "API_KEY": "secret"
    }
  }
}

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

MCP Servers

Configure MCP servers available in this environment:


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

File Operations

List Files

List files in an environment’s workspace.


GET /v1/environments/:environmentId/files

Query Parameters

Parameter	Type	Default	Description
`path`	string	`/`	Directory path
`recursive`	boolean	`false`	Include subdirectories

Example


curl "https://api.computer-agents.com/v1/environments/env_xyz789/files?path=/src" \
  -H "Authorization: Bearer $API_KEY"

Response


{
  "object": "list",
  "data": [
    {
      "name": "app.py",
      "path": "/src/app.py",
      "type": "file",
      "size": 2048,
      "modifiedAt": "2025-01-15T10:30:00.000Z"
    },
    {
      "name": "utils",
      "path": "/src/utils",
      "type": "directory",
      "modifiedAt": "2025-01-14T08:00:00.000Z"
    }
  ],
  "path": "/src",
  "has_more": false,
  "total_count": 2
}

Get File

Download a file from the environment.


GET /v1/environments/:environmentId/files/:path

Example


curl "https://api.computer-agents.com/v1/environments/env_xyz789/files/src%2Fapp.py" \
  -H "Authorization: Bearer $API_KEY"

Upload File

Upload a file to the environment.


PUT /v1/environments/:environmentId/files/:path

Example


curl -X PUT "https://api.computer-agents.com/v1/environments/env_xyz789/files/src%2Fnew_file.py" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: text/x-python" \
  --data-binary @new_file.py

Delete File


DELETE /v1/environments/:environmentId/files/:path

Errors

Status	Error	Description
400	`Bad Request`	Invalid configuration
404	`Not Found`	Environment not found
409	`Conflict`	Container already in requested state
500	`Internal Server Error`	Container operation failed

Threads - Run conversations in environments
Agents - Configure agents for environments
Costs - Track environment costs

Environments API

The Environment Object

Attributes

Environment Status

List Environments

Query Parameters

Example

cURL

JavaScript

Response

Create Environment

Request Body

Example

Response

Get Environment

Example

Response

Update Environment

Request Body

Example

Delete Environment

Example

Response

Environment Configuration

Base Image

Environment Variables

MCP Servers

File Operations

List Files

Query Parameters

Example

Response

Get File

Example

Upload File

Example

Delete File

Errors

Related