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

# Named environments

> Create, rename, upgrade and delete environments, and pick the environment for a sandbox.

You can have many environments. 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}
  sandbox.create(CreateSandboxRequest(ttl_seconds=3600, environment="staging"))
  sandbox.resume(sandbox_id, ResumeRequest(environment="staging"))
  sandbox.fork(sandbox_id, 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>


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