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

# Workflows

> Anatomy of a V-Run workflow: main code, tests, requirements, and config.yaml — the building blocks for AI-generated Python workflows running in the cloud.

A **workflow** is the fundamental unit in V-Run. It is a Python program that you write, test, and publish to the cloud. Each workflow is a top-level resource on your account and can be triggered manually, via API, or on a schedule.

## Anatomy of a workflow

Every workflow consists of four parts, each editable in the browser-based IDE:

| Part                  | Description                                                                                                      |
| --------------------- | ---------------------------------------------------------------------------------------------------------------- |
| **Main code**         | The Python script that runs when the workflow is triggered.                                                      |
| **Test code**         | pytest tests that validate your main code before deployment.                                                     |
| **Requirements**      | A `requirements.txt` listing PyPI packages your code depends on.                                                 |
| **Test requirements** | A `requirements-test.txt` listing additional packages needed only for testing (e.g. `pytest-mock`, `responses`). |
| **Config (YAML)**     | Declares inputs, outputs, triggers, timeout, and secrets.                                                        |

## Workflow lifecycle

A workflow moves through three statuses:

<Steps>
  <Step title="Draft">
    The workflow is being developed. You can edit code, run tests, and iterate freely. Draft workflows cannot be triggered externally — only the latest commit is reachable via API and schedule.
  </Step>

  <Step title="Published">
    The workflow has at least one commit and is live. API and scheduled triggers run the latest commit. You can keep editing in draft and commit again to publish a new version.
  </Step>

  <Step title="Archived">
    The workflow is retired. Schedules are paused, and external triggers are disabled. You can restore it to published at any time.
  </Step>
</Steps>

## Config YAML

The `config.yaml` file controls how a workflow behaves. Here is a complete example:

```yaml theme={null}
inputs:
  target_url:
    type: str
    required: true
    description: "URL to scrape"
  max_articles:
    type: int
    default: 5

outputs:
  results:
    type: file
    mime: "application/json"
    retention_days: 30

triggers:
  schedule:
    enabled: true
    cron: "0 9 * * *"
    timezone: "UTC"
    payload:
      target_url: "https://example.com"
      max_articles: 10
  api:
    enabled: true

required_env:
  - DATABASE_URL

secrets:
  - API_KEY

compute:
  timeout: 300
```

### Input types

Workflows accept typed inputs that render as a form in the editor and are passed as parameters to API triggers.

| Type        | Description           |
| ----------- | --------------------- |
| `str`       | Text string           |
| `int`       | Integer               |
| `float`     | Decimal number        |
| `bool`      | True / false          |
| `list`      | JSON array            |
| `dict`      | JSON object           |
| `file`      | Single file upload    |
| `file_list` | Multiple file uploads |

Each input can be `required` or optional with a `default` value.

### Compute limits

Control the resources allocated to each run:

* **timeout** — maximum execution time in seconds

## Execution

When a workflow runs, V-Run:

1. Spins up a secure cloud sandbox
2. Installs your requirements
3. Injects environment variables and secrets
4. Executes your main code with the provided inputs
5. Captures stdout, stderr, outputs, and cost metrics
6. Stores results in the run log

Every run is isolated — there is no shared state between executions.