Manage environments

You can have many environments, for example base, staging and prod. Each one is a full environment with its own repositories, secrets and credentials. Exactly one of them is the default. A sandbox uses the default when you do not name an environment.

Manage environments

boat env list
boat env info staging
boat env new staging
boat env rename staging prod
boat env default prod
boat env rm staging
boat env upgrade prod

curl -sS "$BOAT_API_BASE/environments" -H "Authorization: Bearer $BOAT_API_KEY"

curl -sS -X POST "$BOAT_API_BASE/environments" \
  -H "Authorization: Bearer $BOAT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name":"staging"}'

curl -sS -X PUT "$BOAT_API_BASE/environments/$ENV_ID" \
  -H "Authorization: Bearer $BOAT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name":"prod","isDefault":true,"safeForThirdParties":true}'

curl -sS -X POST "$BOAT_API_BASE/environments/$ENV_ID/upgrade" \
  -H "Authorization: Bearer $BOAT_API_KEY"

curl -sS -X DELETE "$BOAT_API_BASE/environments/$ENV_ID" \
  -H "Authorization: Bearer $BOAT_API_KEY"

const { environments } = await sandbox.environments();
const staging = await sandbox.createEnvironment({ name: "staging" });

await sandbox.updateEnvironment({
  environmentId: envId,
  name: "prod", isDefault: true, safeForThirdParties: true,
});

await sandbox.upgradeEnvironment({ environmentId: envId });
await sandbox.deleteEnvironment({ environmentId: envId });

from boat_sdk.models.create_sandbox_environment_request import CreateSandboxEnvironmentRequest
from boat_sdk.models.update_sandbox_environment_request import UpdateSandboxEnvironmentRequest

envs = sandbox.environments()
staging = sandbox.create_environment(CreateSandboxEnvironmentRequest(name="staging"))

sandbox.update_environment(env_id, UpdateSandboxEnvironmentRequest(
    name="prod", is_default=True, safe_for_third_parties=True,
))

sandbox.upgrade_environment(env_id)
sandbox.delete_environment(env_id)

A delete is a soft delete. Sandboxes pinned to its versions keep running. New sandboxes cannot use it.
upgradeEnvironment accepts an optional list of sandbox ids. Use it to upgrade only those sandboxes. Without the list, Boat moves every sandbox of yours that is on an older version. Read Versions and upgrades.

Pick the environment for a sandbox

Pass the environment name when you create, resume or fork a sandbox. Without a name, Boat uses your default.

Boat rejects an unknown name before it creates or changes anything. A typo costs you nothing.
Boat never creates an environment by itself.

boat new --environment staging
boat resume bx_f7k2q9hd --environment staging
boat fork bx_f7k2q9hd --environment staging

curl -sS -X POST "$BOAT_API_BASE/sandboxes" \
  -H "Authorization: Bearer $BOAT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"ttlSeconds":3600,"environment":"staging"}'

await sandbox.create({ ttlSeconds: 3600, environment: "staging" });
await sandbox.resume({ sandboxId, environment: "staging" });
await sandbox.fork({ sandboxId, environment: "staging" });

from boat_sdk.models.create_sandbox_request import CreateSandboxRequest
from boat_sdk.models.resume_request import ResumeRequest
from boat_sdk.models.fork_request import ForkRequest

sandbox.create(create_sandbox_request=CreateSandboxRequest(ttl_seconds=3600, environment="staging"))
sandbox.resume(sandbox_id, resume_request=ResumeRequest(environment="staging"))
sandbox.fork(sandbox_id, fork_request=ForkRequest(environment="staging"))

--environment and --env are different flags.

--environment staging picks the environment that the sandbox uses.
--env KEY=value sets one variable on that one sandbox. It adds to what the environment gives.

Organization environments

An organization has its own shared environments. Add ?org=<org id or name> to any environment route, or --org <org> to any boat env command. Only this query parameter selects them: the X-Boat-Org header and the active wallet do not, so a call without org always works on your own environments.

Role	Can do
Member	List the organization environments and use them for sandboxes
Owner or admin	Also create, change and delete them

A sandbox billed to the organization can name an organization environment. When you have an environment of the same name, yours wins. Name an organization credential profile on an organization environment to give the team’s sandboxes the team’s AI credentials.

boat env list --org acme
boat env new agents --org acme
boat env set agents --org acme --credential-profile team-claude
boat --org acme new --environment agents

curl -sS "$BOAT_API_BASE/environments?org=acme" -H "Authorization: Bearer $BOAT_API_KEY"

curl -sS -X PUT "$BOAT_API_BASE/environments/$ENV_ID?org=acme" \
  -H "Authorization: Bearer $BOAT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"credentialProfileId":"team-claude"}'

const { environments } = await sandbox.environments({ org: "acme" });
await sandbox.updateEnvironment({ environmentId: envId, org: "acme", credentialProfileId: "team-claude" });
await sandbox.create({ org: "acme", environment: "agents" });

envs = sandbox.environments(org="acme")
sandbox.update_environment(env_id, UpdateSandboxEnvironmentRequest(credential_profile_id="team-claude"), org="acme")
sandbox.create(create_sandbox_request=CreateSandboxRequest(org="acme", environment="agents"))

Get started

Use cases

Connect to a sandbox

Run work and keep it running

Set up new sandboxes

Stop, resume and snapshots

Machines

Run agents inside

Teams

Security, isolation, data & compliance

Help

Manage environments