Environments
An environment is the sandbox configuration a session runs under. Create it once and reference its id from every session. Sessions share the configuration. Each gets its own container.
const environment = await client.beta.environments.create({
name: "reviews",
config: { type: "cloud" },
});Fields
| Field | Type | Notes |
|---|---|---|
| name | string | Required. |
| config | object | Required. Carries the type the tools run on. |
| description | string | For your own use. |
| metadata | object | String to string. Echoed, never read. |
The type
type decides what the tools run on. cloud is the Linux container, and it is the only type today. The other keys in config describe that container.
Soon: a second type that runs the tools in memory instead of a container. Less to start, and less to pay for.
The cloud sandbox
The container is Linux, with bash and a home directory the agent owns. A relative path resolves against that home directory. Skills mount under /workspace/skills.
The container starts on the first tool call. It stops when the session goes quiet and keeps its filesystem, so files written in one turn are there in the next. The shell does not survive the stop. The working directory, the exported variables and the background processes are gone when it restarts.
Soon: network policies, container images, self-hosted sandboxes. coreloop stores a config that carries them and echoes it back. Nothing enforces it yet.
Archiving
POST /v1/environments/:id/archive takes the environment out of the list. A session that names an archived environment gets invalid_request_error.
Endpoints
- POST/v1/environments
- GET/v1/environments
- GET/v1/environments/:id
- POST/v1/environments/:id
- POST/v1/environments/:id/archive