Skip to main content
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 when both are provided
  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.

​
Example

​
Setup Desktop Parameters

In the desktop details page, click the “Edit” button in the top right, then configure parameters for Machine A: 
{
  "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: 
{
  "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: 
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"
    }
)

​
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 both run input values and desktop parameters are provided:
  1. Run-level values take priority and override desktop parameter defaults
  2. Desktop parameters still fill missing keys when run-level values are not provided
  3. Desktop parameters persist across runs and are not deleted after execution
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.

​
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