> ## Documentation Index
> Fetch the complete documentation index at: https://docs.cyberdesk.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Pool Parameters

> Shared workflow input defaults that apply when a run explicitly selects one or more desktop pools

Pool parameters are shared workflow input defaults stored on a desktop pool. When a run explicitly selects that pool, Cyberdesk adds the pool's parameters to the effective inputs used for validation and execution.

Use them for values that are true for every desktop in a pool:

* A tenant, workspace, or customer account ID
* A regional URL or environment name
* A shared folder path
* Shared credentials or API keys used by that pool

<Info>
  Pool parameters are not desktop display settings. They are workflow inputs that can satisfy prompt variables such as `{region}` or sensitive prompt variables such as `{$shared_api_key}`.
</Info>

## Mental Model

Think of pool parameters as the bottom layer of the run input stack:

1. Pool parameters fill in shared defaults when a selected pool provides them.
2. Desktop parameters override those defaults after Cyberdesk knows which desktop will run the workflow.
3. Run inputs override both when you pass an ad hoc value for a single run.

That means pool parameters are a good place for stable, shared context. They are not a good place for per-customer run data, one-off values, or anything that should change from run to run.

## When They Apply

Pool parameters apply only when the run explicitly selects a pool through `pool_ids` or the dashboard's pool-based machine selection.

They do not apply just because the assigned desktop belongs to a pool. If you choose a specific desktop for the run, Cyberdesk uses that desktop's parameters, but it does not automatically pull parameters from every pool that desktop belongs to.

This rule keeps runs predictable. A desktop can belong to multiple pools for routing, organization, or access control without accidentally changing workflow inputs.

## Basic Example

Suppose a pool named `West Coast Claims` has these pool parameters:

```json theme={null}
{
  "region": "us-west",
  "claims_portal_url": "https://claims-west.example.com",
  "tenant_id": "tenant_west_123"
}
```

Your workflow prompt can reference them like normal inputs:

```text theme={null}
Open {claims_portal_url}, log in to tenant {tenant_id}, and process the claim in the {region} region.
```

When you start a run and select the `West Coast Claims` pool, Cyberdesk includes those values in the effective input payload. You do not need to pass them again as run inputs unless you want to override them for that run.

## Priority And Overrides

When the same key exists in more than one place, Cyberdesk uses this priority order:

1. Run input or sensitive run input
2. Desktop parameter or sensitive desktop parameter on the assigned desktop
3. Pool parameter or sensitive pool parameter from the selected pool

For example:

```json theme={null}
{
  "selected_pool.pool_parameters.region": "us-west",
  "assigned_desktop.machine_parameters.region": "us-west-2",
  "run.input_values.region": "sandbox"
}
```

The workflow sees `sandbox`, because run input wins. If the run omits `region`, the workflow sees `us-west-2`. If the assigned desktop also omits `region`, the workflow sees `us-west`.

<Note>
  An explicit run-level `__EMPTY__` value is still an override. Omitted, null, or blank values allow lower-priority defaults to fill in. To actively clear a populated field during desktop entry, use [`__CLEAR__`](/concepts/clear-values).
</Note>

## Plain And Sensitive Values

Pool parameters come in two forms:

* Plain parameters are stored as normal structured values and referenced as `{key}`.
* Sensitive parameters are stored securely and referenced as `{$key}`.

For sensitive parameters, configure the key without the `$` prefix:

```json theme={null}
{
  "shared_api_key": "actual-secret-value"
}
```

Reference it in the workflow with the `$` prefix:

```text theme={null}
Authenticate with {$shared_api_key}.
```

The same convention applies to input schemas. Sensitive values are exposed to schema validation with `$`-prefixed root keys, such as `$shared_api_key`.

<Tip>
  Plain pool parameters can be strings, numbers, booleans, objects, or arrays. For nested prompt access like `{customer.portal.url}`, see [Structured Inputs](/concepts/structured-inputs).
</Tip>

