> For the complete documentation index, see [llms.txt](https://docs.bluerock.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.bluerock.io/bluerock-documentation-2.7.0-beta/bluerock-sandbox/configure-bouncer-verb-contracts.md).

# Configure Bouncer Verb Contracts

### Introduction

A verb contract says which Bouncer operations a connecting user may perform and how many containers they may own.

Contracts are defined in the BlueRock policy configuration file (`bru_policy.json`), located in `/opt/bluerock/trex/`, under two top-level keys:

* `bouncer_contracts`: Named contracts.
* `bouncer_contract_mapping`: Which user gets which contract.

Contracts apply to devcontainer hosts (Bouncer plus co-located `bluerockd`). On a host, the Bouncer gets the contract from `bluerockd` when the user connects. The `[capabilities]` and `[limits]` sections of `bouncer.toml` are ignored there, while `[allowlist]` is still read from `bouncer.toml`. A standalone gateway still reads its contract from `bouncer.toml`.

When a user connects to a sandbox container using the BlueRock Connector client application, the Bouncer contract is selected based on the user's principal and the rules defined in `bouncer_contract_mapping`. The selected contract determines which Bouncer operations the user is allowed to perform and the applicable container limits.

***

### Policy Format and Configuration

#### Example

The following example defines four contracts and maps users to them.

```bash
{
  "bouncer_contracts": {
    "default": {
      "capabilities": {
        "destroy": {
          "enabled": false
        }
      },
      "limits": {
        "max_containers_per_principal": 3
      }
    },
    "admin": {
      "limits": {
        "max_containers_per_principal": 0
      }
    },
    "attach-only": {
      "capabilities": {
        "up": {
          "enabled": false
        },
        "stop": {
          "enabled": false
        },
        "destroy": {
          "enabled": false
        },
        "rename": {
          "enabled": false
        }
      }
    },
    "catalog-only": {
      "capabilities": {
        "up": {
          "url_source": false,
          "shares": false
        }
      }
    }
  },
  "bouncer_contract_mapping": {
    "rules": [
      {
        "principal": "alice@example.com",
        "contract": "admin"
      },
      {
        "principal": "*@contractor.example.com",
        "contract": "attach-only"
      },
      {
        "principal": "key:SHA256:*",
        "contract": "catalog-only"
      }
    ],
    "default": "default"
  }
}
```

#### Result

| User                                        | Contract       | Effect                                                                                                                                                                                                     |
| ------------------------------------------- | -------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `alice@example.com`                         | `admin`        | Every verb allowed, no container limit.                                                                                                                                                                    |
| Anyone at `contractor.example.com`          | `attach-only`  | Can attach to and start existing containers but cannot create, stop, destroy, or rename them. Limit 5 (the default). `start` stays enabled because autostop stops containers the user is not connected to. |
| Any user authenticated with a plain SSH key | `catalog-only` | `up` works only from catalog templates: no Git URLs, no remote shares.                                                                                                                                     |
| Everyone else                               | `default`      | Cannot destroy, and at most 3 containers.                                                                                                                                                                  |

#### Mapping

Rules are checked in order and the first match wins. If no rule matches, the user gets the contract named in `default`.

`principal` is a glob matched against the whole principal string. It supports `*` and `?` and is case-sensitive. A principal is either the SSH certificate principal (for example, `alice@example.com`) or `key:SHA256:<fingerprint>` for a plain SSH key.

The SSO principal names should be in lower case.  Upper case letter in the principal name is rejected by the policy builder tool `trex`.

Every contract named in the mapping (in a rule's `contract` or in `default`) must be defined in `bouncer_contracts`.

#### Contracts

There is no inheritance. A contract inherits nothing from `default`: a field it leaves out gets the built-in default, which is enabled for every verb and a limit of 5. In the example, `admin` can still destroy even though `default` disables it.

Your `bouncer_contracts` replaces the shipped one. Either define a contract named `default`, or set `bouncer_contract_mapping.default` to one of your contract names.

`max_containers_per_principal: 0` means unlimited. The default is 5.

#### Spelling

* An unknown verb or key, such as a typo, is rejected.

If a policy breaks any of these rules, the policy builder tool `trex` refuses to transform it and names the problem. For example:

```bash
bouncer_contract_mapping references unknown bouncer_contracts ['default']
Extra inputs are not permitted
```

***

### Capabilities and Reference Tables

Every verb takes `{ "enabled": true|false }`, and every verb is enabled by default. Not every verb can be turned off safely, because BlueRock Connector application and BlueRock Vscode extension application use some of them for features that look unrelated. Three verbs also need the host's `bouncer.toml` to allow them.

#### Supported verbs

| Key               | Controls                                                                                                                                                          | Safe to disable?           |
| ----------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------- |
| `list`            | List the user's containers.                                                                                                                                       | No                         |
| `inspect`         | Show one container's metadata.                                                                                                                                    | Yes                        |
| `catalog`         | List catalog templates.                                                                                                                                           | Yes                        |
| `exec`            | Run a command in a container.                                                                                                                                     | No                         |
| `start`           | Start a stopped container.                                                                                                                                        | No, unless autostop is off |
| `stop`            | Stop a running container.                                                                                                                                         | Yes                        |
| `destroy`         | Stop and remove a container.                                                                                                                                      | Yes                        |
| `rename`          | Rename a container.                                                                                                                                               | Yes                        |
| `up`              | Create or bring up a devcontainer (sub-keys below).                                                                                                               | Yes                        |
| `tcpip`           | Port forwarding. Each destination is also checked against the `[allowlist]` in `bouncer.toml`.                                                                    | No                         |
| `logs`            | Stream container logs.                                                                                                                                            | Yes                        |
| `wait`            | Wait for a container to reach a given state.                                                                                                                      | Yes                        |
| `set_autostop`    | Change a container's autostop setting, or choose one when creating it. Disabling this does not turn autostop off; that is `[autostop] enabled` in `bouncer.toml`. | Yes                        |
| `resolve_attach`  | Resolve the attach configuration for Remote-SSH attach.                                                                                                           | Yes, with a side effect    |
| `git_credentials` | Git credential forwarding.                                                                                                                                        | Yes                        |
| `ssh_agent`       | SSH-agent forwarding.                                                                                                                                             | Yes                        |

#### `up` sub-keys

`up` has three extra sub-keys, each `true` by default.

| Key              | Allows                                                                                                               | Safe to disable?        |
| ---------------- | -------------------------------------------------------------------------------------------------------------------- | ----------------------- |
| `catalog_source` | Creating a container from a catalog template (`catalog:<path>`).                                                     | Yes, with a side effect |
| `url_source`     | Creating a container from a Git URL (`git+...`), including a catalog template that clones the user's own repository. | Yes                     |
| `shares`         | Mounting remote NFS/CIFS shares.                                                                                     | Yes                     |

#### Which verbs are safe to disable?

A verb is safe to disable when BlueRock Connector application and BlueRock Vscode extension appliaction cope with it being off: they hide or grey out the action, or the Bouncer refuses it with a clear message, and nothing else stops working. The verbs marked **No** are also used behind the scenes, by features that look unrelated. Turning one of them off breaks those features, usually with an error that does not mention the policy, and neither client hides the features.

**Do not disable these for anyone who uses BlueRock Connector application and BlueRock VS Code extension application.**

| Key     | What breaks when it is off                                                                                                                                                                                                                                                                                                                                      |
| ------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `list`  | Both clients look up the user's containers before acting on one. The user can no longer attach to, start, stop, rename or remove an existing container, and `BlueRockConnector` Application cannot bring up its sandbox at all.                                                                                                                                 |
| `exec`  | Attaching from VS Code or Cursor: the editor installs its server, opens terminals and transfers files through `exec`. Forwarded ports and SSH-agent forwarding stop too. In `BlueRockConnector` Application, creating a sandbox fails after the container already exists, and Claude Code Desktop, file sharing, upload, download and Codex setup stop working. |
| `tcpip` | VS Code and Cursor reach their server in the container through `tcpip`, so the editor window never finishes connecting. Forwarded ports and `BlueRockConnector` Application file sharing accept connections and then drop them without an error.                                                                                                                |
| `start` | Autostop stops a container shortly after its user disconnects, and the user then cannot start it again. Disable `start` only on hosts where autostop is off (`[autostop] enabled = false` in `bouncer.toml`).                                                                                                                                                   |

The other verbs are safe to disable. With one of them off, users see this:

| Key                            | What users see when it is off                                                                                                                                                                                                                                                                   |
| ------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `inspect`, `logs`, `wait`      | Nothing. Neither client uses them.                                                                                                                                                                                                                                                              |
| `catalog`                      | `BlueRock Connector` Extension for VSCODE greys out its catalog. `BlueRockConnector` Application does not use it.                                                                                                                                                                               |
| `stop`, `rename`               | `BlueRock Connector` Extension for VSCODE greys out the action. `BlueRockConnector` Application hides Stop and has no Rename.                                                                                                                                                                   |
| `destroy`                      | Both clients hide or grey out the action. The user's containers still count toward `max_containers_per_principal`, so a user who cannot remove containers eventually reaches the limit and cannot create more.                                                                                  |
| `up`                           | Both clients grey out or hide creating a container. Where it is still offered, the Bouncer refuses it before anything is created. `BlueRockConnector` Application also hides its Destroy item.                                                                                                  |
| `up.catalog_source`            | `BlueRock Connector` Extension for VSCODE greys out creating from the catalog. `BlueRockConnector` Application creates every sandbox from a catalog template, so its users cannot create one: `BlueRockConnector` Application still offers to, and the Bouncer refuses with `feature_disabled`. |
| `up.url_source`                | `BlueRock Connector` Extension for VSCODE greys out creating from a repository. Its command-palette command is still offered and is refused with `feature_disabled` once the user has picked a repository. `BlueRockConnector` Application does not use Git sources.                            |
| `up.shares`                    | `BlueRock Connector` Extension for VSCODE hides its shares settings; `BlueRockConnector` Application `up --share` is refused with `feature_disabled`.                                                                                                                                           |
| `set_autostop`                 | `BlueRock Connector` Extension for VSCODE hides its autostop settings and says autostop is managed by your organization. `BlueRockConnector` Application does not change autostop.                                                                                                              |
| `resolve_attach`               | Attaching still works, but `BlueRock Connector` Extension for VSCODE silently skips the editor setup from `devcontainer.json`: extensions, settings and forwarded ports, and copying the user's `.gitconfig`. `BlueRockConnector` Application does not use it.                                  |
| `git_credentials`, `ssh_agent` | The clients stop setting up Git credential or SSH-agent forwarding.                                                                                                                                                                                                                             |

#### Verbs that also need `bouncer.toml`

Three verbs have a second switch in each host's `bouncer.toml`. The verb works only when the policy and `bouncer.toml` both allow it. The policy can take these verbs away from a user, but it cannot give them to a user while `bouncer.toml` has them off: on such a host, `"enabled": true` in the policy has no effect.

| **Key**           | **Required host configuration in&#x20;**<kbd>**bouncer.toml**</kbd>        | **Default** |
| ----------------- | -------------------------------------------------------------------------- | ----------- |
| `set_autostop`    | `[autostop]` with `enabled = true` and `allow_client_override = true`      | On          |
| `git_credentials` | `[devcontainer_attach]` with `enabled = true` and `git_credentials = true` | Off         |
| `ssh_agent`       | `[devcontainer_attach]` with `enabled = true` and `ssh_agent = true`       | Off         |

Git credential and SSH-agent forwarding therefore stay off for every user until the host's operator turns them on in `bouncer.toml`, whatever the policy says.

***

### Runtime Behavior and Troubleshooting

#### Runtime behaviour

* When a contract applies, the Bouncer looks up the contract once, when the user's SSH link connects, and keeps it for that whole session. After deploying a policy change, reconnect to pick it up.
* If no contract can be looked up, login fails: this happens when `bluerockd` is unreachable or has no policy yet. The Bouncer never falls back to a permissive contract.
* Clients: BlueRock Connector application and BlueRock Vs code extension application receive the contract when they connect and hide or grey out most disabled actions, but not all of them. The Bouncer still enforces it on its side.

#### What a denied user sees

| Case                                                              | Message                                                                                                                                                                     |
| ----------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Disabled verb                                                     | `That operation is disabled for you on this host.`                                                                                                                          |
| Disabled `up` sub-feature                                         | Names the feature, e.g. `feature 'up.url_source' is disabled on this bouncer (operator policy)` or `remote shares are disabled on this bouncer (up.shares capability off)`. |
| Autostop settings sent with `up` while `set_autostop` is disabled | `autostop settings are disabled for you on this host (set_autostop capability off)`                                                                                         |
| Container limit reached                                           | `limit 'max_containers_per_principal' exceeded (3/3)`                                                                                                                       |

#### Checking which contract a user got

Set `[log] level = "debug"` in `bouncer.toml`. The Bouncer then logs a `contract.resolved` diagnostic record that names the principal and the full contract it was given.

***


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.bluerock.io/bluerock-documentation-2.7.0-beta/bluerock-sandbox/configure-bouncer-verb-contracts.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
