> ## Documentation Index
> Fetch the complete documentation index at: https://docs.boat.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Manage environments

> Create, rename, upgrade and delete environments, pick the environment for a sandbox, and share environments with your organization.

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

<CodeGroup>
  ```bash CLI theme={null}
  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
  ```

  ```bash curl theme={null}
  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"
  ```

  ```ts TypeScript theme={null}
  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 });
  ```

  ```python Python theme={null}
  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)
  ```
</CodeGroup>

* 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](/environments/versions).

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

<CodeGroup>
  ```bash CLI theme={null}
  boat new --environment staging
  boat resume bx_f7k2q9hd --environment staging
  boat fork bx_f7k2q9hd --environment staging
  ```

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

  ```ts TypeScript theme={null}
  await sandbox.create({ ttlSeconds: 3600, environment: "staging" });
  await sandbox.resume({ sandboxId, environment: "staging" });
  await sandbox.fork({ sandboxId, environment: "staging" });
  ```

  ```python Python theme={null}
  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"))
  ```
</CodeGroup>

<Warning>
  `--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.
</Warning>

## 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](/ai-credentials#organization-profiles) on an organization environment to give the team's sandboxes the team's AI credentials.

<CodeGroup>
  ```bash CLI theme={null}
  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
  ```

  ```bash curl theme={null}
  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"}'
  ```

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

  ```python Python theme={null}
  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"))
  ```
</CodeGroup>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.