## Multiple Selected Pools

A run can select more than one pool. Cyberdesk merges parameters from all selected pools before the run starts.

If two selected pools define the same parameter key, Cyberdesk rejects the run instead of choosing one silently:

```text theme={null}
Selected pools define duplicate parameter keys: region: Pool A (...), Pool B (...)
```

Rename or remove one of the duplicate keys before starting the run. This applies to both plain and sensitive pool parameter keys.

## Validation Behavior

When a run selects pools, Cyberdesk loads those pool parameters during create-time validation. This means required workflow inputs can be satisfied by selected pool parameters before a desktop has been assigned.

If the final desktop is not known yet, Cyberdesk still validates the concrete values it already has:

* Run inputs
* Sensitive run inputs
* Selected pool parameters
* Selected sensitive pool parameters

Required inputs that may come from desktop parameters can be deferred until execution time, after Cyberdesk assigns a desktop and can merge that desktop's values.

Validation runs again at execution time with the full effective payload. That final payload includes selected pool defaults, assigned desktop defaults, run inputs, and resolved sensitive values.

## Dashboard Setup

1. Go to the dashboard and open the Desktops area.
2. Click **View Pools**.
3. Create or edit a pool.
4. Add plain or sensitive pool parameters in the pool parameter editor.
5. Start a run and choose pool-based machine selection.
6. Select the pool whose defaults should apply.

If you start a run by choosing a specific desktop instead, pool parameters do not apply. Move shared values to [Desktop Parameters](/concepts/desktop-parameters) for that desktop, or pass them as run inputs.

## SDK Setup

<CodeGroup>
  ```typescript TypeScript theme={null}
  import { createCyberdeskClient } from 'cyberdesk';

  const client = createCyberdeskClient('your-api-key');

  await client.pools.update('pool-id', {
    pool_parameters: {
      region: 'us-west',
      claims_portal_url: 'https://claims-west.example.com',
      tenant_id: 'tenant_west_123'
    },
    pool_sensitive_parameters: {
      shared_api_key: 'actual-secret-value'
    }
  });
  ```

  ```python Python theme={null}
  from cyberdesk import CyberdeskClient, PoolUpdate

  client = CyberdeskClient(api_key="your-api-key")

  client.pools.update_sync(
      pool_id="pool-id",
      data=PoolUpdate(
          pool_parameters={
              "region": "us-west",
              "claims_portal_url": "https://claims-west.example.com",
              "tenant_id": "tenant_west_123",
          },
          pool_sensitive_parameters={
              "shared_api_key": "actual-secret-value",
          },
      ),
  )
  ```
</CodeGroup>

Then create a run with `pool_ids` instead of a specific `machine_id`:

<CodeGroup>
  ```typescript TypeScript theme={null}
  await client.runs.create({
    workflow_id: 'workflow-id',
    pool_ids: ['pool-id'],
    input_values: {
      claim_id: 'CLM-123'
    }
  });
  ```

  ```python Python theme={null}
  from cyberdesk import RunCreate

  client.runs.create_sync(
      RunCreate(
          workflow_id="workflow-id",
          pool_ids=["pool-id"],
          input_values={
              "claim_id": "CLM-123",
          },
      ),
  )
  ```
</CodeGroup>

## Choosing The Right Parameter Type

Use pool parameters when a value is shared across every desktop in a selected pool.

Use desktop parameters when a value depends on the assigned desktop, such as machine-specific credentials, local file paths, or desktop-specific account IDs.

Use run inputs when a value belongs to a specific run, such as a claim number, invoice ID, customer name, or any value that should be supplied by the caller.

## Common Gotchas

* Pool membership alone does not apply pool parameters; the run must explicitly select the pool.
* Selecting a specific desktop bypasses pool parameters.
* Duplicate keys across selected pools fail fast.
* Run inputs override pool parameters, even when the pool value exists.
* Sensitive parameter keys are configured without `$` and referenced with `$` in prompts and schemas.