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

# Configuration System

> Learn how to configure workflows using config fields, runtime inputs, and instructions.

Rilo's configuration system allows you to customize workflow behavior through three main mechanisms: **config fields**, **runtime inputs**, and **instructions**.

## Overview

Each workflow block can be configured with:

1. **Config Fields**: Static values that remain constant across executions
2. **Runtime Inputs**: Dynamic values provided by users at each execution
3. **Instructions**: Natural language descriptions of block logic

<Info>
  Config fields are stored permanently and used for every workflow execution. Runtime inputs are provided fresh each time a workflow runs.
</Info>

## Config Fields

Config fields are **static configuration values** that are set once and used for all workflow executions.

### When to Use Config Fields

Use config fields for values that:

* ✅ Don't change between executions
* ✅ Are set during workflow creation
* ✅ Apply to all workflow runs

**Examples:**

* Email addresses for notifications
* API endpoints or service URLs
* Threshold values (e.g., "minimum 50 upvotes")
* File references (templates, reference documents)
* Tool-specific settings

### Config Field Types

Rilo supports multiple field types:

| Type       | Description            | Example                        |
| ---------- | ---------------------- | ------------------------------ |
| `string`   | Text values            | Email addresses, IDs, names    |
| `number`   | Numeric values         | Thresholds, counts, limits     |
| `boolean`  | True/false flags       | Enable/disable options         |
| `list`     | Arrays of values       | Subreddits, recipients, URLs   |
| `json`     | Complex nested objects | Complex configurations         |
| `datetime` | Date/time values       | Schedules, deadlines           |
| `file`     | File references        | Templates, reference documents |

### Example: Config Fields

```json theme={null}
{
  "config_fields": [
    {
      "name": "notification_email",
      "value": "admin@example.com",
      "field_type": "string",
      "description": "Email address for notifications"
    },
    {
      "name": "min_upvotes",
      "value": 50,
      "field_type": "number",
      "description": "Minimum upvotes threshold"
    },
    {
      "name": "subreddits",
      "value": ["r/python", "r/programming"],
      "field_type": "list",
      "description": "Subreddits to monitor"
    }
  ]
}
```

<Warning>
  Complex objects should use the `json` field type.
</Warning>

## Runtime Inputs

Runtime inputs are **dynamic values** that users provide each time a workflow executes.

### When to Use Runtime Inputs

Use runtime inputs for values that:

* ✅ Change between executions
* ✅ Are provided by users at runtime
* ✅ Vary per workflow run

**Examples:**

* Search queries
* File uploads
* Date ranges
* User selections

### Runtime Input Configuration

Runtime inputs are configured in **Start blocks**:

```json theme={null}
{
  "block_type": "start",
  "config_fields": [
    {
      "name": "search_query",
      "value": null,
      "field_type": "string",
      "description": "Search query to use for this execution"
    },
    {
      "name": "input_file",
      "value": null,
      "field_type": "file",
      "description": "File to process in this execution"
    }
  ]
}
```

<Info>
  Runtime inputs with `value: null` indicate that the user must provide a value at each execution. If a value is provided, it becomes the default.
</Info>

## Instructions

Instructions are **natural language descriptions** of what a block should do.

### Purpose of Instructions

Instructions serve multiple purposes:

* **Documentation**: Explain what the block does
* **Code Generation**: Guide the AI agent in generating code
* **Verification**: Help verify block configuration

### Writing Good Instructions

<AccordionGroup>
  <Accordion title="Be Specific">
    Instead of "Process data", write "Filter posts with 50+ upvotes from the last 24 hours".
  </Accordion>

  <Accordion title="Include Context">
    Mention relevant details: "Send email to [admin@example.com](mailto:admin@example.com) with daily summary".
  </Accordion>

  <Accordion title="State What, Not How">
    Focus on the goal, not implementation: "Generate 5 quotes" not "Call LLM API with prompt".
  </Accordion>

  <Accordion title="Keep It Concise">
    Instructions should be 2-3 lines max. Use config fields for detailed settings.
  </Accordion>
