> ## 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.

# Desktop Parameters

> Machine-specific input values that automatically populate runs on specific desktops

Desktop Parameters allow you to configure machine-specific values that automatically populate workflows running on that desktop. This is useful for credentials, file paths, or IDs that are unique to each machine.

Despite the name, these are workflow input defaults tied to a machine, not display settings like resolution or scaling.

## The Problem

You have workflows that need different input values depending on which machine runs them:

* Different login credentials for each machine
* Machine-specific file paths or configurations
* Hardware-specific settings or IDs

You can't hardcode these in your workflow prompts because you don't always know which machine will be assigned to a run.

## The Solution

Set Desktop Parameters on each machine. When a run is assigned to that machine, the parameters automatically populate the effective input payload used by that run.

## How It Works

1. **Configure Parameters**: In the desktop details page, add parameters with names and values in the "Edit" dialog
2. **Use in Workflows**: Reference them in prompts using standard syntax: `{parameter_name}` or `{$sensitive_parameter}`
3. **Automatic Population**: When machine context is known, desktop parameters merge into the effective input payload used for validation and execution
4. **Storage Behavior**: Desktop parameters stay on the machine record; they are not copied into the run's stored input values unless you also pass them explicitly at run creation
5. **Priority**: Run-level input/sensitive values override desktop parameter defaults, and desktop parameters override pool parameter defaults
6. **Input Schema Compatibility**: You can mark desktop-parameter keys as required in workflow `input_schema`; when machine context is already known, those values participate in create-time validation automatically. For pool/auto assignment, required-key checks that may be satisfied by desktop parameters are deferred until a machine is assigned.

<Note>
  Need literal template-style text in the prompt instead of resolving a variable? Escape the opening delimiter:

  * `\{customer_name}` renders as literal `{customer_name}`
  * `\{{current_status}}` renders as literal `{{current_status}}`
  * `\{$support_pin}` renders as literal `{$support_pin}`
</Note>

## Example

### Setup Desktop Parameters

In the desktop details page, click the "Edit" button in the top right, then configure parameters for Machine A:

```json theme={null}
{
  "username": "user_machine_a",
  "api_url": "https://api-region-east.example.com",
  "database_path": "C:\\MachineA\\data.db"
}
```

### Use in Workflow

```
Log in to the system at {api_url} using username {username}.
Then open the database at {database_path} and run the query.
```

### Result

When this workflow runs on Machine A, the system automatically replaces:

* `{api_url}` → `https://api-region-east.example.com`
* `{username}` → `user_machine_a`
* `{database_path}` → `C:\\MachineA\\data.db`

## Sensitive Parameters

For sensitive values like passwords or API keys, mark parameters as "Sensitive":

1. In the edit desktop dialog, check the "Sensitive" checkbox when adding a parameter
2. Enter the sensitive value (it will be obscured as you type)
3. The value is stored securely in Basis Theory
4. Use in prompts with sensitive syntax: `{$password}`. Configure the key as `password`; the `$` prefix is only used when referencing it in prompts or input schemas.

### Example with Sensitive Parameters

Desktop parameters:

```json theme={null}
{
  "username": "admin_user",
  "password": "●●●●●●"
}
```

Workflow prompt:

```
Log in using {username} and password {$password}.
```

When machine context is known, the system securely resolves the stored password for validation and execution without exposing the plaintext value in the UI.

## Configuration via SDK

You can also set desktop parameters programmatically:

<CodeGroup>
  ```python Python theme={null}
  from cyberdesk import Cyberdesk

  client = Cyberdesk(api_key="your_api_key")

  # Update machine with parameters
  client.machines.update(
      machine_id="machine-id",
      machine_parameters={
          "username": "machine_specific_user",
          "config_path": "/opt/app/config.json"
      },
      machine_sensitive_parameters={
          "api_key": "actual_secret_value_123",  # Will be stored securely, only revealed at the last mile, never logged
          "password": "actual_password_456"
      }
  )
  ```

  ```typescript TypeScript theme={null}
  import { Cyberdesk } from 'cyberdesk';

  const client = new Cyberdesk({ apiKey: 'your_api_key' });

  // Update machine with parameters
  await client.machines.update('machine-id', {
    machine_parameters: {
      username: 'machine_specific_user',
      config_path: '/opt/app/config.json'
    },
    machine_sensitive_parameters: {
      api_key: 'actual_secret_value_123',  // Will be stored securely, only revealed at the last mile, never logged
      password: 'actual_password_456'
    }
  });
  ```
</CodeGroup>

## Best Practices

### ✅ Good Use Cases

* Machine-specific credentials or API keys
* Hardware-specific paths or configurations
* Region-specific URLs or endpoints
* Machine-assigned identifiers

### ❌ Avoid

* Workflow-specific logic (use input values instead)
* Data that changes frequently (parameters are relatively static)
* Large datasets (use file attachments instead)

## Priority and Overrides

When run input values, desktop parameters, and pool parameters are available:

1. **Run-level values take priority** and override desktop and pool defaults
2. Desktop parameters override pool parameters for the same key
3. Pool parameters fill missing keys only when the run explicitly selected the pool
4. Desktop parameters persist across runs and are not deleted after execution

<Info>
  An explicit run-level `__EMPTY__` value is treated as an intentional override, so it will suppress the desktop default for that key. Omitted/null/blank values still allow desktop defaults to populate.
</Info>

If you want the run to actively blank out the field instead of simply suppressing the desktop default, use [`__CLEAR__`](/concepts/clear-values).

For shared defaults across a group of desktops, see [Pool Parameters](/concepts/pool-parameters).

## Security

* Sensitive desktop parameters are stored in Basis Theory
* Values are never displayed in the UI after being saved
* Only parameter names are visible; values show as "●●●●●●"
* Sensitive values are securely resolved for validation/execution and never logged
* Desktop parameters are only accessible to runs on that specific machine