> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://platform.bctrl.ai/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://platform.bctrl.ai/_mcp/server.

# Spaces

> The boundary that scopes which storage, secrets, and AI credentials a runtime can use.

A **Space** is the boundary around your automation resources. It groups
Runtimes and defines the environment they can use: durable storage, Vault
secrets, and AI credentials.

A Runtime inherits the environment of the Space it belongs to. Configure a
capability once at the Space boundary when several Runtimes should share it.

## Create a Space

The smallest valid request is an empty object:

```ts
const space = await bctrl.spaces.create({});
console.log(space.id);
```

Give the Space a name when you want a stable label in your application:

```ts
const space = await bctrl.spaces.create({
  name: "checkout-automation",
});
```

You can configure its environment at creation time:

```ts
const models = await bctrl.ai.models.list({
  status: "recommended",
});
const modelId = models.data[0]?.id;
if (!modelId) {
  throw new Error("No recommended Browser Use model is available");
}

const space = await bctrl.spaces.create({
  name: "checkout-automation",
  environment: {
    storage: { namespace: "checkout" },
    vault: { allow: ["checkout/"] },
    ai: {
      credentialIds: ["openai-production"],
      default: modelId,
    },
  },
});
```

### Create fields

| Parameter     | Type                | Required | Description                                                             |
| ------------- | ------------------- | -------- | ----------------------------------------------------------------------- |
| `name`        | `string`            | No       | Human-readable label. The server supplies a default when omitted.       |
| `region`      | `string`            | No       | Region for the Space. The current platform region is `"us-east-1"`.     |
| `environment` | `EnvironmentMounts` | No       | Storage, Vault, and AI capabilities available to Runtimes in the Space. |

## Space identity

The Space object includes its environment, so one response gives you both the
Space identity and the capabilities available to its Runtimes.

| Field         | Type                | Always present | Description                                                             |
| ------------- | ------------------- | -------------- | ----------------------------------------------------------------------- |
| `id`          | `string`            | Yes            | Durable Space identifier. Pass it as `spaceId` when creating a Runtime. |
| `name`        | `string`            | Yes            | Human-readable label.                                                   |
| `region`      | `string`            | Yes            | Region where the Space runs.                                            |
| `isDefault`   | `boolean`           | Yes            | Whether this is the caller's default Space.                             |
| `environment` | `EnvironmentMounts` | Yes            | Storage, Vault, and AI mounts available to the Space.                   |
| `createdAt`   | `string`            | Yes            | Creation timestamp.                                                     |
| `updatedAt`   | `string`            | Yes            | Last update timestamp.                                                  |

Use the Space ID for resource operations. The literal `"default"` can be used
where the API accepts a Space selector to address the caller's default Space.

## Space environment

An environment is a set of optional mounts. If a mount is omitted, that
capability is not mounted into the Space.

| Field     | Type                    | Always present | Description                                                      |
| --------- | ----------------------- | -------------- | ---------------------------------------------------------------- |
| `storage` | `{ namespace: string }` | No             | Durable file namespace available to the Space.                   |
| `vault`   | `SpaceVaultMount`       | No             | Secret prefixes and direct-read policy available to Vault Tools. |
| `ai`      | `EnvironmentAiMount`    | No             | Saved AI credentials and default models available to Agents.     |

### Storage

| Field               | Type     | Always present | Description                                         |
| ------------------- | -------- | -------------- | --------------------------------------------------- |
| `storage.namespace` | `string` | Yes            | Namespace used by the Space's durable file storage. |

### Vault

| Field                 | Type       | Always present | Description                                 |
| --------------------- | ---------- | -------------- | ------------------------------------------- |
| `vault.allow`         | `string[]` | No             | Secret prefixes Vault Tools may access.     |
| `vault.deny`          | `string[]` | No             | Secret prefixes that remain inaccessible.   |
| `vault.allowRawReads` | `boolean`  | No             | Allow Tools to read secret values directly. |

Keep the allowlist narrow. Leave `allowRawReads` unset unless the workflow
needs the secret value itself; many workflows only need Vault to provide a
credential to a Tool.

### AI

| Field              | Type                               | Always present | Description                                                |
| ------------------ | ---------------------------------- | -------------- | ---------------------------------------------------------- |
| `ai.credentialIds` | `string[]`                         | No             | Saved AI credential IDs that Agents may use in this Space. |
| `ai.default`       | `string \| AiStoredModelSelection` | No             | Default model selection for hosted Conversation turns.     |

A string is the shorthand model form:

```ts
default: modelId
```

Use the object form when the selection needs explicit authentication or model
controls:

```ts
default: {
  model: modelId,
  auth: { credential: "openai-production" },
  reasoningEffort: "medium",
}
```

`AiStoredModelSelection` has a required `model` and optional `auth`, `provider`,
and model controls. `auth` can be `"managed"` or
`{ credential: string }`. When a saved credential is selected, its provider is
used; do not send a separate `provider` with `auth: { credential: ... }`.
The [AI models](/sdk/ai) page explains model selections and credentials in
detail.

## Read and update the environment

Read the environment from the Space object:

```ts
const current = await bctrl.spaces.get(space.id);
const environment = current.environment;

console.log(environment.storage?.namespace);
console.log(environment.vault?.allow);
console.log(environment.ai?.credentialIds);
```

Include `environment` in `spaces.update()` to patch the Space environment:

* Omit a mount to leave it unchanged.
* Send an object to add or replace a mount.
* Send `null` to remove a mount.

```ts
await bctrl.spaces.update(space.id, {
  name: "checkout-production",
  environment: {
    storage: { namespace: "checkout" },
    vault: {
      allow: ["checkout/"],
      deny: ["checkout/admin/"],
    },
    ai: {
      credentialIds: ["openai-production"],
      default: modelId,
    },
  },
});
```

For nested AI fields, the same patch rules apply. Omit a field to keep it,
provide a value to set it, and use `null` to clear it:

```ts
await bctrl.spaces.update(space.id, {
  environment: {
    ai: {
      default: null,
    },
  },
});
```

To remove the complete mount:

```ts
await bctrl.spaces.update(space.id, {
  environment: {
    vault: null,
  },
});
```

## Manage Spaces

```ts
const page = await bctrl.spaces.list({ limit: 50 });
const current = await bctrl.spaces.get(space.id);

await bctrl.spaces.update(space.id, {
  name: "checkout-production",
});

for await (const item of bctrl.spaces.iter()) {
  console.log(item.id, item.name);
}
```

Delete a Space only after its active Runtimes have stopped:

```ts
await bctrl.spaces.delete(space.id);
```

## Use a Space with a Runtime

Pass `spaceId` when creating a Runtime. If you omit it, the Runtime uses the
caller's default Space.

```ts
const runtime = await bctrl.runtimes.create({
  spaceId: space.id,
});
```

Runtime-specific settings such as browser identity, proxy, and extensions
belong in [Runtimes](/sdk/runtimes).