# 3pm-backend route `setBucketSettings`

Paths are relative to the backend's origin (https://fleet.edgecr4ft.net, or your own 3pm-backend), not to this site. Index: https://3pm.edgecr4ft.net/docs/backend/api.md

---

tokens:
  claude: 1110
  o200k: 647
# POST /api/buckets/{clusterId}/settings (setBucketSettings)

Set the bucket's settings — `approval`: whether a host that links with a reusable token waits for `approveNode` (turning it off approves the hosts already waiting); `require_access_rights`: off, every active node may place a call on every other, as if each held `fleet:invoke`, `fleet:list` and `fleet:read`; `record_shells` (on by default): the screen of each shell session is kept as an asciicast artifact of its call. Answers the bucket as it now stands.

- auth: an account — Authorization: Bearer 3pmu_<token>, or the dashboard's session cookie
- body: SetBucketSettings (JSON)
- answer: BucketView (JSON)

## Types

```ts
/** `setBucketSettings`'s body: a setting left out is unchanged; a body naming none is a 400. */
interface SetBucketSettings {
  /** `false`: every host that links with a valid token of the bucket is active at once, and the hosts already waiting are approved. */
  approval?: boolean;
  /** `false`: every active node may place a call on every other node of the bucket — each is treated as holding `fleet:invoke`, `fleet:list` and `fleet:read` for as long as this is off, whatever its own `scopes`. A target's `callers` rules still narrow who may call it. `true` (the default): a node does only what `setNodeAccess` granted it. */
  require_access_rights?: boolean;
  /** `false`: shell, command and attach sessions are no longer recorded. `true` (the default): what each session's screen showed — never what was typed — is kept as an asciicast (`.cast`) artifact of its call. */
  record_shells?: boolean;
}

interface BucketView {
  cluster_id: ClusterId;
  name: string;
  created_at: EpochMs;
  /** Does a host that links with a reusable token wait for `approveNode`? `false`: a valid token of the bucket is enough (`setBucketSettings`). For the owner only — absent from what a node's bearer reads. */
  approval?: boolean;
  /** Does a node ask of the bucket only what it was granted (`setNodeAccess`)? `false`: every active node may place a call on every other, with no scope granted node by node (`setBucketSettings`). For the owner only, like `approval`. */
  require_access_rights?: boolean;
  /** Is the screen of each `3pm fleet ssh` / `fleet attach` session kept as an asciicast artifact of its call (`setBucketSettings`)? On by default. For the owner only, like `approval`. */
  record_shells?: boolean;
}

/** `3pmc_…` — a bucket. */
type ClusterId = string;

/** Milliseconds since the Unix epoch. */
type EpochMs = number;
```