# Configuration

> Every CoworkkitProvider prop and its default — FAB position and drag, the z-index escape valve, the confirmation timeout, the app-wide control baseline, and the wiring props.

`CoworkkitProvider` is the one component you mount. Only `getToken` is required — it is your [closed-loop token route](/docs/how-it-works). Every other prop is optional and ships with a sensible default, so a bare Provider works out of the box. This page is the complete list.

```tsx
<CoworkkitProvider getToken={getToken}>
  {children}
</CoworkkitProvider>
```

## Placement & behavior

Where the button sits and how it moves.

```tsx
fabPosition?: "bottom-right" | "bottom-left" | "top-right" | "top-left"; // default "bottom-right"
draggable?: boolean; // default true
zIndex?: number;     // default 2147483640
```

- `fabPosition` — which corner the button anchors to. Default `"bottom-right"`.
- `draggable` — let the user drag the button off its anchor; the new position persists across reloads. Default `true`. Set `false` to pin it.
- `zIndex` — the stacking order of the button, its ring, and the page-edge glow. The default, `2147483640`, sits just under the 32-bit maximum so the overlays float above almost everything. Lower it only if the button covers an overlay of your own that legitimately needs to sit on top.

## Confirmation & control

How actions are gated. Both are covered in depth under [Control & confirmation](/docs/control) — here are the two Provider-level knobs.

```tsx
confirmationTimeout?: number;              // default 60 (seconds)
defaultControl?: "open" | "soft" | "hard"; // default "open"
```

- `confirmationTimeout` — how many seconds a `hard` confirmation may stay pending before the SDK resolves it as `timeout` (the handler never runs). Default `60`.
- `defaultControl` — the app-wide baseline for actions that declare no `control` of their own and aren't caught by the destructive-name fail-safe. Default `"open"` (reads and benign actions run freely). Set `"soft"` to make the whole app ask-first; an explicit per-action `control` always wins.

## Appearance

```tsx
look?: string | LookSpec;                // brand the button (Studio look code or inline spec)
intensity?: "default" | "subtle" | "off"; // default "default"
```

- `look` — brand the button with your accent and dot style, via a Studio look code or an inline spec. See [Appearance](/docs/appearance).
- `intensity` — the visual prominence of the button. Default `"default"`. `"subtle"` dials it down — a fainter ring and a softer shadow; `"off"` removes the button entirely, an escape hatch to keep the Provider mounted without rendering the surface.

## Wiring

Rarely set — the defaults are right for the common case.

```tsx
getToken: () => Promise<SessionToken>;            // required — your token route
cloudUrl?: string;                               // fallback control base
fallbackSurface?: (pathname: string) => Surface; // derive a surface from the URL
onActionRecord?: (record: ActionRecord) => void; // observe every settled action
```

- `getToken` — the one required prop: an async function that returns a minted session from your server. The tenant key stays server-side; it never reaches the browser. See [Getting started](/docs/getting-started).
- `cloudUrl` — normally omitted. A live session already carries the control base it was minted against, and that value wins while a session is running; this prop is only the fallback for pre-session and session-less (dev) configs.
- `fallbackSurface` — derive a [surface](/docs/actions-surfaces) from the current pathname when a route declares no `useSurface` of its own.
- `onActionRecord` — called once per settled action with a record of what ran, how it was gated, and the outcome. The SDK emits; you persist it (your DB or SIEM). The [Watch panel](/docs/watch) shows the same record in dev with no wiring.

Note there is **no** `apiKey` prop. The tenant key is secret and server-side, held by your `getToken` route — putting it in the browser is exactly what the [closed-loop model](/docs/how-it-works) exists to prevent.