Environments

An environment is a definition, not a running machine. Creating one creates a BMA machine pool by copying the deployment’s template pool and applying what the environment owns: name, description, metadata, packages and desktop settings. The pool is granted to your project automatically.

{
  "name": "data-analysis",
  "config": {
    "type": "cloud",
    "networking": {"type": "unrestricted"},
    "packages": {"pip": ["pandas", "numpy"], "apt": ["jq"]}
  }
}

Field	Support
`config.type`	`cloud` only
`config.networking`	`unrestricted` only. `limited` is rejected because BMA cannot enforce an egress allowlist on the sandbox provider.
`config.packages`	`apt`, `pip`, `npm` are installed by the pool’s startup script; `cargo`, `gem`, `go` are rejected
`config.desktop.wallpaper.file_id`	BMA extension: default desktop wallpaper (a project file, PNG/JPEG/WebP, ≤ 10 MiB)
`metadata`, `description`	Stored
archive	Not supported (`400`): a pool has no archive state. Use `DELETE`.

The stored config is limited to 512 bytes.

What the machines look like

On the hosted deployment, environment machines are E2B sandboxes started from BMA’s machine templates: a Linux desktop-capable image with bmad (the machine daemon) preinstalled. Templates are built with everything preinstalled; BMA does not install system packages at boot beyond your packages. Sessions get their own machines: two sessions in the same environment never share a workspace. See Machines for when machines start, pause and get rebuilt.

Native API equivalent

In the native API you create and grant pools directly (/orgs/{org}/machine-pools, /machine-pool-grants) and reference them from an agent config with machine_sources, including per-agent overrides for working directory, environment variables, size and idle policy. Pool and grant limits stay hard ceilings.

Get started

Concepts

Executor & brains

What the machines look like

Native API equivalent

​What the machines look like

​Native API equivalent

What the machines look like

Native API equivalent