</AccordionGroup>

### Example: Instructions

**Start Block:**

```
Daily at 9 AM. User provides a search query for each run.
```

**Code Block:**

```
- Scrape Reddit posts matching the search query
- Filter posts with 50+ upvotes
- Return top 10 posts
```

**HITL Block:**

```
Review scraped posts. User can approve or reject each post before sending email.
```

## Configuration Best Practices

### Config Fields vs Runtime Inputs

<Tabs>
  <Tab title="Use Config Fields For">
    * Email addresses
    * API endpoints
    * Thresholds and limits
    * File templates
    * Tool settings
    * Default values
  </Tab>

  <Tab title="Use Runtime Inputs For">
    * User-provided queries
    * File uploads
    * Date ranges
    * User selections
    * Dynamic parameters
  </Tab>
</Tabs>

### File Configuration

Files can be used in both config fields and runtime inputs:

**Config Field (Permanent):**

```json theme={null}
{
  "name": "template_file",
  "value": {
    "type": "file",
    "filename": "template.xlsx",
    "s3_location": {...}
  },
  "field_type": "file",
  "description": "Template file for document generation"
}
```

**Runtime Input (Per Execution):**

```json theme={null}
{
  "name": "input_data",
  "value": null,
  "field_type": "file",
  "description": "Data file to process"
}
```

<Info>
  Files uploaded as config fields are stored permanently. Files uploaded as runtime inputs are provided fresh each execution.
</Info>

## Configuration Workflow

### 1. Create Workflow

Describe your workflow in natural language:

```
"Scrape Reddit posts daily and email summary to admin@example.com"
```

### 2. AI Agent Creates Blocks

The agent automatically:

* Creates blocks with appropriate types
* Sets up config fields based on your description
* Generates instructions for each block

### 3. Verify Configuration

Review and adjust:

* **Config fields**: Add or modify static values
* **Runtime inputs**: Configure what users provide
* **Instructions**: Refine block descriptions

### 4. Execute

* Config fields are used automatically
* Runtime inputs prompt users for values
* Instructions guide code generation

## Advanced Configuration

### JSON Config Fields

For complex configurations, use the `json` field type:

```json theme={null}
{
  "name": "filter_config",
  "value": {
    "min_upvotes": 50,
    "max_age_days": 7,
    "subreddits": ["r/python", "r/programming"],
    "keywords": ["tutorial", "guide"]
  },
  "field_type": "json",
  "description": "Complex filtering configuration"
}
```

### Conditional Configuration

Some blocks support conditional logic based on config fields:

```python theme={null}
# In block code
min_upvotes = config.get("min_upvotes", 10)
if min_upvotes > 50:
    # Use stricter filtering
    ...
```

## Troubleshooting

<AccordionGroup>
  <Accordion title="Config field not being used">
    * Verify the field name matches what the code expects
    * Check that the field type is correct
    * Ensure the value is set (not null for required fields)
  </Accordion>

  <Accordion title="Runtime input not prompting">
    * Verify the Start block has the config field
    * Check that `value` is `null` (not a default value)
    * Ensure the workflow is in "verified" state
  </Accordion>

  <Accordion title="Instructions unclear">
    * Be more specific about what the block should do
    * Include relevant context and constraints
    * Reference config fields by name when relevant
  </Accordion>
</AccordionGroup>

## Related Features

* [Code Generation](/features/code-generation) - How config fields are used in generated code
* [Graph Mode](/features/graph-mode) - Visual configuration in the graph editor
* [Human-in-the-Loop](/features/human-in-the-loop) - Configuring review blocks

***

<Note>
  Configuration is a key part of workflow creation. Take time to set up config fields and runtime inputs correctly for the best workflow experience.
</Note>