--- url: https://docs.puppetflow.com/guide/introduction.md --- # Introduction Puppetflow is a source-available, self-hostable browser automation platform built for the scenarios that actually break: 2FA walls, email verification, CAPTCHA gates, human approval steps, and anything that requires more than a simple headless script. ## Why Puppetflow? Most browser automation tools work until they hit real-world authentication. Puppetflow was designed from the start to handle these cases: * **TOTP / 2FA** - Compute one-time passwords at runtime from stored secrets or, on Pro and above, 1Password vault items. * **Email verification** - Receive emails on custom domains, match them with rules, and extract verification codes directly in your flow. * **Human approval** - Pause a running flow and wait for a team member to approve via Slack, Discord, or Telegram before continuing. * **Full observability** - Live-stream the browser session, record MP4 videos, collect screenshots and downloaded files as artifacts. ## How it works You can write flows in JavaScript with Puppeteer and Puppetflow's **magic methods** (`$gotoUrl`, `$gotoTab`, `$fillInput`, `$vars`, `$waitForEmail`, `$waitHumanValidation`, …). ```js async function run($page, $input) { await $gotoUrl('https://app.example.com/login', 'Login'); await $fillInput('#email', 'foo@example.com'); await $fillInput('#password', 'my_password'); await $clickElement('#login-btn'); // Compute a fresh TOTP code from the stored secret await $fillInput('#otp', $vars('variable-id')); // Pause until a matching verification email arrives const email = await $waitForEmail('watcher-id'); // Follow the link extracted from the email body await $gotoUrl(email.parsed, 'Email link'); await $screenshot('logged-in'); return $generateResponseSuccess('Login complete'); } ``` Flows run inside a sandboxed Puppeteer environment, optionally connected to a remote Chromium instance through Pinokio, the bundled browser gateway. Every run produces structured output, console logs, and artifacts. You can build flows in two ways: * **[Nodal flows](/guide/nodal-flows)** - Visual browser automations built from connected steps. * **[Code flows](/guide/code-flows)** - JavaScript automations that use Puppeteer and Puppetflow magic methods. ## Key concepts | Concept | Description | | --- | --- | | **[Flow](/guide/flows)** | A code or nodal automation with settings, triggers, and actions. | | **[Nodal flow](/guide/nodal-flows)** | A visual automation built from connected steps. | | **[Code flow](/guide/code-flows)** | A JavaScript automation with direct browser control. | | **[Snippet](/guide/flows#snippets)** | A reusable code or nodal function callable from flows and other snippets. | | **[Run](/guide/flow-runs)** | A single execution of a flow, with status, output, logs, and artifacts. | | **[Variable](/guide/variables)** | A stored value (text, secret, JSON, TOTP, vault) available at runtime. | | **[Trigger](/guide/triggers-actions#triggers)** | A webhook or cron schedule that starts a flow automatically. | | **[Action](/guide/triggers-actions#actions)** | A post-run webhook that fires with the run result. | | **[Blueprint](/guide/flows#blueprints)** | A reusable package of flows and snippets from the public blueprints or a private repository. | | **[Private library](/guide/workspaces#private-libraries-tab)** | A workspace-scoped Git repository that adds internal blueprints to the blueprints store. | | **[Mailbox](/guide/mailboxes)** | An email address on a custom domain that receives emails for your flows. | | **[Watcher](/guide/mailboxes#mailbox-watchers)** | A rule set attached to a mailbox that matches incoming emails for a flow. | | **[Channel](/guide/channels)** | A Slack, Discord, or Telegram channel for notifications and human approval. | | **[MCP server](/guide/mcp)** | Exposes selected flows as tools for AI clients such as Claude, ChatGPT, and Cursor. | | **[Workspace](/guide/workspaces)** | A shared space where team members collaborate on flows and resources. | | **[Access control](/guide/users-teams-access)** | Roles, teams, ownership, and resource sharing within a workspace. | ## Next steps * Follow the [Cloud Quick Start](/guide/quick-start) to create a managed environment without deploying infrastructure. * Read the [Flows](/guide/flows) guide to understand the core building block. * Browse the [Flow API reference](/reference/magic-methods) for the full list of magic methods. * Prefer your own infrastructure? Start with the [Self-Hosted Quick Start](/self-hosting/quick-start). --- --- url: https://docs.puppetflow.com/guide/quick-start.md --- # Cloud Quick Start Puppetflow Cloud is the fastest way to start. Your environment is provisioned and managed for you, so you can build automations without operating Docker, PostgreSQL, Redis, browser workers, TLS certificates, or deployment updates. ## Why start with Cloud * **Ready-to-use environment.** Choose a cloud address and open Puppetflow when provisioning completes. * **Managed operations.** Puppetflow manages the hosted environment and monitors its allocated capacity. * **Simple lifecycle.** Plans, billing, and environment access stay together in your Puppetflow account. * **Room to grow.** Start with a trial, then choose the capacity and support level that fit your workflows. Cloud and self-hosted deployments use the same automation toolkit, including code and nodal flows, triggers, run history, live browser control, human validation, notifications, and API access. ## 1. Create a Cloud environment Open the [Puppetflow pricing page](https://puppetflow.com/pricing), choose a Cloud plan, and create your account. During checkout, choose the address for your environment. You can start with the trial plan before choosing a paid subscription. ## 2. Open Puppetflow Go to your Puppetflow account and select the Cloud instance. Its status changes from provisioning to active when the environment is ready. Click **Open environment** to continue. ## 3. Create your first flow 1. Open **Flow Explorer** in the sidebar. 2. Click **New Flow** and select **Raw Code**. 3. Give it a name and paste this script: ```js async function run($page, $input) { await $gotoUrl('https://example.com', 'Default'); await $screenshot('homepage'); return $generateResponseSuccess('Done', { title: await $page.title() }); } ``` 4. Click **Run Flow** to execute it. 5. Open the run to see the console logs, output, and the screenshot artifact. ## 4. Explore * Add [variables](/guide/variables) to store credentials securely. * Set up a [webhook trigger](/guide/triggers-actions) to start flows from external systems. * Connect a [notification channel](/guide/channels) for Slack/Discord/Telegram alerts. * Configure a [mailbox](/guide/mailboxes) to receive and process emails. * Import a ready-made automation from the [blueprints store](/guide/flows#blueprints). * Browse the [Flow API reference](/reference/magic-methods) for all available magic methods. ## Prefer your own infrastructure? Use the [Self-Hosted Quick Start](/self-hosting/quick-start) to understand the deployment path, then follow the full installation guide. --- --- url: https://docs.puppetflow.com/guide/flows.md --- # Flows A flow is an automation that runs in a sandboxed browser environment. It is the core unit of work in Puppetflow. ## Creating a flow Open **Flow Explorer** and click **New Flow**. Choose a source: * **Visual Builder** - Build a nodal flow with nodes and connections. * **Raw Code** - Write the script in the built-in Monaco editor. * **Git Repository** - Link a file from a repository and synchronize it on push or tag events. Every flow has a **name** and a generated **ID** used for API and CLI access. Flows can be organized into **folders**. ## Flow types Puppetflow supports two flow types. | Type | Best for | | --- | --- | | **[Nodal flow](/guide/nodal-flows)** | Visual automation steps that are easy to inspect and modify. | | **[Code flow](/guide/code-flows)** | Custom JavaScript and direct Puppeteer control. | Both types support the same run options, artifacts, recordings, and API responses. ## Snippets Snippets are reusable functions that can be called from code flows, nodal flows, and other snippets. Each snippet has a generated ID, used with a `$$` prefix, and an optional comma-separated argument list. When creating a snippet, choose one of two immutable types: | Type | Description | | --- | --- | | **Nodal snippet** | Build the function visually with nodes and expressions. | | **Code snippet** | Write the function body directly in JavaScript. | Both types expose the same callable interface. For example, a snippet with ID `snip_k8Zt3xQ9mA2f` and arguments `street, city` can be called from code: ```js const address = await $$snip_k8Zt3xQ9mA2f(street, city); ``` Inside the snippet, named arguments are available through `$input`, such as `$input.street` and `$input.city`. ### Nodal snippets A nodal snippet starts at the fixed **SNIPPET** node instead of a flow **RUN** node. Connect actions from this node to define the function body. Assign values to `$output` when the caller needs a result. There is no dedicated Return node. The nodal toolbox lists accessible snippets in the **Snippets** category. Adding one creates a call node with an input for each declared argument. This works for code and nodal snippets, so callers do not need to know how the snippet was implemented. ### Local functions Nodal flows and nodal snippets can also declare private functions from the **Local Functions** toolbox category. A declared function: * has optional named arguments available through `$input`, * can be called from `RUN`, `TERMINATE`, a snippet body, or another local function, * can call itself recursively, * returns its `$output` object to the caller. Local functions belong only to their containing graph. Use a snippet when the function needs to be reused by other flows or snippets. ### Import and export Code snippets are exported as JavaScript files. Nodal snippets are exported as versioned JSON files containing the graph and compiled code required for portability. The snippet importer accepts both formats. Changing a snippet label does not change its ID or usages. Blueprint snippets remain locked to their source and can be duplicated when an editable copy is needed. ## AI models AI models are reusable resources exposed to code and nodal flows through their AI integration. Each `AiModel` contains exactly one provider model. Provider credentials remain in the [AI integration](/guide/integrations#ai-integrations). To create one: 1. Connect OpenAI, Gemini, Anthropic Claude, or Mistral under **Integrations**. 2. Open **AI Models** and click **New Model**. 3. Select the AI integration and one discovered provider model. 4. Enter a descriptive model name. 5. Choose its owner, visibility, and optional group. The **Vision** filter shows models with vision support. `$aiControl` requires one because it sends browser screenshots to the provider. `$aiMessage` uses text-capable models. An AI model receives an `AiModel.id` starting with `aim_`. IDs are resolved with the permissions of the user who triggered the run. Both the AI model and its integration must be active and visible to that user. Renaming a model does not change its ID; deleting one leaves its references unresolved. See [Code Flows](/guide/code-flows#using-ai) for JavaScript examples and [Nodal Flows](/guide/nodal-flows#using-ai) for the visual nodes. ## Data Tables Data Tables store structured data that flows can read and update. Open **Data Tables** from the main navigation, below **Snippets**. The page has two panes: 1. **Data Tables** lists the tables you can access. 2. **Data** displays the selected table and its rows. ### Access A data table contains its settings, columns, and rows. Visibility can be owner-only, team-wide, or workspace-wide. Visibility controls read access. Changing settings or columns and writing rows require management access. Flow runs use the permissions of the user who triggered the run. A node can therefore be valid for one user and fail for another user who cannot access the same data table. ### Tables and columns Each table starts with three system columns: | Column | Description | | --- | --- | | `id` | Generated numeric row ID. | | `created_at` | Date and time when the row was inserted. | | `updated_at` | Date and time of the most recent update. | System columns are read-only. Custom columns support `string`, `number`, `boolean`, and `datetime`. A custom column can be renamed, moved, or deleted, but its type cannot be changed after creation. Deleting a column permanently removes its values. Deleting a table permanently removes the table and every row it contains. ### Editing data Use **Add Row** to insert an empty row. Custom columns are nullable, so a row does not need a value for every column. * Single-click a cell to focus it. * Double-click an editable cell to change its value. * Clear a string, number, or datetime editor to store `NULL`. * Boolean cells accept `NULL`, `TRUE`, or `FALSE`. * Copy a focused cell with Cmd/Ctrl + C. * Paste into a focused custom cell with Cmd/Ctrl + V. The pasted value is checked against the column type. * Drag a header border to resize a column. * Use the column menu to rename or delete a custom column. The first column selects rows. Use its header checkbox to select the current page, then delete or export the selection. ### Filtering and export Column filters run on the server and work with pagination. Available operators depend on the column type. Active filters can be combined and cleared from the data grid. Tables can be exported as CSV, JSON, or XML. Export every row, the filtered result, or selected rows. Imports support the same formats and append rows. Drop a file into the modal or paste its content. Headers and object keys match existing columns; blank or missing values become `NULL`. ### Using Data Tables in flows The **Data Tables** toolbox category appears before **Utilities** and contains nodes for row queries, row mutations, and table management. Operations on an existing table use one searchable **Data Table** selector, or an expression that resolves to its stable `tableId`. For code flows and Code nodes, type a `$dataTable*` helper and open autocomplete inside the quoted `tableId` argument. The editor displays table names while inserting stable IDs. Create and list are workspace-level management operations, so they do not require a table selector. Flow Inputs support the `datatable` resource type. * Form mode provides a searchable Data Table selector. * JSON mode stores `${dataTables.}` and autocompletes names while inserting stable IDs. * Code blueprints use `// @input table [datatable]: "${dataTables.dtbl_...}"`. See [Data Table nodes](/guide/nodal-flows#using-data-tables) for the visual workflow and [Data Table Flow API](/reference/magic-methods#data-tables) for JavaScript signatures, filters, options, and return values. ## Flow settings | Setting | Description | | --- | --- | | **Timeout (seconds)** | Maximum run time. | | **Max Retries** | Number of automatic retries on failure. | | **Proxy routing** | Connect directly, use one specific proxy, or rotate through a filtered round-robin pool. | | **Viewport** | Custom viewport width and height (overrides workspace defaults). | | **Output & artifacts** | Configure screenshots, downloads, and recordings in output. | | **Run retention limit** | Maximum number of runs to keep. | | **Visibility** | Owner, Team, or Workspace. Change it from the flow menu or the editor header badge. | Each trigger has its own active toggle. Inactive triggers ignore webhook requests or schedules. ### Proxy routing Proxy routing has its own section in flow settings: * **None** connects directly. * **Specific** always uses the selected proxy when it is available to the user starting the run. * **Auto (round-robin)** rotates through the proxies available to that user. Auto pools can be filtered by proxy country and group. Conditions inside one rule group use `AND`; separate groups use `OR`. For example, the following rules select French or US proxies from the Managed group: ```text (Country = FR AND Group = Managed) OR (Country = US AND Group = Managed) ``` The editor shows a live expression summary. If no available proxy matches the configured rules when a run starts, the run is rejected instead of falling back to an unfiltered proxy. ## Folders Flows can be organized into nested folders. Drag and drop flows and folders to reorganize. Each folder has a sort order and supports full breadcrumb navigation. ## Blueprints Blueprints are reusable packages published through the blueprints store. A blueprint can contain one or more flows and snippets under a single namespace. Open the blueprints store from the flow or snippet area. Filter by type, category, text, popularity, downloads, likes, date, or local usage. Categories include **Auth**, **Scraping**, **Files**, **Notifications**, **Data**, **Fun**, **Form**, and **Social**. When importing a blueprint, you can: * select which flows and snippets to import, * override the imported flow name, description, visibility, owner, or team, * override snippet label, description, group, scope, owner, or team, * import code or nodal flows and snippets, * keep the imported item linked to its blueprint source for update checks. Imported flows and snippets are locked to their blueprint source. This prevents accidentally editing a shared blueprint copy in place. Duplicate an imported item if you need a fully editable local version. ### Blueprint updates Imported items remain linked to their blueprint source. Puppetflow can then notify you when an update is available. To distribute internal blueprints without publishing them to the public store, see [Private Libraries](/guide/workspaces#private-libraries-tab). ## Running a flow Click **Run Flow** in the flow editor to trigger a manual run. You can also: * Set up [triggers](/guide/triggers-actions) for automatic runs. * Use the [REST API](/reference/api) to trigger programmatically. * Run from the CLI with `php artisan flow:run --id=flow_k8Zt3xQ9mA2f`. ## Icons Each flow can have a custom icon displayed in the explorer and listings. Options include emoji, a color swatch, or an uploaded image. --- --- url: https://docs.puppetflow.com/guide/nodal-flows.md --- # Nodal Flows Nodal flows let you build browser automations visually. Each node represents an action, and connections define the run order. Use a nodal flow when: * the automation is mostly a sequence of browser actions, * non-developers need to understand or edit it, * you want to organize the flow visually, * you start from a nodal blueprint. ## Building a nodal flow Create a flow and select **Visual Builder**. Use the visual editor to add nodes, connect them, configure their settings, and define their inputs. See the complete [canvas shortcut reference](/guide/canvas-shortcuts) for keyboard commands, selection gestures, viewport controls, and advanced move tools. Nodal flows support: * manual runs and triggers, * screenshots, downloads, and video recordings, * blueprint imports and updates, * reusable code and nodal [snippets](/guide/flows#snippets), * private local functions with optional arguments and recursion, * MCP exposure, * REST API triggers. Importing a nodal blueprint recreates its visual graph and keeps it linked to the blueprint source. Imported items are read-only; duplicate one to create an editable copy. ## Core visual nodes The editor includes structural nodes in addition to nodes generated from the Flow API: | Node | Purpose | | --- | --- | | **RUN** | Entry point of the main flow. | | **TERMINATE** | Cleanup branch (shown as **FINALLY**) that runs after the main flow, including after failures. Off by default: enable **FINALLY node** in the flow settings to show and run it. While off, the branch is hidden and skipped at run time but kept for later. | | **Code** | Run custom asynchronous JavaScript inside the generated flow. | | **Set variable** | Add one or more values to the current flow state. | | **Set Output** | Add values to the final `$output` object. | | **Meta** | Add searchable metadata to the run context. | | **If / Else** | Route execution through a `true` or `false` output. | | **Loop** | Repeat a branch over items or while a condition applies. The active iteration is available through `$loop`. | | **Filter** | Keep array items that satisfy an expression. | | **Limit** | Select a range of items from an array. | | **Merge** | Rejoin branches using append, object assignment, or first non-empty behavior. | | **No-op** | Join or organize connections without performing an action. | | **Declare Function** | Define a private function subgraph and expose a callable node in Local Functions. | | **Sticky Note** | Add non-executable context to the canvas. | Nodes created from Flow API helpers use the same signatures and behavior as their code equivalents. See the [Flow API reference](/reference/magic-methods) for their parameters and return values. ## Referencing data in expressions Node parameters accept expressions wrapped in {{ }}. Run data is reachable only through `$run` or through a named node: | Expression | Value | | --- | --- | | {{ $run.$input.email }} | Flow input, as received by **RUN**. | | {{ $run.$output.total }} | Values added so far with **Set Output**. | | {{ $run.$context.flow_id }} | Run context. | | {{ $run.myVar }} | A variable defined upstream with **Set Variable** or a **Code** node. Variables accumulate from node to node. | | {{ $('Load Cookies').$result }} | The state recorded after a specific node, by its label. | | {{ $loop.item }}, {{ $loop.index }} | Current iteration inside a **Loop**. | | {{ $capture.response.body.contentJson }} | Current request and response pair inside a **Sniff Network** callback. See [`$sniffNetwork`](/reference/flow-api/page-evaluation#sniff-network). | Bare identifiers such as {{ $input.email }} or {{ myVar }} are not defined in expressions. **Code** nodes run plain JavaScript and expose the same data through `$run`; assign to `$run.myVar` to make a value available to following nodes. The expression and Code node editors provide context-aware autocomplete: * **Suggested** contains `$run`, `$now`, `$if`, `$ifEmpty`, and the locals valid at the current node. * **Earlier nodes** contains `$('Node name')`, `$nodes`, and known output paths from reachable upstream nodes. * **Methods** contains Puppetflow helpers, DateTime methods, object members, and JavaScript symbols. * **Tools** contains resource-aware entries for variables, channels, AI models, Data Tables, mailbox watchers, snippets, tabs, stopwatches, network profiles, and cookie jars. Type `$page.` to browse the Puppeteer API. Autocomplete uses both the installed Puppeteer declarations and the latest static or runtime node-output preview. Entries outside the current graph scope are not suggested. ## Inspecting run data Open a node to inspect its **Before** and **After** data. Runtime values come from the latest manual run launched by the current user. When no runtime snapshot is available, the editor shows a static preview inferred from the graph and the flow inputs. The node footer identifies the current data source. * **Use static preview** returns to inferred data. This is useful after changing flow inputs because existing snapshots keep their original inputs. * **Use run #N** restores runtime data. The choice is remembered across nodes. The JSON view of **Before** lets you select an upstream node. The immediately preceding node uses `$run`; older nodes use `$('Node name')`. The **After** panel is read-only and shows the current node output. Nodes can execute more than once inside a **Loop** or a **Sniff Network** callback. When at least two runtime snapshots exist, an `N of M` selector appears in the JSON view. Use it to inspect each retained `$loop.item` or `$capture` value independently. The first execution is selected by default. The Schema view keeps all upstream nodes expanded as separate roots and shows their final state. Iteration selection is available only in the JSON view. Execution histories are bounded. By default, Puppetflow keeps the first three executions of each node within an overall size budget. The node's final state remains available. Truncated arrays and objects show `[Preview items omitted]` or `[Preview properties omitted]`. Network capture bodies are stored separately and loaded when a node references them. Expressions using `$capture.response.body` show `Loading captured responses…` while they load. If a run exceeds the accepted preview size, the node footer reports it and the editor falls back to the static preview. Self-hosted instances can adjust the [nodal run preview limits](/reference/configuration#nodal-run-previews). ## Reusable functions The **Snippets** toolbox category contains the snippets available to the current user. Each snippet appears as its own node with configurable inputs matching its declared arguments. Code and nodal snippets behave identically when called from a nodal flow. The **Local Functions** category is for functions private to the current graph. Add **Declare Function**, configure its name and optional arguments, then add its call node wherever it is needed. Local functions can call other local functions or themselves recursively. Function arguments are exposed through `$run.$input` inside the function. Values added with **Set Output** are returned to the caller. Functions do not use a Return node. ## Using AI The **AI** toolbox category contains: * **AI Message** - Sends a text prompt through a configured AI model. It supports system instructions, message history, sampling controls, token limits, and text or structured JSON output. * **AI Control** - Uses a vision-capable model to inspect the current browser screenshot and execute restricted browser actions until an objective completes or reaches its iteration limit. Before adding either node, connect an [AI integration](/guide/integrations#ai-integrations) and configure an [AI model](/guide/flows#ai-models) containing one provider model. AI Control requires a vision-capable model. AI Control can optionally save each inspected screenshot as a run artifact. Its output includes the final status, message, iteration count, executed actions, AI model, and usage information. ## Using Data Tables Open the **Data Tables** category in the toolbox to add a Data Table operation. It appears before **Utilities**. Existing-resource nodes have one searchable Data Table selector that shows table names and inserts stable `tableId` values. The selector can also use an expression. Data Table nodes use the same operations as the code API: | Node | Purpose | | --- | --- | | **Insert Row** | Insert one row and return the stored row. | | **Update Row(s)** | Update every row matching the filters. | | **Upsert Row(s)** | Update matching rows, or insert one row when no match exists. | | **If Row Exists** | Continue through the `true` or `false` output. | | **If Row Does Not Exist** | Continue through the `true` or `false` output. | | **Get Row(s)** | Return matching rows with sorting and limits. | | **Delete Row(s)** | Delete matching rows. | | **Create Data Table** | Create a table and its custom columns. | | **Delete Data Table** | Permanently delete a table and its rows. | | **List Data Tables** | Return accessible tables and their columns. | | **Update Data Table** | Update a table's name, description, visibility, owner, or team. | **Create Data Table** and **List Data Tables** are workspace-level management nodes and do not require a selected table. Create accepts custom columns plus ownership and visibility options. Delete and update operate directly on the selected table. ### Row values The Values field is generated from the selected table. Each custom column has an input matching its type. You may leave nullable columns empty. Switch the field to JSON or Expression when values must be computed dynamically. JSON values are keyed by column name: ```json { "email": "person@example.com", "score": 42, "active": true, "processed_at": "2026-08-27T20:30:00Z" } ``` ### Filters Each filter contains a column name, a condition, and an optional comparison value. Add more than one filter when the query needs several conditions. Use `allConditions` to require every filter or `anyCondition` to accept a row matching at least one filter. Conditions such as `isEmpty`, `isNotEmpty`, `isTrue`, and `isFalse` do not need a comparison value. The form selects valid conditions based on the column type. Switch to Expression to supply the complete filter array dynamically. ### Mutation safeguards **Update Row(s)** requires at least one filter unless **Update all** is enabled explicitly. **Upsert Row(s)**, both existence nodes, and **Delete Row(s)** always require filters. Enable **Dry run** on update, upsert, or delete nodes to preview the before and after rows without saving the operation. Table deletion has no dry-run mode. ### Conditional outputs **If Row Exists** and **If Row Does Not Exist** have `true` and `false` outputs. Connect both outputs as you would on an **If / Else** node. The branches can join again later in the flow. For the complete filter format and all node options, see the [Data Table Flow API reference](/reference/magic-methods#data-tables). ## Run snapshots The Visual snapshot in run details uses the same nodal canvas in read-only mode. It preserves local-function subgraphs and snippet calls, highlights the currently active path, and displays traversal counts when loops or repeated function calls execute an edge more than once. --- --- url: https://docs.puppetflow.com/guide/code-flows.md --- # Code Flows Code flows are JavaScript automations with direct access to Puppeteer and Puppetflow's [magic methods](/reference/magic-methods). ## Writing a code flow A code flow exports an async `run` function that receives the Puppeteer page, the input object, the run context, and the CDP session: ```js async function run($page, $input, $context, $client) { await $gotoUrl('https://example.com', 'Default'); return $generateResponseSuccess('Done'); } ``` `$page` is a proxy to the active Puppeteer [Page](https://pptr.dev/api/puppeteer.page). `$context` contains run metadata such as `run_id` and `flow_id`. `$client` is the active tab's [CDP session](https://pptr.dev/api/puppeteer.cdpsession). Both trailing parameters can be omitted. See [Flow Objects](/reference/flow-api/globals) for details. An optional `terminate` function runs after `run`, including when it fails. It receives the response produced by `run` as `$output` (`$output.status` is `success` or `error`): ```js async function terminate($page, $input, $output, $context, $client) { if ($output.status === 'error') await $screenshot('failure'); } ``` See [Working with Downloaded Files](/guide/downloaded-files) for the built-in PDF and archive tools. ## Editor assistance The Monaco editor provides JavaScript and TypeScript language assistance without changing the JavaScript executed by the flow. Autocomplete, signatures, hover information, and diagnostics run in a separate browser worker. Type `$` to browse suggestions grouped by purpose: * **Suggested** contains the values and helpers most often used in the current context, such as `$input`, `$page`, `$now`, `$if`, and `$ifEmpty`. * **Methods** contains every Puppetflow helper exposed to code flows, JavaScript symbols, and object methods. * **Tools** contains resource-aware helpers and values for variables, notification channels, AI models, Data Tables, mailbox watchers, snippets, tabs, stopwatches, network profiles, and cookie jars. Type `$page.` or `$client.` to browse the Puppeteer `Page` and CDP APIs. The available members and signatures come from the Puppeteer version installed with Puppetflow. Resource suggestions display readable names but insert stable IDs. Type `$$` to insert an accessible snippet. ## Input Code flows receive input through `$input`: * **Default inputs** - JSON defined in the flow settings. * **Manual input** - JSON entered before a manual run. * **Trigger input** - Data sent by a webhook or cron trigger. * **API input** - JSON sent through the REST API. Variables in input values use the `${vars.ID}` syntax. Blueprint code flows can declare resource inputs. For example: ```js // @input model [ai-model] // @input table [datatable] ``` The generated input value keeps the resource-reference syntax and resolves to the configured resource ID: ```json { "model": "${aiModels.ai-model-id}", "table": "${dataTables.data-table-id}" } ``` In the Flow Inputs form, Data Table values use a searchable selector showing the table name, visibility, and column count. In JSON mode, `${dataTables.` provides table-name autocomplete while inserting the stable ID. At execution, `${dataTables.}` becomes the plain table ID. ## Output The value returned by `run` becomes the run output: ```js $setOutput('source', 'invoice-import'); return $generateResponseSuccess('Operation completed', { invoiceId: '12345', amount: 99.99, }); ``` Use `$generateResponseError()` to return an error. Keys added with `$setOutput()` are included in the response. ## Calling snippets Active snippets available to the flow are exposed as async functions using their `$$id`. Arguments are positional and follow the order declared by the snippet: ```js const address = await $$snip_k8Zt3xQ9mA2f(street, city); ``` The same syntax calls code and nodal snippets. A nodal snippet receives the declared arguments through `$input` and returns its `$output` object. See [Snippets](/guide/flows#snippets) for creation, local functions, and import or export details. ## Using AI Configure an [AI integration](/guide/integrations#ai-integrations) and an AI model containing one provider model. Pass its `AiModel.id`, which starts with `aim_`, to `$aiMessage` or `$aiControl`. Use `$aiMessage` for text generation: ```js const response = await $aiMessage( 'ai-model-id', 'Extract the company name from this text: ' + $input.text, { system: 'Return only the company name.', temperature: 0.2, max_tokens: 100, }, ); $setOutput('company', response.text); ``` Set `outputMode` to `json` for a JSON object, or to `schema` with a JSON Schema in `schema` for constrained structured output. Previous messages can be passed as `{ role, content }` objects in `messages`. Use `$aiControl` with a vision-capable model to inspect and operate the current browser page: ```js const control = await $aiControl( 'ai-model-id', 'Open the account menu and sign out', { maxIterations: 8, screenshotQuality: 65, persistScreenshots: false, allowPuppeteerFallback: true, }, ); if (control.status !== 'success') { return $generateResponseError(control.message); } ``` AI Control executes only its restricted Puppetflow browser actions. When `allowPuppeteerFallback` is enabled, it may use restricted Puppeteer actions after a Puppetflow action fails, or use a coordinate click for a purely visual target. Page content is treated as untrusted data. See the [Flow API reference](/reference/magic-methods#ai) for parameters, return values, and limits. ## Repository linking A code flow can be linked to a file in a Git repository. Choose the integration, repository, branch, file path, and sync trigger. Repository-linked code is read-only in Puppetflow and updates on the selected `push` or `tag` event. --- --- url: https://docs.puppetflow.com/guide/flow-runs.md --- # Runs & Executions A run is one execution of a flow. Puppetflow uses both terms for the same thing. Each run has its own status, input, output, logs, code snapshot, duration, and artifacts. A flow can be run manually from the editor or automatically through a trigger, the REST API, or MCP. ## Execution modes Puppetflow distinguishes between two execution modes. ### Manual runs A manual run starts from the flow editor or from a run-again action in the interface. Manual runs are intended for building, debugging, and validating flows with a real browser and test data. Development usage does not normally use the run quota. Puppetflow applies a fair-use policy when the same working browser journey is launched manually over and over. A stable, repeated manual journey may eventually be classified as a production run. The policy looks at what the flow actually executes. Renaming or moving nodes, changing comments, or adding a `No-op` node does not by itself establish new development activity. New browser actions, branches, or other meaningful execution changes move the flow back toward development usage. The decision made when a run starts is final for that run. Finishing a run may update the flow's fair-use state, but that update only affects later runs. ### Automated runs The following runs are classified as production when Puppetflow accepts them: * webhook triggers; * cron triggers; * REST API executions; * executions started through MCP. Each production run reserves one credit when accepted. Successful and failed runs consume that credit. Cancelling the run releases it, while pausing for human validation keeps the reservation attached to the same run. A request rejected before Puppetflow creates a run does not use a credit. ## How quota usage works Plans with a run allowance use a fixed subscription cycle. Puppetflow reserves one credit when it accepts a production run. When the allowance is exhausted, Puppetflow blocks production runs until the next cycle. Manual runs that still qualify as development usage remain available. One flow run always consumes at most one credit: * Calling a snippet does not create another run. * Pausing with `$waitHumanValidation()` and continuing later remains part of the original run. * Producing several screenshots, downloads, or browser actions does not create additional runs. ## Run lifecycle A run moves through these statuses: 1. **Pending**: the run is queued and waiting for a worker. 2. **Running**: the browser is active and executing the flow. 3. **Success**: the flow completed successfully. 4. **Error**: the flow threw an exception or returned an error response. 5. **Cancelled**: someone stopped the run before completion. ## Viewing runs Open a flow and select the **Runs** tab to see its history. The main **Runs** page searches across the flows you can access. Each entry shows its status, trigger source, duration, legend, and artifact counts. Open a run to inspect: * the input and JSON output; * console logs; * the exact code snapshot used for that execution; * screenshots, downloads, and video recording when available. Runs can be filtered by date and status. Plans with metadata search can also filter values attached through `$meta()`. See the [Runs API](/reference/api/runs) for programmatic access. ## Waiting for human validation `$waitHumanValidation()` keeps the run open and displays **Continue run** in its **Live** tab. Continuing resumes the same browser session and does not create or count another run. ## Cancelling a run Active runs can be stopped from the run detail or the runs list. Puppetflow terminates the browser process and marks the run as cancelled. A cancelled production run releases its reserved credit. Its production classification remains attached to the run for audit purposes. ## Retention Retention controls how much execution history Puppetflow stores: * a flow can set its own maximum number of retained runs; * a workspace can provide a default and an upper limit. When a retention limit is reached, Puppetflow removes the oldest runs and their artifacts. Removing history does not change quota usage for the current subscription cycle. --- --- url: https://docs.puppetflow.com/guide/triggers-actions.md --- # Triggers & Actions Triggers start flows automatically. Actions fire after a flow finishes. ## Triggers ### Webhook triggers A webhook trigger generates a unique URL that starts a flow when called: ``` POST https://your-instance.com/api/trigger/{token} ``` Any JSON body sent to this URL is merged into the flow input (`$input`). Configure: | Option | Description | | --- | --- | | **Label** | A name for this trigger. | | **Merge POST data into input** | Whether to merge the incoming body into the input. | | **Additional data for this trigger** | Default JSON supplied to the flow. | | **Use a different proxy for this trigger** | Override the flow proxy for this trigger. | | **Visibility** | Owner, Team, or Workspace. | | **Owner** | Workspace member who owns the trigger. | The trigger list contains its active toggle. Inactive triggers ignore incoming requests. You can configure several webhook triggers per flow, each with its own URL. ### Schedule triggers A **Schedule** trigger fires the flow using a cron expression: | Expression | Meaning | | --- | --- | | `* * * * *` | Every minute | | `0 */6 * * *` | Every 6 hours | | `0 9 * * 1-5` | Weekdays at 9 AM | | `0 0 1 * *` | First day of each month | Schedules are evaluated once per minute in the trigger owner's timezone. The smallest interval is one minute. ### Visibility Triggers and actions can use Owner, Team, or Workspace visibility. Shared resources appear in the flow's **Automation** tab for members with access. ## Actions Actions are post-run webhooks that fire after a flow run completes. ### Webhook actions Configure a URL to receive the run result: | Option | Description | | --- | --- | | **Webhook URL** | The endpoint to call. | | **HMAC Secret (Optional)** | HMAC secret for request signing. | | **Headers** | Custom headers to include. | | **Fire on error** | Also fire when the run fails (default: only on success). | | **Screenshots/Downloads/Recording in output** | Override the flow artifact settings. | | **Visibility** | Owner, Team, or Workspace. | | **Owner** | Workspace member who owns the action. | The webhook receives a POST with the run output, status, duration, and artifact URLs. ### Multiple actions You can attach multiple actions to a single flow. Each action has its own configuration and can fire independently. --- --- url: https://docs.puppetflow.com/guide/integrations.md --- # Integrations Integrations connect Puppetflow to external services. ## Workflow automation ### n8n The [`n8n-nodes-puppetflow`](https://www.npmjs.com/package/n8n-nodes-puppetflow) community node adds Puppetflow browser automation to n8n workflows. It can: * Trigger a flow with optional JSON input. * List runs and filter them by status. * Retrieve a run and its result. * List and download screenshots or downloaded files. * Download session recordings. #### Install the node Installing a community package from npm requires a self-hosted n8n instance. 1. In n8n, open **Settings > Community Nodes**. 2. Click **Install** and enter `n8n-nodes-puppetflow`. 3. Add a **Puppetflow** node to a workflow. 4. Create a **Puppetflow API** credential. 5. Enter the root URL of your Puppetflow instance, without `/api/v1`. 6. In Puppetflow, open **Profile > API Keys**, generate a key, and enter it in the n8n credential. See the [n8n community node installation guide](https://docs.n8n.io/integrations/community-nodes/installation/) for alternative installation methods. ## AI integrations Puppetflow supports OpenAI, Google Gemini, Anthropic Claude, and Mistral. An AI integration stores the API key and discovers the AI models available to that account. 1. Go to **Integrations** and choose the AI integration. 2. Enter a name and select personal, team, or workspace visibility. 3. Enter the API key. 4. Validate the connection, then click **Connect**. The API key is stored in the integration and is never added to flow code. Editing an integration with an empty API key keeps the existing key. After connecting an AI integration, select the [AI models](/guide/flows#ai-models) that flows may use. ## Repository integrations Link your flows to Git repositories so the code stays in sync with your codebase. ### GitHub GitHub integration uses a GitHub App for secure access. Setup: 1. Go to **Integrations** and click **GitHub**. 2. Puppetflow generates an App manifest and redirects you to GitHub to create the App. 3. Install the App on your repositories. 4. Back in Puppetflow, the integration is active and you can link flows to files. Once connected, you can: * Browse repositories and branches. * Link a flow to a specific file path. * Choose a sync trigger (`push` or `tag`). * Code updates automatically when the event fires. Git repositories are also used by the blueprints system. Public blueprints are read from the configured repository. Private blueprints can use additional repositories when this option is enabled for the instance. ### Private libraries and blueprints Private libraries are workspace-level blueprint sources configured under **Workspace > Settings > Private Libraries**. Use private blueprints when you want to distribute internal blueprints without publishing them to the public store. They support: * owner, workspace, or team visibility, * branch selection, * manual refresh, * grouping, * importing flows and snippets into the workspace, * update notifications. Enter a public **GitHub URL** in `https://github.com//` format. Puppetflow reads the repository anonymously through GitHub, so private repositories are not supported here. ### Other providers GitLab, Bitbucket, and Gitea are listed as available providers in the integration settings. ## Vault integrations ### 1Password On Pro and above, connect to 1Password for runtime secret resolution. #### Run 1Password Connect Create a Connect server in 1Password, then place the generated `1password-credentials.json` file next to your Puppetflow Docker Compose file. Add these services to the Puppetflow Compose configuration: ```yaml services: op-connect-api: image: 1password/connect-api:1.8.1 restart: unless-stopped volumes: - "./1password-credentials.json:/home/opuser/.op/1password-credentials.json:ro" - "onepassword-data:/home/opuser/.op/data" networks: - puppetflow op-connect-sync: image: 1password/connect-sync:1.8.1 restart: unless-stopped volumes: - "./1password-credentials.json:/home/opuser/.op/1password-credentials.json:ro" - "onepassword-data:/home/opuser/.op/data" networks: - puppetflow volumes: onepassword-data: ``` Start both services: ```bash docker compose up -d op-connect-api op-connect-sync ``` The Connect access token is used by Puppetflow to authenticate with the API. It does not need to be passed to the Connect containers. #### Connect Puppetflow 1. Go to **Integrations** and click **1Password**. 2. Set **Connect Server URL** to `http://op-connect-api:8080`. 3. Enter the 1Password **Connect Token**. 4. Browse vaults, items, and fields. Once connected: * Create **Vault** variables that reference specific 1Password fields. * Values are fetched at runtime, never stored in Puppetflow. * OTP fields from 1Password generate fresh TOTP codes. ## Messenger integrations Connect chat platforms for notifications and human approval gates. ### Telegram 1. Create a Telegram bot via [@BotFather](https://t.me/BotFather). 2. Enter the bot token in the integration settings. 3. Puppetflow detects available chats. 4. Create notification channels from the detected chats. ### Discord 1. Create a Discord bot in the Developer Portal. 2. Enter the bot token. 3. Puppetflow detects available channels. ### Slack 1. Create a Slack app with a bot token. 2. Enter the token. 3. Puppetflow detects available channels. ## Mailbox integration The mailbox integration manages custom email domains for receiving emails. 1. Go to **Integrations** and click **Mailbox**. 2. Add a domain name. 3. Configure the A, MX, and TXT records shown by Puppetflow. 4. Verify the domain. Once verified, you can create mailboxes on that domain and use them in flow [mailbox watchers](/guide/mailboxes). ### DNS setup Puppetflow provides the exact DNS records to add: * **A record** - `mail.` points to the Puppetflow server's public IP. * **MX record** - `` points to `mail.` with priority 10. * **TXT record** - `v=spf1 mx ~all`. The domain detail page shows a DNS verification checker that validates your records in real time. ## Managing integrations All integrations support: * **Visibility** - Owner, Team, or Workspace. * **Active toggle** - Disable an integration without deleting it. * **Usage tracking** - See which flows and variables reference the integration before deleting. --- --- url: https://docs.puppetflow.com/guide/mailboxes.md --- # Mailboxes Mailboxes let you receive emails on custom domains and use them in your automations. This is how Puppetflow handles email verification flows, OTP codes sent by email, and any scenario where your automation needs to read incoming mail. ## How it works 1. Configure a [mailbox integration](/guide/integrations#mailbox-integration) with a verified domain. 2. Create a mailbox (e.g. `verify@yourdomain.com`). 3. Set up a **watcher** on a flow to listen for matching emails. 4. In your flow code, call `$waitForEmail('watcher-id')` to pause until a matching email arrives. ## Creating a mailbox Go to **Mailboxes** and click **New Mailbox**: | Field | Description | | --- | --- | | **Mailbox address** | Local part and verified domain. | | **Description (Optional)** | Optional note. | | **Group** | Optional organizational group. | | **Visibility** | Owner, Team, or Workspace. | | **Owner** | Workspace member who owns the mailbox. | The full address is `local-part@domain`. ## Browsing emails The mailbox UI has three panels: 1. **Mailbox list** - All your mailboxes with unread badges. 2. **Email list** - Emails in the selected mailbox with search and sort. 3. **Email preview** - Full email content with HTML rendering. You can mark emails as read/unread and delete them individually. ## Mailbox watchers Watchers are attached to a flow and define rules for matching incoming emails. When a flow is running and calls `$waitForEmail('watcher-id')`, Puppetflow checks incoming emails against the watcher's rules. ### Creating a watcher In the flow editor, go to the **Mailboxes** tab: 1. Select a mailbox to watch. 2. Give the watcher a name (used in your code). 3. Define matching rules. 4. Optionally enable additional parsing. ### Matching rules Rules can inspect **Body**, **Subject**, **To**, **From**, **Has Attachments**, and **Size**. Every field supports **Contains**, **Not Contains**, **Equals**, **Greater Than**, **Less Than**, and **Regex**. Rules are grouped with AND/OR logic. All rules in a group must match (AND), and any group can match (OR). ### Additional parsing Enable **Additional parsing** and choose **Regex** or **XPath Selector**. The extracted result is available as `parsed`, with `parsed_value` as an alias. Example: extract a 6-digit verification code: ``` /code[:\s]*(\d{6})/i ``` ### Using watchers in code ```js const email = await $waitForEmail('watcher-id', { timeout: 300000 // milliseconds, default: watcher config or 300000 }); // email.parsed contains the extracted value (if regex enabled) await $fillInput('#code', email.parsed); ``` The method blocks until a matching email arrives or the timeout expires. ## SMTP server Puppetflow includes a built-in SMTP server that receives incoming emails. It runs as a separate service on port 2525 (configurable via `MAILBOX_SMTP_PORT`). Your domain's MX record must point to the server's public IP for emails to be delivered. --- --- url: https://docs.puppetflow.com/guide/channels.md --- # Notification Channels Channels connect Puppetflow to messaging platforms for notifications and human-in-the-loop workflows. ## Supported providers * **Telegram** - Send messages to Telegram chats via a bot. * **Discord** - Send messages to Discord channels via a bot. * **Slack** - Send messages to Slack channels via a bot. ## Creating a channel 1. First, set up a [messenger integration](/guide/integrations#messenger-integrations) for the desired platform. 2. Go to **Channels** and click **New Channel**. 3. Select the integration and pick a chat/channel from the detected list. 4. Give it a name and optional group. ## Visibility * **Owner** - Private to you. * **Team** - Available to members of the selected team. * **Workspace** - Available to every workspace member. ## Using channels in flow code ### Sending notifications ```js await $notify('channel-id', 'Deployment complete!', { link: { url: 'https://app.example.com', label: 'Open the app' }, showFlowId: true, showRunId: true, }); ``` | Option | Description | | --- | --- | | `link` | Object with `url` and `label`, appended to the message. | | `showFlowId` | Append the flow ID to the message. | | `showRunId` | Append the run ID to the message. | ### Human-in-the-loop Pause the run and wait for a human to approve before continuing: ```js // Notify the team and wait for approval await $waitHumanValidation( 'User onboarding requires manual review. Continue?', 'channel-id' ); // The run resumes only after someone clicks "Continue run" in the UI await $clickElement('#confirm-onboarding'); ``` Without a channel argument, the flow pauses silently and shows **Continue run** in the run's **Live** tab: ```js // Silent pause - no notification await $waitHumanValidation(); ``` The method declares a pending validation on the server and polls every 3 seconds until it is approved from the UI or the API. ## Testing channels After creating a channel, click **Send test message** to verify the connection. ## Usage tracking Before deleting a channel, you can inspect which flows reference it in their code. --- --- url: https://docs.puppetflow.com/guide/workspaces.md --- # Workspaces Workspaces are the top-level organizational unit in Puppetflow. They group flows, variables, integrations, mailboxes, and channels together for a team. ## Creating a workspace Open the workspace switcher and click **New workspace**. In the modal, select **Create Workspace**. Every user starts with a default workspace. Workspaces can also be managed through the REST API with an API key: ```http GET /api/v1/workspaces POST /api/v1/workspaces GET /api/v1/workspaces/{workspace} PATCH /api/v1/workspaces/{workspace} ``` The API supports creating workspaces and updating their name, lookup key, preferences, and API-managed appearance fields. Workspace deletion is not exposed through the REST API. An optional `lookup_key`, such as `production_eu`, gives a workspace a stable API identifier. Posting a workspace with an existing lookup key updates it instead of creating a duplicate. Workspace detail and update endpoints accept either the workspace ID (`work_...`) or lookup key. ## Members and roles | Role | Permissions | | --- | --- | | **Admin** | Manage members, settings, integrations, and all flows. | | **Manager** | Manage flows and shared resources. | | **Member** | Create and manage own flows. Access shared resources. | Workspace ownership is separate from member roles. See [Users, Teams, and Access Control](/guide/users-teams-access) for details. ### Inviting members Go to **Workspace > Members** and enter an email address. If the user doesn't have an account, they'll receive an invitation email with a registration link tied to the workspace. Pending invitations can be resent or cancelled. ### Transferring ownership The workspace owner can transfer ownership to another member from the workspace settings. ## Teams and resource access Teams let you share flows, variables, channels, mailboxes, integrations, and other resources with a selected group of workspace members. Each resource can be private to its owner, shared with a team, or shared with the workspace. See [Users, Teams, and Access Control](/guide/users-teams-access) for roles, ownership, teams, and resource permissions. ## Workspace settings Workspace settings contain **General**, **Flows**, and **Proxies**. **Private Libraries** and **Instance MCP** appear when enabled. All members can view the tabs, but only workspace admins can make changes. ### General tab #### General * **Name** - Display name for the workspace. * **Icon** - Emoji or uploaded image, with a preset or custom background color. Through the REST API, appearance updates support `icon_type`, `icon_value`, and `icon_color`. Uploaded icon files remain managed from the web interface. Instance administrators can view and edit workspace lookup keys from **Admin > Workspaces**. #### Ownership The current workspace owner is shown here. The owner can transfer ownership to another user, who becomes a workspace admin. #### Security * **Require two-factor authentication for all members** - Members must configure 2FA before accessing the workspace. This setting is available when two-factor enforcement is enabled on the instance. #### Danger zone Workspace admins can delete the workspace after entering its name for confirmation. Deletion permanently removes its resources, runs, and artifacts. ### Flows tab #### Browser * **Default viewport width** - Browser width, from 320 to 3840 pixels. * **Default viewport height** - Browser height, from 200 to 2160 pixels. * **Default keyboard speed** - Delay between simulated keystrokes. * **Default user agent** - Browser user agent used when a flow does not override it. * **Default browser language** - Browser language used when a flow does not override it. Flows can override these defaults in their own settings. #### Run retention * **Default retention limit** - Number of runs kept when a flow has no specific limit. * **Maximum retention limit** - Maximum number of runs that any flow can keep. Set a value to `0` for no workspace limit. Instance-level limits may still apply. #### Performance * **Default flow timeout** - Timeout used when a flow has no specific value. * **Maximum flow timeout** - Hard timeout limit for flows in the workspace. * **Default max retries** - Retry count used when a flow has no specific value. * **Maximum max retries** - Hard retry limit for flows in the workspace. Instance-level limits can cap workspace timeout and retry settings. The same settings are available through the REST API. Instance-level limits still apply, so submitted values may be capped before they are stored. #### Debug * **Object depth** - Maximum depth used when expanding nested objects in flow console logs, from 0 to 20. Default: 8. * **Array item limit** - Maximum number of array entries included in flow console logs, from 1 to 1000. Default: 100. These limits apply to every flow in the workspace and prevent deeply nested or large values from overwhelming run logs. #### Default Flow Choose the starting type and content used for new flows in the workspace: * **Visual Builder** - Edit the default nodal graph. * **Raw Code** - Edit the default JavaScript template. Use **Reset to default** to restore Puppetflow's built-in graph or code template. Existing flows are not changed when the workspace default is updated. ### Proxies tab Workspace administrators can add HTTP, HTTPS, SOCKS4, and SOCKS5 proxy servers for flow runs. A proxy can be personal, shared with a team, or shared with the workspace. Proxies can be selected explicitly in a flow or included in automatic round-robin routing. Instance administrators can also provision proxies for every workspace through the `MANAGED_PROXIES` environment variable. Managed proxies display a lock badge in the table. They are available to workspace users and flows, but cannot be edited or deleted from the interface. Each proxy can have a country and group. Flow round-robin pools can use grouped `AND`/`OR` rules to select proxies from specific countries and groups. See [Managed proxies](/reference/configuration#managed-proxies) for the JSON format and synchronization behavior. ### Instance MCP tab This tab is available when MCP is enabled for the instance. | Setting | Description | | --- | --- | | **Enable MCP access for this workspace** | Makes the workspace available to MCP clients. | | **Include flows not enabled for MCP in search results** | Includes visible, non-executable flows in MCP search results. | | **Universal MCP Connection** | Shows the single public address, `https://mcp.puppetflow.com/mcp`, recommended for Claude and ChatGPT. | | **Direct OAuth** | Shows the instance and workspace OAuth endpoints, manages fixed OAuth clients, and lists connected clients. | | **Manual Access Token** | Creates and revokes named `mcp_...` bearer tokens. | | **MCP Tools** | Enables or disables individual MCP tools. | | **Exposed Flows** | Controls which flows can be inspected and run through MCP. | See [Connect AI clients with MCP](/guide/mcp) for the connection steps. The available tool groups are: * **Flows**: search and inspect flows, list authoring resources, and create or update code and visual flows. * **Automation**: list, create, update, and delete flow triggers and actions. * **Snippets**: search and inspect snippets, and create or update code and visual snippets. * **Runs**: search, start, inspect, and continue flow runs. * **Artifacts**: list and retrieve screenshots, downloads, and recordings. * **Workspace**: inspect or update the connected workspace. * **Teams**: list workspace members and manage teams and memberships. Each tool is marked read-only or potentially destructive. AI clients can use these annotations to request confirmation before writes or external browser actions. See the [MCP API reference](/reference/api#mcp-server) for the complete tool list. Only flows visible to the connected user and explicitly exposed to MCP can be executed. See [Connect AI clients with MCP](/guide/mcp) for setup instructions for Claude, ChatGPT, Cursor, and other MCP clients. ### Private Libraries tab This tab is available when private libraries are enabled. Private libraries add flows and snippets from a public GitHub repository to the blueprints store. To add a library, configure: | Field | Description | | --- | --- | | **Label** | Display name shown in workspace settings. | | **GitHub URL** | Public repository URL in `https://github.com/owner/repo` format. | | **Branch** | Branch to use, defaulting to `main`. | | **Group** | Optional grouping label. | | **Visibility** | Owner, workspace, or team. | | **Owner** | Workspace member who owns the imported resources. | Libraries can be refreshed manually. When deleting one, you can choose whether to delete its imported flows and snippets. ## Switching workspaces Click the workspace name in the sidebar to open the switcher. You see all workspaces you belong to and can switch instantly. --- --- url: https://docs.puppetflow.com/guide/users-teams-access.md --- # Users, Teams, and Access Control Puppetflow combines workspace roles, resource ownership, and access scopes to control who can view, use, and manage resources. ## User authentication Users can sign in with an email address and password. An instance can also enable Google or GitHub sign-in. Users can protect their account with two-factor authentication and recovery codes. A workspace can require two-factor authentication from all its members. API keys authenticate REST API requests. MCP connections use MCP tokens or OAuth credentials. ## Workspace roles Each workspace member has one role: | Role | Permissions | | --- | --- | | **Admin** | Manage workspace settings, members, teams, and shared resources. | | **Manager** | Manage flows and shared resources, plus membership of teams they belong to. | | **Member** | Create and manage personal resources and use resources shared with them. | Workspace ownership is separate from these roles. The workspace owner has full control, can delete the workspace, and can transfer ownership to another member. Only admins can grant or remove the admin role. A workspace must always have at least one admin. ## Teams Teams group workspace members for resource sharing. A team does not have its own roles: a user is either a member of the team or not. Workspace admins can create, rename, and delete teams and manage every team's membership. Managers can add or remove members only in teams they belong to. ## Resource owners Every resource has an owner. The owner keeps access to the resource regardless of its sharing scope and can manage or transfer it. A resource can be transferred to another member of the same workspace. Workspace admins can manage ownership across the workspace. Managers can transfer resources owned by members, but not resources owned by admins or other managers. ## Access scopes Resources support three access scopes: | Scope | Access | | --- | --- | | **Owner** | Only the resource owner. | | **Team** | The owner and members of the selected team. | | **Workspace** | Every workspace member. | Sharing grants members access to view and use a resource. Editing, deleting, or transferring it remains limited to the owner and workspace admins. ## Resources with access control Access scopes are available for: * flows and folders, * variables and snippets, * notification channels, * mailboxes and mailbox watchers, * integrations, * triggers and actions, * private libraries. Runs and artifacts follow the permissions of their flow. Mailbox emails follow the permissions of their mailbox. API keys remain personal to the user who created them. Access is configured separately for each resource. Moving or grouping resources does not automatically grant access to unrelated resources. ## Invitations Workspace admins can invite members to the workspace. Managers can invite users into teams they belong to. Existing Puppetflow users join immediately. New users receive an invitation link and join after creating their account. Pending invitations can be resent or cancelled. --- --- url: https://docs.puppetflow.com/guide/grabber-browser-extension.md --- # Grabber Browser Extension Puppetflow Grabber lets you select an element on a web page instead of writing its CSS selector by hand. It works with nodal flows, code flows, and as a standalone browser tool. ## Install the extension Install Puppetflow Grabber from the [Chrome Web Store](https://chromewebstore.google.com/detail/puppetflow-grabber/behdpfaljjpaeekihhnjfhfhigfbkjdc) or [Firefox Add-ons](https://addons.mozilla.org/firefox/addon/puppetflow-grabber/), then pin it to the browser toolbar. The first click on the extension icon opens a short introduction. Select **Pick an element** to start. After that first use, clicking the extension icon starts the picker directly. ## Grab from a nodal flow Selector fields have a **Grab** button next to their label. 1. Open the settings for a node that expects a selector. 2. Select **Grab**. 3. Puppetflow opens the page from the closest `$gotoUrl` when one is available. 4. Hover the element you want, then click it. The selector is inserted into the field automatically. Hold the **Grab** button or use `Shift` + click to open the introduction again. ## Grab from a code flow Selector arguments have a target icon in the editor gutter. Select the icon, pick an element in the browser, and Puppetflow replaces the matching argument in your code. The editor checks that the code has not changed before inserting the selector. If it has, the pending grab is cancelled rather than editing the wrong location. ## Use Grabber without the editor Click the extension icon while viewing any HTTP or HTTPS page. The page enters picking mode immediately after the first-use introduction. Hover an element to preview it. Click to open **Extract element as**, then choose **Copy Selector**, **Copy JS Path**, **Copy XPath**, **Copy Full XPath**, or **Copy Minimal Selector**. The result is copied to the clipboard. Click the extension icon again or press `Esc` to stop picking. ## While picking * `Esc` closes the extraction menu first, then cancels the grab. * `ArrowUp` moves the target to its parent. * `ArrowLeft` and `ArrowRight` move between sibling elements. * Navigation in the same tab keeps picking active. Grabber resumes when the new page is ready. The green frame uses Puppetflow's brand color. The label above the frame shows the current HTML tag, ID, and a short class summary. ## Selector format Grabber builds a CSS selector from stable information already present in the page. It prefers: * the HTML tag; * a stable ID or class chain; * useful attributes such as `data-testid`, `aria-label`, `role`, `name`, or `type`; * up to two parent elements when they make the selector more specific. Positional selectors such as `:nth-of-type()` are a fallback. Shadow DOM and same-origin iframe boundaries are included when needed. Browsers do not expose the contents of a cross-origin iframe to extensions. Grabber can select the iframe itself, but not an element inside it. ## Self-hosted editors Any Puppetflow editor served over HTTP or HTTPS can connect. No origin allowlist is required. See [Connect a self-hosted editor](/self-hosting/grabber-browser-extension) for setup instructions. ## Troubleshooting ### Grabber is not connected Reload the Puppetflow tab after installing or reloading the extension. Existing tabs can retain content scripts from the previous extension version. For self-hosted installations, confirm that the editor uses HTTP or HTTPS. The extension does not maintain a trusted-origin list. ### Picking is unavailable on a page Browsers block extensions on internal pages and extension stores. Open a regular HTTP or HTTPS page and try again. --- --- url: https://docs.puppetflow.com/guide/canvas-shortcuts.md description: >- Complete keyboard and pointer shortcut reference for the Puppetflow nodal canvas. --- ::: tip Canvas focus Keyboard shortcuts act on the active canvas. Most are ignored while you type in an input or text editor, and while a modal is open. Editing shortcuts are unavailable in read-only graphs. ::: ## Create and edit | Shortcut | Action | Details | | --- | --- | --- | | N or A | Add a node | Opens the node picker. A places it at the pointer. When opened from a connection, the node is inserted into that connection. | | R | Tidy the graph | Arranges selected nodes when possible, otherwise the complete graph, then centers it. | | M | Activate or deactivate | Toggles deactivation for the selected nodes. | | E or Enter | Edit selection | Opens the editor for the single selected node or sticky note. | | Left click ×2 | Edit an item | Double-click a node or sticky note to open its editor. | | D | Duplicate | Duplicates the selected editable nodes and sticky notes. | | Delete, Backspace, or X | Delete | Removes the current selection from an editable graph. | ## Select and navigate | Shortcut | Action | Details | | --- | --- | --- | | ⌘/Ctrl + A | Select all | Selects every item in the current canvas, including sticky notes. | | Left click | Select an item | Selects the clicked node or sticky note. Clicking an already selected item preserves the group selection for dragging. | | Drag empty canvas | Rectangle select | Selects only items fully enclosed by the rectangle. Sticky notes join the selection only when the rectangle also contains at least one node. | | → | Select next node | With exactly one node selected, follows its first outgoing connection. | | ← | Select previous node | With exactly one node selected, follows its first incoming connection. | | Esc | Clear or close | Closes the active picker, menu, connection, or transform first. Otherwise clears the canvas selection. | | Right click | Open context menu | An unselected item becomes the selection. Right-clicking a selected item preserves its group; right-clicking empty canvas preserves the current selection. | ## Move, push, and swap | Shortcut | Action | Details | | --- | --- | --- | | Drag selection | Move items | Moves the clicked item or every item in the current selection. Positions snap to the canvas grid, and approaching a canvas edge automatically pans the viewport. | | G | Move mode | Attaches the selection to the pointer. Move the pointer, then click to confirm. | | Shift + move | Lock movement axis | Locks movement to the first dominant horizontal or vertical axis. Works during mouse dragging and in G mode. | | Alt + move | Push nodes | Moves the selection and pushes every node located ahead of it in the movement direction. Sticky notes outside the selection stay in place. Moving in the opposite direction pushes nodes on the opposite side. | | Alt + Shift + move | Push on one axis | Combines directional pushing with horizontal or vertical axis locking. | | S | Swap mode | With exactly two editable, single-input/single-output nodes selected, previews their swap. Move the pointer, then click to confirm. | | Esc | Cancel transform | Restores all original positions while move or swap mode is active. | ### How directional pushing works Nodes behind the selection stay in place. Nodes ahead move by the same distance as the selection. Sticky notes are never pushed unless they are part of the selection being moved. With multiple selected items, Puppetflow uses the frontmost selected item as the push boundary. ## Clipboard and history | Shortcut | Action | Details | | --- | --- | --- | | ⌘/Ctrl + C | Copy | Copies selected editable items and the connections between them. | | ⌘/Ctrl + X | Cut | Copies and removes selected editable items. | | ⌘/Ctrl + V | Paste | Pastes copied items at the last pointer position on the canvas and selects the new items. | | ⌘/Ctrl + Z | Undo | Reverts the last editable graph operation. | | ⌘/Ctrl + Shift + Z | Redo | Reapplies the last reverted graph operation. | ## Viewport and zoom | Gesture | Action | Details | | --- | --- | --- | | Mouse wheel / two-finger scroll | Pan | Scrolls the canvas horizontally and vertically. | | Shift + wheel | Pan horizontally | Converts wheel movement into horizontal canvas movement. | | ⌘/Ctrl + wheel | Zoom | Zooms around the pointer position. Trackpad pinch gestures use the same behavior. | | Middle-button drag | Free pan | Moves the viewport in any direction without changing the selection. | | Click minimap | Jump viewport | Centers the viewport on the clicked minimap position. | | Drag minimap | Navigate viewport | Continuously moves the viewport through the graph overview. | | F | Center viewport | Centers the viewport on the graph. | ## Connections and canvas gestures | Gesture | Action | Details | | --- | --- | --- | | Drag from a port to a port | Connect nodes | Creates a connection between compatible input and output ports. | | Drag from a port to a node | Connect to default input | Dropping on a compatible node uses its default input port. | | Drag from a port to empty canvas | Continue with a new node | Opens the node picker and connects the chosen node automatically. | | Hold C + drag empty canvas | Cut connections | Draws a knife path. Every crossed connection is removed when the pointer is released. | | Drag one node over a connection | Insert into connection | A compatible single-node selection snaps into the highlighted connection when released. | | Drag sticky-note handles | Resize note | Resizes a selected sticky note from its edges or corners. | ## Pickers, menus, and editors | Shortcut | Action | Details | | --- | --- | --- | | ↑ / ↓ | Navigate node results | Moves through the filtered results while the node picker search is focused. | | Enter | Add highlighted node | Adds the active node-picker result to the canvas or current connection. | | ↑ / ↓ or Tab | Navigate a context menu | Cycles through enabled menu actions. Use Shift + Tab to move backward. | | Home / End | Jump through a context menu | Focuses the first or last enabled menu action. | | → / ← | Open or close a submenu | Controls the submenu of the currently focused context-menu action. | | Enter or Space | Run menu action | Activates the focused button or menu item. | | Esc | Close active UI | Closes the node picker, context menu, node editor, or sticky-note editor before returning focus to the canvas. | ::: warning Modifier order Start moving first or press the modifier while moving. Releasing Shift returns to free movement. Releasing Alt stops pushing surrounding items. ::: --- --- url: https://docs.puppetflow.com/guide/variables.md --- # Variables Variables store reusable values that are securely injected into your flows at runtime. ## Variable types | Type | Description | | --- | --- | | **Text** | Plain text value, visible in the UI. | | **Secret** | Encrypted at rest, masked in the UI, never logged in run output. | | **Object** | Structured key-value data, accessible with dotted paths. | | **Array** | Structured list data. | | **One Time Password** | A TOTP secret that generates a fresh code on every `$vars()` call. | | **MCP Credentials** | Credentials for an MCP client connection. | | **Vault provider** | A field fetched from a connected vault such as 1Password. | ## Visibility * **Owner** - Private to you. * **Team** - Shared with members of the selected team. * **Workspace** - Shared with every workspace member. ## Using variables ### In flow code Call `$vars(variableId)` to resolve a variable at runtime: ```js await $fillInput('#email', $vars('variable-id')); await $fillInput('#password', $vars('variable-id')); ``` For OTP variables, `$vars('variable-id')` computes a fresh TOTP code every time it is called. ### In flow inputs Use the `${vars.ID}` syntax in JSON input templates: ```json { "username": "${vars.variable-id}", "api_key": "${vars.variable-id}" } ``` Variables are resolved before the input is passed to the flow. ### Object paths Object variables support dotted paths. Given a variable with this value: ```json { "api": { "key": "abc123", "url": "https://api.example.com" } } ``` You can access nested values: ```js const key = $vars('variable-id.api.key'); // "abc123" const url = $vars('variable-id.api.url'); // "https://api.example.com" ``` ## Groups Variables can be organized into named groups for easier management. Use the group filter in the variables table to narrow down the list. ## OTP variables OTP variables store a TOTP secret (Base32-encoded or an `otpauth://` URI). Always resolve them while the flow is running with `$vars(variableId)`: ```js const otp = $vars('variable-id'); await $fillInput('#otp', otp); ``` TOTP codes change after each rotation period. Calling `$vars()` at runtime generates the code that is valid at that moment. The generated code uses: * **Algorithm** - SHA1, SHA256, or SHA512 * **Digits** - Number of digits (default: 6) * **Period** - Rotation interval in seconds (default: 30) Do not copy or save a generated TOTP code in the flow: it will expire. ## Vault variables Available on Pro and above, vault variables reference a specific field inside a 1Password item. They require a configured 1Password integration. At runtime, the value is fetched directly from the vault. ## Usage tracking Before deleting a variable, you can inspect where it is used across: * Flow code (direct `$vars()` calls) * Flow input templates (`${vars.ID}` syntax) * Trigger input templates * Other variables referencing it Renaming a variable changes its display key without changing its ID, so existing references remain valid. --- --- url: https://docs.puppetflow.com/guide/downloaded-files.md --- # Working with Downloaded Files Flows often download files as part of an automation: invoices, exports, reports, archives. Puppetflow ships with built-in tools to process these files during the run, without any external service. Every flow has its own downloads area. Files retrieved with `$download()`, `$downloadFromBrowser()`, or `$waitForFile()` land there, and all the tools on this page read from it by default. See [Artifacts](/guide/artifacts) for how downloads are collected and exported. ## PDF documents ### Check that a PDF contains a text Use `$pdfSearch()` to verify the content of a downloaded PDF, for example to confirm an invoice matches the expected customer: ```js await $downloadFromBrowser('https://app.example.com/invoice.pdf', 'invoice.pdf'); const result = await $pdfSearch('invoice.pdf', 'ACME Ltd'); if (!result.found) { return $generateResponseError('Wrong invoice downloaded'); } $log(`Found on pages ${result.pages.join(', ')}`); ``` The search is case-insensitive and matches literal text: ```js { found: true, count: 2, pages: [1, 3], totalPages: 5 } ``` `$pdfSearch()` reads the text embedded in the PDF. Scanned image-only documents have no embedded text and cannot be searched. ### Extract data from a PDF Use `$pdfGetText()` to extract the full text and process it yourself, with regular expressions for example: ```js const pdf = await $pdfGetText('invoice.pdf'); const invoiceNumber = pdf.text.match(/Invoice\s+#(\d+)/i)?.[1]; const total = pdf.text.match(/Total\s+€([\d.,]+)/)?.[1]; return $generateResponseSuccess('Invoice parsed', { invoiceNumber, total }); ``` The result also includes the text page by page, which is useful for documents with a fixed layout. ## ZIP archives Use `$unzipFile()` to extract a downloaded archive and work with its content: ```js await $download('https://app.example.com/exports/monthly.zip', 'monthly.zip'); const files = await $unzipFile('monthly.zip', 'extracted'); // ['invoices.csv', 'summary.pdf'] ``` Extracted files are kept with the run's downloads by default. Pass `{ store: false }` to delete them at the end of the run, or `{ keepArchive: true }` to also keep the ZIP file. ## Browsing and organizing files List the downloaded files, optionally filtered by name: ```js const csvFiles = await $scanDownloadsDirectory('extracted', '.csv'); ``` Rename or move a file, for example to give a stable name to a file whose name changes on every export: ```js $moveDownloadedFile('export-2026-07-17.csv', 'latest-export.csv'); ``` ## Re-uploading a file A downloaded file can be sent back to a website through a file input, which is handy for flows that transfer documents between two applications: ```js await $upload('#file-input', 'invoice.pdf'); ``` See [Files & Downloads](/reference/flow-api/files) for the full reference of every file helper and its options. --- --- url: https://docs.puppetflow.com/guide/mcp.md --- # Connect AI clients with MCP Puppetflow includes a remote [Model Context Protocol](https://modelcontextprotocol.io/) server. It lets AI clients search, inspect, and run the flows you choose to expose. You can connect Claude, ChatGPT, Cursor, Claude Code, and other MCP-compatible clients. For most of them, a single public address is enough: ```text https://mcp.puppetflow.com/mcp ``` ## Before you connect You need: * a Puppetflow workspace with MCP enabled; * administrator access to its settings to configure tools and exposed flows; * at least one flow you can expose; * a recent version of your MCP client. For self-hosted instances, the Puppetflow URL must be reachable from the machine running the client and use HTTPS outside local development. Cloud clients such as Claude and ChatGPT connect from the internet, so the instance must have a public HTTPS address and an active license. ## 1. Configure the workspace 1. Open **Workspace > Settings > MCP**. 2. Make sure **Enable MCP access for this workspace** is enabled. 3. In **MCP Tools**, enable only the tools your client should use. 4. In **Exposed Flows**, enable **Available in MCP** for each flow the client may inspect or run. ::: tip Flow access still follows Puppetflow permissions. A connected user can only access flows that are both visible to them and explicitly exposed to MCP. ::: ## 2. Choose a connection mode The **MCP** tab offers three ways to connect. Pick the first one that fits your client: | Mode | Endpoint | Use it when | | --- | --- | --- | | **Universal MCP Connection** | `https://mcp.puppetflow.com/mcp` | The client supports remote MCP with OAuth: Claude, ChatGPT, Claude Code. Same address for every instance, no token to copy. | | **Direct OAuth** | `https://your-puppetflow.example/mcp` or a workspace endpoint | The client must reach your instance directly, for example on a private network, or must be locked to one workspace. | | **Manual Access Token** | `https://your-puppetflow.example/api/mcp-server/http` | The client only supports a fixed bearer header, such as Cursor. | See [Connection Modes](/guide/mcp/connection-modes) for the details of each mode. ## 3. Connect your client * [Claude, Claude Desktop, and Claude Code](/guide/mcp/claude) * [ChatGPT](/guide/mcp/chatgpt) * [Cursor](/guide/mcp/cursor) * [Other MCP clients](/guide/mcp/other-clients) ## 4. Verify the connection Ask the client: ```text List the Puppetflow flows available to me. ``` If a flow is exposed and the user has access, the client should return it. You can then ask: ```text Show me the details of the flow named "My flow". ``` Before allowing the client to run flows, review the enabled MCP tools and confirm that each exposed flow is safe to execute with AI-generated input. ## Going further * [Publish flows and snippets from an AI client](/guide/mcp/publishing) * [Troubleshooting](/guide/mcp/troubleshooting) * [MCP API reference](/reference/api#mcp-server) for protocol details and the complete tool list --- --- url: https://docs.puppetflow.com/guide/mcp/connection-modes.md --- # MCP connection modes The **MCP** tab in **Workspace > Settings** offers three ways to connect an AI client, from the simplest to the most manual. All three expose the same tools and the same flows: only the way the client authenticates and the way the workspace is chosen differ. ## Universal MCP Connection (recommended) Use `https://mcp.puppetflow.com/mcp` for Claude, ChatGPT, and any client that supports remote MCP with OAuth. The address is the same for every Puppetflow Cloud and self-hosted instance, so it is also what the Puppetflow listings in the Claude and ChatGPT catalogs use. When the client connects: 1. Puppetflow asks for your instance: a Cloud subdomain or the HTTPS URL of your self-hosted installation. 2. You sign in on your own instance. Your password is never shared with the client or with the broker. 3. You choose the MCP-enabled workspace to connect. No URL specific to your workspace and no access token needs to be copied. The connection appears under **OAuth connected clients** in the workspace settings, where it can be revoked. For self-hosted instances, the broker only accepts URLs that an active license instance reports as its public address. See [Troubleshooting](/guide/mcp/troubleshooting#the-universal-connection-does-not-accept-my-instance) if your instance is refused. ## Direct OAuth Use a direct endpoint when the client should talk to your instance without going through `mcp.puppetflow.com`, for example on a private network. Both endpoints are shown in the **Direct OAuth** card: * **Instance OAuth MCP endpoint**, `https://your-puppetflow.example/mcp`: the user signs in and picks the workspace during authorization, like the universal connection. * **Workspace OAuth MCP endpoint**, `https://your-puppetflow.example/api/workspaces/work_your_workspace/mcp-server/http`: the connector is locked to this exact workspace. The client discovers the **Authorize URL** and **Token URL** automatically and registers itself through Dynamic Client Registration. These two URLs are only needed for clients that do not support OAuth discovery and must be configured by hand. Create a **fixed OAuth client** only when a client requires a pre-registered client ID and redirect URI. Fixed clients are bound to the workspace where they are created. Connected clients and fixed clients can be revoked at any time from the same card. ## Manual Access Token Use an access token for clients that cannot run an OAuth flow and need a fixed bearer header, such as [Cursor](/guide/mcp/cursor). 1. In the **Manual Access Token** card, copy the **Manual MCP endpoint**. 2. Enter a client name such as `Cursor`. 3. Click **Create token**. 4. Copy the generated `mcp_...` token immediately. It is only displayed once. The token carries the workspace, so the endpoint is the same for every workspace of the instance. ::: warning An MCP token acts with the permissions of the user who created it. Do not commit it to a repository, paste it into chat, or share it with another user. Revoke unused tokens from the workspace MCP settings. ::: --- --- url: https://docs.puppetflow.com/guide/mcp/claude.md --- # Connect Claude Puppetflow supports Claude's native remote connector flow. It uses OAuth 2.0 with PKCE, so users sign in to Puppetflow and approve access without copying a long-lived token into Claude. All Claude surfaces use the [Universal MCP Connection](/guide/mcp/connection-modes#universal-mcp-connection-recommended): ```text https://mcp.puppetflow.com/mcp ``` Claude connects from Anthropic's infrastructure. A self-hosted Puppetflow instance therefore needs a public HTTPS endpoint and an active license. Use [Direct OAuth](/guide/mcp/connection-modes#direct-oauth) to lock the connector to one workspace or connect through a private network. ## Claude on the web If Puppetflow is listed in the Claude connector directory, enable it from there. Otherwise add it as a custom connector: 1. In Claude, open **Customize > Connectors**. 2. Select **Add custom connector**. 3. Enter `Puppetflow` as the name and `https://mcp.puppetflow.com/mcp` as the URL. 4. Select **Connect**, enter your Cloud subdomain or self-hosted URL, sign in to Puppetflow, and choose the workspace. For Team and Enterprise organizations, an Owner must first add the connector under **Organization settings > Connectors**. Each member then authorizes their own Puppetflow access and picks their own workspace. ## Claude Desktop Claude Desktop uses the same connector configuration as Claude on the web: 1. Open **Customize > Connectors**. 2. Add a custom connector with `https://mcp.puppetflow.com/mcp`. 3. Select **Connect**, then complete the instance, sign-in, and workspace steps. 4. Open the tools menu and confirm that Puppetflow tools are available. The connection is associated with your Claude and Puppetflow accounts. You can revoke it from either Claude or **Workspace > Settings > MCP**. ## Claude Code Run: ```bash claude mcp add --transport http puppetflow https://mcp.puppetflow.com/mcp ``` Then open Claude Code and run: ```text /mcp ``` Select **Authenticate** if prompted. Claude Code opens Puppetflow in your browser so you can choose your instance, sign in, and pick the workspace. The `puppetflow` server should then show as connected. By default, Claude Code saves the server for the current project. Add `--scope user` if you want it available across your projects. Replace the URL with a Direct OAuth endpoint to bypass the universal broker. --- --- url: https://docs.puppetflow.com/guide/mcp/chatgpt.md --- # Connect ChatGPT ChatGPT connects through the [Universal MCP Connection](/guide/mcp/connection-modes#universal-mcp-connection-recommended): ```text https://mcp.puppetflow.com/mcp ``` If Puppetflow is available in the ChatGPT apps directory, enable it from there. Otherwise add it as a custom connector from the apps and connectors settings, using the address above. When you connect, Puppetflow asks for your instance, lets you sign in on it, and asks which workspace to expose. Your Puppetflow password is never shared with ChatGPT. ChatGPT connects from OpenAI's infrastructure. A self-hosted Puppetflow instance must have a public HTTPS endpoint and an active license. To lock the connection to one workspace, or to connect on a private network, use a [Direct OAuth](/guide/mcp/connection-modes#direct-oauth) endpoint instead. The connection appears under **OAuth connected clients** in **Workspace > Settings > MCP**, where it can be revoked. --- --- url: https://docs.puppetflow.com/guide/mcp/cursor.md --- # Connect Cursor Cursor is configured with a fixed bearer header, so it uses a [Manual Access Token](/guide/mcp/connection-modes#manual-access-token). Create the token first, then: 1. Open **Customize > MCPs** in Cursor. 2. Create `~/.cursor/mcp.json` for a personal connection, or `.cursor/mcp.json` for the current project. 3. Add the following server: ```json { "mcpServers": { "puppetflow": { "url": "https://your-puppetflow.example/api/mcp-server/http", "headers": { "Authorization": "Bearer ${env:PUPPETFLOW_MCP_TOKEN}" } } } } ``` 4. Replace the URL with the **Manual MCP endpoint** copied from Puppetflow. 5. Define `PUPPETFLOW_MCP_TOKEN` in Cursor's process environment with the generated `mcp_...` token as its value. 6. Restart Cursor, then check that `puppetflow` appears as connected under **Customize > MCPs**. Project and global configurations are merged. A project entry takes precedence when both configurations use the same server name. ::: warning Do not replace the environment variable with a raw token in a project-level `.cursor/mcp.json`. This file may be committed to the repository. ::: If the connection fails, open **Output**, select **MCP Logs**, and check whether the environment variable was loaded. --- --- url: https://docs.puppetflow.com/guide/mcp/other-clients.md --- # Connect other MCP clients ## Clients with OAuth support If the client supports remote MCP servers with OAuth, point it to the [Universal MCP Connection](/guide/mcp/connection-modes#universal-mcp-connection-recommended): ```text https://mcp.puppetflow.com/mcp ``` The client discovers the authorization server, registers itself, and opens Puppetflow so you can choose your instance, sign in, and pick a workspace. Use a [Direct OAuth](/guide/mcp/connection-modes#direct-oauth) endpoint when the client must reach your instance directly. ## Clients with a fixed bearer header Otherwise create a [Manual Access Token](/guide/mcp/connection-modes#manual-access-token) and use the **Manual MCP endpoint** with this request header: ```http Authorization: Bearer mcp_your_token_here ``` The client must support remote HTTP MCP servers and custom request headers. A typical configuration looks like: ```json { "type": "http", "url": "https://your-puppetflow.example/api/mcp-server/http", "headers": { "Authorization": "Bearer mcp_your_token_here" } } ``` The exact wrapper and field names depend on the client. --- --- url: https://docs.puppetflow.com/guide/mcp/publishing.md --- # Publish flows and snippets from an AI client Enable the flow or snippet authoring tools in **Workspace > Settings > MCP** to let an AI client manage publication: * `publish_flow` publishes the current flow draft as a new version. * `unpublish_flow` disables the published flow while preserving its draft and version history. * `publish_snippet` publishes the current snippet draft as a new version. * `unpublish_snippet` removes the active published snippet while preserving its draft and version history. Publication tools require update access. Before publishing, the client reads the current source and submits its exact `content_updated_at` value. Puppetflow rejects publication if the draft changed in the meantime. Library-managed flows and snippets must be duplicated before they can be published through MCP. Disabling a publication tool also blocks the equivalent publication option in flow and snippet writing tools. Snippet creation produces an unpublished draft unless publication is explicitly requested and `publish_snippet` is enabled. For the complete tool list, see the [MCP API reference](/reference/api#mcp-server). --- --- url: https://docs.puppetflow.com/guide/mcp/troubleshooting.md --- # MCP troubleshooting ## The server is disabled Confirm that MCP is enabled for the instance and for the workspace under **Workspace > Settings > MCP**. ## The universal connection does not accept my instance * For Cloud, enter only the subdomain, without `https://` or the domain suffix. * For a self-hosted instance, enter the public HTTPS origin only, without a path. * The instance must have an active license and be reachable over HTTPS with a trusted certificate. * If you recently changed the instance URL, update `APP_URL` and refresh the license from **Admin > Server > License** so the license service learns the new address. See [License Activation](/self-hosting/license-activation#the-mcp-broker-does-not-recognize-the-instance-url). ## No workspace is offered during sign-in Only workspaces with **Enable MCP access for this workspace** turned on, and that you belong to, are listed. Ask a workspace administrator to enable MCP. ## Authentication fails with an access token * Copy the token without leading or trailing spaces. * Include the `Bearer ` prefix before the token. * Check that the token has not been revoked. * Create a new token if the original value was lost. Existing tokens cannot be displayed again. * In Cursor, open **Output**, select **MCP Logs**, and check whether the environment variable was loaded. ## No flows are returned * Enable **Available in MCP** for the flow. * Confirm that the connected user can view the flow. * Check that the flow search tools are enabled in **MCP Tools**. ## A flow cannot be executed * Confirm that the flow is exposed to MCP. * Enable the flow execution tool in **MCP Tools**. * Confirm that the connected user has permission to run the flow. ## A cloud client cannot reach a self-hosted instance Localhost, private network addresses, firewalls, and invalid TLS certificates can prevent remote clients from reaching Puppetflow. Use a public HTTPS URL or connect from a client running inside the same network. --- --- url: https://docs.puppetflow.com/guide/live-tracking.md --- # Live Tracking Puppetflow streams the browser session in real time so you can watch exactly what your automation is doing. ## Watching a live run 1. Open a running run from the flow's **Runs** tab. 2. Select the **Live** tab. 3. Watch the browser viewport update in real time. Live view must be enabled on the instance. The interface shows: * a pulsing indicator on the **Live** tab * Current URL being visited * a status chip for connecting, connected, or session ended ## Interactive control The live stream is bidirectional. You can interact with the running browser: * **Mouse** - Move, click, and scroll are relayed to the browser. * **Keyboard** - Key presses are forwarded. * **Navigation** - Use the URL bar to navigate, or the back/forward buttons. This is useful for debugging or for stepping through flows that require manual input at certain points. ## Multiple viewers Multiple team members can watch the same run simultaneously. --- --- url: https://docs.puppetflow.com/guide/video-recording.md --- # Video Recording Every flow run can produce an MP4 video recording of the entire browser session, from start to finish. ## Enabling recording Recording is controlled at two levels: * **Flow settings** - Enable **Recording in output** under **Output & artifacts**. * **Action overrides** - Each webhook action can override the recording export setting. ## Viewing recordings Open a completed run and select **Recording**. While the run is active, the same tab is labelled **Live**. Recordings are also accessible via the REST API: ``` GET /api/v1/flows/{id}/runs/{runId}/recording ``` ## Retention Recordings follow the same access and retention rules as other run artifacts. --- --- url: https://docs.puppetflow.com/guide/artifacts.md --- # Artifacts Artifacts are files produced during a flow run. They give you tangible proof of what the automation did. ## Artifact types ### Screenshots PNG files captured with `$screenshot()`: ```js await $screenshot('after-login'); await $screenshot('invoice-page'); ``` Screenshots are auto-numbered if you don't provide a name (`screenshot_00`, `screenshot_01`, …). By default, all screenshots are included in the run artifacts. Pass `{ output: false }` to capture a screenshot for internal use without exporting it: ```js await $screenshot('debug', { output: false }); ``` ### Downloads Files downloaded during the run: ```js // Direct HTTP download using the page's cookies await $download('https://app.example.com/export.csv', 'report.csv'); // Browser-initiated download (click a download link) await $downloadFromBrowser('https://app.example.com/invoice.pdf', 'invoice.pdf'); // Wait for a browser-initiated download to complete await $clickElement('#download-btn'); const file = await $waitForFile(); ``` Downloaded files support the same `{ output: false }` option. ### Video recording An MP4 video of the entire browser session. See [Video Recording](/guide/video-recording) for details. ## Accessing artifacts ### In the UI Open a run's detail view. The artifacts section shows: * Thumbnail grid for screenshots. * File list for downloads. * Video player for recordings. ### Via the REST API List artifacts: ``` GET /api/v1/flows/{id}/runs/{runId}/artifacts/screenshots GET /api/v1/flows/{id}/runs/{runId}/artifacts/downloads ``` Download a specific file: ``` GET /api/v1/flows/{id}/runs/{runId}/artifacts/screenshots/after-login.png GET /api/v1/flows/{id}/runs/{runId}/artifacts/downloads/report.csv ``` Get the recording: ``` GET /api/v1/flows/{id}/runs/{runId}/recording ``` ## Export control Under **Output & artifacts**, each flow has three export toggles: * **Screenshots in output** - Include PNG files. * **Downloads in output** - Include downloaded files. * **Recording in output** - Include the MP4 video. Webhook actions can override these settings per action, so you can send different artifacts to different endpoints. ## File utilities Puppetflow provides several helper methods for working with files during a run: ```js // Unzip a downloaded file const files = await $unzipFile('archive.zip', 'extracted'); // List files in a directory const csvFiles = await $scanDirectory('extracted', '.csv'); // Move a downloaded file $moveDownloadedFile('old-name.csv', 'renamed.csv'); // Get the full path to a downloaded file const path = $getDownloadsPathFile('report.csv'); ``` See [Working with Downloaded Files](/guide/downloaded-files) for PDF and archive processing. ## Retention Artifacts follow the run's retention policy. When a run is deleted, manually or because of a retention limit, its artifacts are removed too. --- --- url: https://docs.puppetflow.com/reference/magic-methods.md --- # Flow API Reference Flow code can use Puppeteer alongside Puppetflow's helper functions and global objects. ## Flow objects | Object | Description | | --- | --- | | `$input` | Input argument passed to the flow. | | `$context` | Run metadata (`run_id`, `flow_id`, `legend`, `meta`), passed as the third argument of `run`. | | `$page` | Proxy to the Puppeteer [Page](https://pptr.dev/api/puppeteer.page) of the active named tab. | | `$browser` | The Puppeteer [Browser](https://pptr.dev/api/puppeteer.browser) instance. | | `$client` | CDP session for low-level Chrome DevTools Protocol calls. | | `$viewportWidth`, `$viewportHeight` | Effective browser viewport dimensions. | | `$now`, `$today` | Luxon `DateTime` values for the current time and start of today. | See [Flow Objects](./flow-api/globals) for details on the input structure and context metadata. The editor builds this catalog from the same runtime metadata used by the help panel. Type `$` to browse every helper, `$page.` or `$client.` for the installed Puppeteer API, and `$$` for accessible snippets. Resource parameters autocomplete readable names while inserting stable IDs. ## Categories ### [Navigation](./flow-api/navigation) Page navigation, viewport control, cookie persistence and login helpers. `$gotoUrl`, `$gotoTab`, `$setViewport`, `$screenshot`, `$loginRemember`, `$saveCookies`, `$loadCookies`, `$clearCookies` ### [Interaction & Selectors](./flow-api/interaction) Click, type, scroll, and query elements - including shadow DOM traversal. * Input: `$keyboardSpeed`, `$keyboardPress`, `$keyboardShortcut`, `$fillInput` * Click and scroll: `$clickElement`, `$clickElementAtIndex`, `$clickAtCoordinates`, `$scrollByPixels`, `$scrollToElement` * Selectors: `$selectOneElement`, `$selectManyElements`, `$attributesFromOne`, `$attributesFromMany`, `$selectShadow`, `$shadowInputFill`, `$waitForSelectorCondition` ### [Page Evaluation](./flow-api/page-evaluation) Run JavaScript inside the page context, send HTTP requests and capture browser network traffic. `$injectScriptLibrary`, `$bridgeEvaluate`, `$httpRequest`, `$sniffNetwork`, `$stopSniffing` ### [Files & Downloads](./flow-api/files) Download, upload, unzip, scan directories, and work with PDFs. `$writeFile`, `$download`, `$downloadFromBrowser`, `$waitForFile`, `$upload`, `$unzipFile`, `$scanDirectory`, `$scanDownloadsDirectory`, `$moveDownloadedFile`, `$getDownloadsPathFile`, `$pdfSearch`, `$pdfGetText` ### [Data Tables](#data-tables) Query rows, update data, branch on row existence, and manage data tables. `$dataTableInsertRow`, `$dataTableUpdateRows`, `$dataTableUpsertRows`, `$dataTableRowExists`, `$dataTableRowDoesNotExist`, `$dataTableGetRows`, `$dataTableDeleteRows`, `$dataTableCreate`, `$dataTableDelete`, `$dataTableList`, `$dataTableUpdate` ### [Utilities](./flow-api/utilities) Timing, logging, variables, date helpers and pattern matching. `$sleep`, `$stopwatchStart`, `$stopwatchCheck`, `$stopwatchStop`, `$if`, `$ifEmpty`, `$max`, `$min`, `$log`, `$legend`, `$meta`, `$vars`, `$totp`, `$matchSequence`, `$parseDates`, `$sortDates`, `$currentDate`, `$currentDateMinusOneMonth`, `$currentDatePlusOneMonth` ### [Response & Output](./flow-api/response) Build the flow's return value. `$setOutput`, `$generateResponse`, `$generateResponseSuccess`, `$generateResponseError`, `$stopSuccess`, `$stopFail` ### [Notifications](./flow-api/notifications) Send messages to Slack, Discord, or Telegram and pause for human validation. `$notify`, `$waitHumanValidation` ### [Email](./flow-api/email) Wait for incoming emails through mailbox watchers. `$waitForEmail` ### AI Send prompts to configured AI models or let a vision model operate the browser. `$mcpClientTool`, `$aiMessage`, `$aiControl` ### [Debugging](./flow-api/debugging) Interactive breakpoints for step-by-step debugging. `$breakpoint` ## Data Tables Data Table helpers use stable table IDs that start with `dtbl_`. Existing-resource helpers accept `tableId` as their only resource identifier. In the code editor, autocomplete displays the table name and inserts its ID. Rows are returned as plain objects. Custom values use their column names alongside the system fields: ```js { id: 42, email: 'person@example.com', score: 18, active: true, processed_at: '2026-08-27T20:30:00+00:00', created_at: '2026-08-27 20:30:00', updated_at: '2026-08-27 20:35:00', } ``` ### Values Write values as an object keyed by custom column name. Omitted columns and explicit `null` values are stored as `NULL`. ```js const values = { email: 'person@example.com', score: 18, active: true, processed_at: null, }; ``` The accepted value depends on the column type: | Type | Accepted values | | --- | --- | | `string` | A string or `null`. | | `number` | A finite JavaScript number or `null`. | | `boolean` | `true`, `false`, or `null`. | | `datetime` | An ISO 8601 date and time string or `null`. Values are stored in UTC. | System fields cannot be written through the Values object. ### Filters Filters are arrays because one query may contain several conditions, including more than one condition on the same column. ```js const filters = [ { keyName: 'status', condition: 'eq', keyValue: 'active' }, { keyName: 'score', condition: 'gte', keyValue: 10 }, ]; ``` Each filter has: | Field | Description | | --- | --- | | `keyName` | Custom or system column name. | | `condition` | Comparison to apply. | | `keyValue` | Comparison value. Omit it for conditions that do not need a value. | Conditions depend on the column type: | Column type | Conditions | | --- | --- | | String | `eq`, `neq`, `like`, `ilike`, `isEmpty`, `isNotEmpty` | | Number | `eq`, `neq`, `gt`, `gte`, `lt`, `lte`, `isEmpty`, `isNotEmpty` | | Datetime | `eq`, `neq`, `gt`, `gte`, `lt`, `lte`, `isEmpty`, `isNotEmpty` | | Boolean | `eq`, `neq`, `isTrue`, `isFalse`, `isEmpty`, `isNotEmpty` | `like` contains the supplied text with case-sensitive matching. `ilike` is case-insensitive. Percent and underscore characters are treated as ordinary text, not SQL wildcards. Use `options.matchType` to combine filters: * `allConditions` requires every condition and is the default. * `anyCondition` accepts a row when at least one condition matches. ### `$dataTableInsertRow(tableId, values)` {#data-table-insert-row} Insert one row and return the complete stored row. ```js const row = await $dataTableInsertRow( 'data-table-id', { email: 'person@example.com', active: true, }, ); ``` An empty Values object is valid and creates a row containing `NULL` in every custom column. ### `$dataTableUpdateRows(tableId, filters, values, options?)` {#data-table-update-rows} Update all matching rows and return their stored values. ```js const rows = await $dataTableUpdateRows( 'data-table-id', [{ keyName: 'active', condition: 'isFalse' }], { active: true }, { matchType: 'allConditions', dryRun: false, }, ); ``` At least one filter is required. Set `options.updateAll` to `true` to update every row explicitly. Set `options.dryRun` to `true` to return before and after rows without saving changes. ### `$dataTableUpsertRows(tableId, filters, values, options?)` {#data-table-upsert-rows} Update matching rows. When nothing matches, insert one row using `values`. ```js const rows = await $dataTableUpsertRows( 'data-table-id', [{ keyName: 'email', condition: 'eq', keyValue: 'person@example.com' }], { email: 'person@example.com', active: true, }, ); ``` Filters are required. Filter values are not copied into a newly inserted row, so include those values in the Values object when needed. `matchType` and `dryRun` are available in `options`. ### `$dataTableRowExists(tableId, filters, options?)` {#data-table-row-exists} Return `true` when at least one row matches. ```js const exists = await $dataTableRowExists( 'data-table-id', [{ keyName: 'email', condition: 'eq', keyValue: 'person@example.com' }], ); ``` ### `$dataTableRowDoesNotExist(tableId, filters, options?)` {#data-table-row-does-not-exist} Return `true` when no row matches. Both existence helpers require filters and accept `options.matchType`. ```js const isNewCustomer = await $dataTableRowDoesNotExist( 'data-table-id', [{ keyName: 'email', condition: 'eq', keyValue: 'ada@example.com' }], ); ``` In a nodal flow, these helpers are represented by conditional nodes with `true` and `false` outputs. ### `$dataTableGetRows(tableId, filters?, options?)` {#data-table-get-rows} Return matching rows. ```js const rows = await $dataTableGetRows( 'data-table-id', [ { keyName: 'score', condition: 'gte', keyValue: 10 }, { keyName: 'active', condition: 'isTrue' }, ], { matchType: 'allConditions', limit: 50, orderBy: 'updated_at', direction: 'desc', }, ); ``` Options: | Option | Default | Description | | --- | --- | --- | | `matchType` | `allConditions` | Combine filters with all or any matching. | | `limit` | `50` | Maximum rows to return, from 1 to 10000. | | `returnAll` | `false` | Return every matching row and ignore `limit`. | | `orderBy` | `updated_at` | Custom or system column used for sorting. | | `direction` | `desc` | `asc` or `desc`. | Pass an empty array or omit `filters` to query the whole table. ### `$dataTableDeleteRows(tableId, filters, options?)` {#data-table-delete-rows} Delete matching rows and return the rows that were deleted. ```js const deleted = await $dataTableDeleteRows( 'data-table-id', [{ keyName: 'status', condition: 'eq', keyValue: 'expired' }], { dryRun: true }, ); ``` Filters are always required. Set `dryRun` to `true` to preview before and after rows without deleting them. ### `$dataTableCreate(name, columns?, options?)` {#data-table-create} Create a data table and return its ID. The `id`, `created_at`, and `updated_at` system columns are added automatically. ```js const tableId = await $dataTableCreate( 'contacts', [ { name: 'email', type: 'string' }, { name: 'score', type: 'number' }, { name: 'active', type: 'boolean' }, { name: 'processed_at', type: 'datetime' }, ], { description: 'Contacts collected by flows', visibility: 'team', teamId: 'team-id', }, ); const row = await $dataTableInsertRow(tableId, { email: 'ada@example.com' }); ``` Column types are immutable after creation. Options can set `description`, `visibility`, `ownerId`, and `teamId`. Visibility is `owner` (the default), `team`, or `workspace`. ### `$dataTableDelete(tableId)` {#data-table-delete} Permanently delete a table and all of its rows. The helper returns the deleted table ID. ```js const deletedTableId = await $dataTableDelete('data-table-id'); ``` ### `$dataTableList(options?)` {#data-table-list} Return accessible data tables with their metadata and custom columns. Optional filters can narrow the list by visibility, owner, or team. ```js const tables = await $dataTableList({ visibility: 'workspace' }); ``` ### `$dataTableUpdate(tableId, changes)` {#data-table-update} Update a table's name, description, visibility, owner, or team without changing its ID, physical storage, columns, or rows. ```js const table = await $dataTableUpdate( 'data-table-id', { name: 'archived_contacts', description: 'Archived contact records', visibility: 'owner', }, ); ``` ### Permissions and errors Read helpers require access to the data table. Row mutations and table management operations require management access. Permissions are evaluated for the user who triggered the flow run. Unknown columns, incompatible values, invalid conditions, missing filters, and inaccessible resources stop the helper with an error. Use dry-run mode before broad updates or deletions. See [Data Tables in the Flows guide](/guide/flows#data-tables) for the table editor and [Using Data Tables](/guide/nodal-flows#using-data-tables) for visual nodes. ## AI AI methods require an active [AI integration](/guide/integrations#ai-integrations) and an accessible [AI model](/guide/flows#ai-models). Each configured `AiModel` contains exactly one provider model. Pass its `AiModel.id`, which starts with `aim_`. ### `$mcpClientTool(credentialId, include?, tools?, options?)` {#mcp-client-tool} Create a toolkit from a stored MCP client credential for use with `$aiMessage` or `$aiControl`. Use `include` and `tools` to restrict the exposed tools. `options.maxToolCalls` limits tool calls and defaults to `20`. ### `$aiMessage(aiModelId, message, options?)` {#ai-message} Send a text prompt through the provider model configured on an `AiModel`. ```js const response = await $aiMessage( 'ai-model-id', 'Summarize the current invoice', { system: 'Answer in one sentence.', messages: [ { role: 'user', content: 'The customer prefers concise answers.' }, ], temperature: 0.2, top_p: 1, max_tokens: 200, timeout: 120000, outputMode: 'text', }, ); console.log(response.text); ``` | Parameter | Description | | --- | --- | | `aiModelId` | Configured `AiModel.id`, starting with `aim_`. | | `message` | Current user message. | | `options.system` | System instructions. | | `options.messages` | Previous `{ role, content }` messages. Roles are `user`, `assistant`, or `system`. | | `options.temperature` | Provider sampling temperature. | | `options.top_p` | Provider nucleus sampling probability. | | `options.max_tokens` | Maximum output tokens. | | `options.timeout` | Request timeout in milliseconds. Default: `120000`. | | `options.outputMode` | `text`, `json`, or `schema`. Default: `text`. | | `options.schema` | JSON Schema. Supplying it selects `schema` mode unless `outputMode` is `text`. | | `options.maxToolCalls` | Maximum MCP tool calls, from 1 to 100. Default: `20`. | The response contains `text`, provider `content`, `usage`, `model`, `finishReason`, and `provider`. In `json` or `schema` mode it also contains parsed `json`, or `null` when the text is not valid JSON. Structured output availability depends on the selected AI model. ### `$aiControl(aiModelId, prompt, options?)` {#ai-control} Repeatedly capture the current browser viewport, ask a vision-capable model for the next restricted action, validate that action, and execute it. ```js const result = await $aiControl( 'ai-model-id', 'Submit the completed checkout form', { maxIterations: 10, timeout: 120000, screenshotQuality: 65, persistScreenshots: false, maxTokens: 4000, temperature: 0.1, allowPuppeteerFallback: true, }, ); ``` | Option | Default | Description | | --- | --- | --- | | `maxIterations` | `10` | Maximum screenshot and action cycles, from 1 to 50. | | `timeout` | `120000` | Overall timeout in milliseconds, from 5000 to 900000. | | `screenshotQuality` | `65` | JPEG quality, from 20 to 90. | | `persistScreenshots` | `false` | Save each decision screenshot as a run artifact. | | `maxTokens` | `4000` | Maximum output tokens for each decision, from 4000 to 32000. | | `temperature` | provider default | Sampling temperature for each decision. It is not sent unless specified. | | `maxToolCalls` | `20` | Maximum MCP tool calls, from 1 to 100. | | `allowPuppeteerFallback` | `true` | Allow restricted Puppeteer actions after a Puppetflow action fails and coordinate clicks for purely visual targets. | The result contains: | Field | Description | | --- | --- | | `status` | `success`, `error`, or `max_iterations`. | | `message` | Final model or execution message. | | `result` | Optional value returned by the model's finish action. | | `iterations` | Number of screenshot and decision cycles used. | | `actions` | Validated actions and their execution results. Values entered into fields are redacted from this log. | | `model` | AI model that produced the result. | | `usage` | Provider usage information when available. | The generated program is limited to Puppetflow navigation, click, fill, scroll, wait, shadow DOM, and finish actions. It cannot run arbitrary page code. Puppeteer fallback has the same restrictions. It is normally available only after a Puppetflow action fails and cannot be mixed with Puppetflow actions in one generated program. Browser page content is treated as untrusted data, not as model instructions. --- --- url: https://docs.puppetflow.com/reference/api.md --- # REST API Trigger flows, list runs, fetch results, and download artifacts programmatically. ## Authentication Routes under `/api/v1` require an API key passed in the `Authorization` header: ``` Authorization: Bearer pk_your_api_key_here ``` Click your name or avatar at the bottom-left of the sidebar, then open **Profile > API Keys**. The full key is shown only once when it is created, so copy it before closing the dialog. ## Base URL ``` https://your-instance.com/api/v1 ``` ## Path parameters Most endpoints use the same path parameters: | Parameter | Description | | --- | --- | | `{id}` | Flow ID (`flow_...`). | | `{run}` | Run ID (integer). | | `{workspace}` | Workspace ID (`work_...`). Workspace detail and update endpoints also accept a lookup key. | | `{user}` | User ID (`user_...`). | | `{team}` | Team ID (`team_...`). | ## Endpoints ### [Flows & Folders](./api/flows) List or search flows, inspect a flow, trigger a run, and browse folders. `GET /flows`, `GET /flows/search`, `GET /flows/{id}`, `POST /flows/{id}/trigger`, `GET /folders` ### Workspaces List, inspect, create, and update workspaces. Deletion is intentionally not exposed through the REST API. `GET /workspaces`, `POST /workspaces`, `GET /workspaces/{workspace}`, `PATCH /workspaces/{workspace}`, `PUT /workspaces/{workspace}` #### List workspaces ```http GET /workspaces ``` Returns the workspaces visible to the API key owner. | Param | Type | Description | | --- | --- | --- | | `search` | string | Search by workspace name, slug, lookup key, or ID. | | `limit` | integer | Maximum results, from 1 to 100. Default: 50. | #### Create or upsert a workspace ```http POST /workspaces ``` `lookup_key` is an optional globally unique, stable identifier. When it does not exist, the endpoint creates a workspace and returns `201`. When it already exists, the endpoint updates that workspace and returns `200` instead of creating a duplicate. Creating a new workspace requires an instance admin or a user with workspace creation enabled. Updating an existing workspace by lookup key requires an instance admin or workspace admin/manager. ```json { "name": "Production", "lookup_key": "production_eu", "preferences": { "viewport_width": 1440, "viewport_height": 900 }, "appearance": { "icon_type": "emoji", "icon_value": ":rocket:" } } ``` `name` is required when a new workspace is created. It may be omitted when `lookup_key` resolves to an existing workspace. #### Get a workspace ```http GET /workspaces/{workspace} ``` Returns the workspace name, lookup key, preferences, appearance, and resource counts. `{workspace}` may be its ID or lookup key. #### Update a workspace ```http PATCH /workspaces/{workspace} ``` `PUT /workspaces/{workspace}` is also accepted and behaves like `PATCH`: omitted fields are left unchanged. `{workspace}` may be the ID or lookup key. The API key owner must be an instance admin or workspace admin/manager. The API can update: You may send these fields at the top level or grouped under `preferences` and `appearance`. | Field | Type | Description | | --- | --- | --- | | `name` | string | Workspace display name. | | `lookup_key` | string | null | Globally unique API identifier. Must start with a lowercase letter and contain only lowercase letters, numbers, underscores, or hyphens. | | `runs_retention_default` | integer | Default run retention for flows without an override. | | `runs_retention_max` | integer | Maximum retention a flow can request. | | `default_flow_timeout_seconds` | integer | Default flow timeout. | | `max_flow_timeout_seconds` | integer | Maximum flow timeout. | | `max_retries_default` | integer | Default retry count. | | `max_retries_max` | integer | Maximum retry count. | | `expires_at` | datetime | null | Optional workspace expiration date. | | `viewport_width` | integer | Default browser viewport width. | | `viewport_height` | integer | Default browser viewport height. | | `keyboard_speed` | integer | Default keyboard delay, from 0 to 10000 milliseconds. | | `default_user_agent` | string | null | Default printable ASCII browser user agent. | | `default_language` | string | Default browser language. | | `allow_trigger_advertising` | boolean | Legacy stored preference. Trigger and action access is controlled by their Visibility. | | `require_two_factor` | boolean | Require 2FA for workspace members when the instance entitlement is enabled. | | `default_flow_code` | string | null | Default JavaScript template for new code flows. | | `icon_type` | `emoji` | `color` | API-managed workspace icon type. Uploaded icons are not managed by this endpoint. | | `icon_value` | string | null | Emoji token or display value. | | `icon_color` | string | null | Hex color for color icons. | Workspace settings remain capped by instance-level license limits. For example, retention, timeout, and retry values may be reduced to the maximum allowed by the instance. ### Users Create, inspect, and update users for tenant provisioning. These endpoints require an instance admin API key. `GET /users`, `POST /users`, `GET /users/{user}`, `PATCH /users/{user}`, `PUT /users/{user}` #### Create or update a user ```http POST /users PATCH /users/{user} ``` `PUT /users/{user}` is also accepted and behaves like `PATCH`: omitted fields are left unchanged. ```json { "first_name": "Jane", "last_name": "Doe", "email": "jane@example.com", "password": "secret-password", "role": "member", "can_create_workspace": true, "workspaces": [ { "id": "work_k8Zt3xQ9mA2f", "role": "manager" } ], "team_ids": ["team_k8Zt3xQ9mA2f"] } ``` `name` is the stored profile name. If omitted, `first_name` and `last_name` are combined. `team_ids` requires the Teams feature: * When `workspaces` is present, every team must belong to one of those workspaces. * When `workspaces` is omitted, Puppetflow creates the required workspace memberships. ### Teams Create, inspect, and update workspace teams, then assign users to teams. Team deletion is not exposed through the REST API. `GET /workspaces/{workspace}/teams`, `POST /workspaces/{workspace}/teams`, `GET /teams/{team}`, `PATCH /teams/{team}`, `PUT /teams/{team}` #### Team members ```http POST /teams/{team}/members PUT /teams/{team}/members PUT /workspaces/{workspace}/members/{member}/teams ``` Use `POST /teams/{team}/members` to add one or more existing workspace members and `PUT /teams/{team}/members` to replace a team's complete member list: ```json { "member_ids": ["user_k8Zt3xQ9mA2f"] } ``` Use `PUT /workspaces/{workspace}/members/{member}/teams` with `{"team_ids": ["team_k8Zt3xQ9mA2f"]}` to replace one member's team assignments. Users must already belong to the workspace. ### [Runs](./api/runs) List, search, and inspect flow runs. `GET /runs/search`, `GET /flows/{id}/runs`, `GET /flows/{id}/runs/search`, `GET /flows/{id}/runs/{run}`, `GET /flows/{id}/runs/{run}/result`, `POST /flows/{id}/runs/{run}/continue` ### [Artifacts](./api/artifacts) List, download screenshots/files, fetch recordings, and read captured response bodies. `GET /flows/{id}/runs/{run}/artifacts/{type}`, `GET /flows/{id}/runs/{run}/artifacts/{type}/{filename}`, `GET /flows/{id}/runs/{run}/recording`, `GET /flows/{id}/runs/{run}/recording/lastshot`, `GET /flows/{id}/runs/{run}/sniff-bodies/{captureId}` ## Webhook triggers Webhook triggers have their own public endpoint that does **not** require API key authentication: ```http POST /api/trigger/{token} ``` The token is unique per trigger. The configured trigger input is always used. The request body is added to `$input` when **Merge POST data into input** is enabled. Successful requests return `status`, `run_id`, and `flow_id`. The endpoint accepts payloads up to 10 MB, 5,000 fields, and 32 levels of nesting. It is throttled per IP using `TRIGGER_RATE_LIMIT_PER_MINUTE`, which defaults to 120 requests per minute. ## Repository webhooks ```http POST /api/webhooks/github/{webhookId} POST /api/webhooks/gitlab/{webhookId} POST /api/webhooks/gitea/{webhookId} POST /api/webhooks/bitbucket/{webhookId} ``` Handles repository push events for configured branches. Payloads are limited to 10 MB and requests are throttled per IP using `REPOSITORY_WEBHOOK_RATE_LIMIT_PER_MINUTE`, which defaults to 300 requests per minute. ## MCP server Puppetflow includes an MCP-compatible JSON-RPC server for exposing workspace flows as tools. ### Universal endpoint The recommended entry point for Claude, ChatGPT, and other OAuth-capable clients is the central Puppetflow broker: ```http POST https://mcp.puppetflow.com/mcp Authorization: Bearer broker_access_token_here ``` The broker asks for the Puppetflow instance, then delegates sign-in and workspace selection to it. MCP requests are proxied to the selected workspace. OAuth discovery uses `/.well-known/oauth-protected-resource/mcp` and `/.well-known/oauth-authorization-server` on `mcp.puppetflow.com`. Artifacts use opaque `https://mcp.puppetflow.com/artifacts/{id}` URLs tied to the connection. ### Token endpoint Workspace MCP tokens call the global MCP endpoint: ```http POST /api/mcp-server/http Authorization: Bearer mcp_your_token_here ``` Artifact URLs returned by MCP tools use: ```http GET /api/mcp-server/flows/{id}/runs/{run}/artifacts/{type}/{filename} ``` ### OAuth endpoints OAuth MCP clients call either the instance-level endpoint, where the user picks the workspace during authorization: ```http POST /mcp Authorization: Bearer oauth_access_token_here ``` or the workspace-scoped endpoint, which locks the client to one workspace: ```http POST /api/workspaces/{workspace}/mcp-server/http Authorization: Bearer oauth_access_token_here ``` Artifact URLs returned by OAuth-authenticated MCP tools use the same prefix as the endpoint that served the call: ```http GET /mcp/flows/{id}/runs/{run}/artifacts/{type}/{filename} GET /api/workspaces/{workspace}/mcp-server/flows/{id}/runs/{run}/artifacts/{type}/{filename} ``` OAuth clients use the authorization code flow with PKCE S256 and the `mcp` scope. MCP clients discover the authorization endpoints from the protected-resource challenge: ```http GET /oauth/authorize POST /oauth/token POST /oauth/register POST /oauth/register/{workspace} GET /.well-known/oauth-protected-resource/mcp GET /.well-known/oauth-authorization-server GET /.well-known/oauth-protected-resource/api/workspaces/{workspace}/mcp-server/http GET /.well-known/oauth-authorization-server/workspaces/{workspace} ``` Dynamic Client Registration lets compatible clients create a public OAuth client automatically. Administrators can also create and revoke fixed workspace OAuth clients under **Workspace > Settings > MCP**. ### JSON-RPC methods The server supports: | Method | Description | | --- | --- | | `initialize` | Returns protocol version, tool capabilities, and server info. | | `tools/list` | Lists enabled tools for the workspace MCP settings. | | `tools/call` | Calls one enabled tool with JSON arguments. | Tool call responses include both text content and `structuredContent`. Requests must use `Content-Type: application/json`. The `Accept` header may be `application/json` or `*/*`. Supported `MCP-Protocol-Version` values are `2025-03-26`, `2025-06-18`, and `2025-11-25`. JSON-RPC notifications return `204 No Content`. ### Tools | Tool | Description | | --- | --- | | `search_flows` | Search flows visible to the connected user. | | `get_flow_details` | Get the details and configuration of an exposed flow. | | `get_flow_source` | Get editable code or the complete nodal graph for an accessible flow. | | `list_folders` | List visible flow folders. | | `get_flow_creation_options` | Get allowed folders, teams, and visibility scopes for a new flow. | | `get_nodal_catalog` | Read the runtime helper and visual-node catalog. | | `list_flow_resources` | List resources that may be referenced while authoring a flow or snippet. | | `write_code_flow` | Create or update a JavaScript flow. | | `write_nodal_flow` | Create or update a visual flow. | | `publish_flow` | Publish the editable flow draft as a new version. | | `unpublish_flow` | Unpublish a flow without deleting its history or draft. | | `list_flow_triggers` | List cron and webhook triggers for an exposed flow. | | `create_flow_trigger` | Create a cron or webhook trigger. | | `update_flow_trigger` | Update a flow trigger. | | `delete_flow_trigger` | Permanently delete a flow trigger. | | `list_flow_actions` | List post-run webhook actions for an exposed flow. | | `create_flow_action` | Create a post-run webhook action. | | `update_flow_action` | Update a flow action. | | `delete_flow_action` | Permanently delete a flow action. | | `search_snippets` | Search visible snippets. | | `get_snippet_source` | Get editable source for an accessible snippet. | | `get_snippet_creation_options` | Get allowed teams and visibility scopes for a new snippet. | | `write_code_snippet` | Create or update a JavaScript snippet. | | `write_nodal_snippet` | Create or update a visual snippet. | | `publish_snippet` | Publish the editable snippet draft as a new version. | | `unpublish_snippet` | Unpublish a snippet without deleting its history or draft. | | `search_runs` | Search runs visible to the connected user. | | `list_flow_runs` | List recent runs for an exposed flow. | | `run_flow` | Execute an exposed flow with optional JSON input. | | `get_run` | Inspect an MCP-visible run. | | `get_run_result` | Fetch the run output. | | `continue_human_validation` | Continue a run waiting for human validation. | | `list_artifacts` | List screenshots or downloads for a run. | | `get_latest_screenshot` | Return the latest screenshot URL for a run or flow. | | `download_artifact` | Return a secure download URL for a specific artifact. | | `get_recording` | Return a secure recording URL for a run. | | `get_recording_lastshot` | Return the final recording frame URL. | | `get_current_workspace` | Read the connected workspace configuration. | | `update_current_workspace` | Update the connected workspace configuration. | | `list_workspace_members` | List visible workspace members. | | `list_teams` | List workspace teams. | | `get_team` | Get a team and its members. | | `create_team` | Create a workspace team. | | `update_team` | Rename a workspace team. | | `add_team_members` | Add workspace members to a team. | | `replace_team_members` | Replace a team's complete member list. | | `set_member_teams` | Replace one member's team assignments. | Every tool declares a human-readable title and read-only or destructive annotations. MCP runs are opt-in per workspace and per flow. A flow must be visible to the connected user and have **Available in MCP** enabled before it can be executed. ## Error responses Most resource and permission errors use: ```json { "error": "Flow not found." } ``` | Code | Meaning | | --- | --- | | `401` | Missing or invalid API key. | | `403` | API key lacks permission for this resource. | | `404` | Flow, run, workspace, or artifact not found. | | `422` | Validation error (invalid type, bad input). | | `429` | Run quota reached. | Validation and quota errors use a `message` field, and validation responses can also include an `errors` object. ## Rate limits Authenticated `/api/v1` routes are not rate limited, but flow runs depend on available queue workers. Public endpoints are throttled per IP: * Flow trigger webhooks: 120 requests per minute by default * Repository webhooks: 300 requests per minute by default Schedule triggers are evaluated once per minute. --- --- url: https://docs.puppetflow.com/reference/api/flows.md --- # Flows & Folders ## List flows ```http GET /flows ``` Returns flows accessible by the authenticated user. ### Query parameters | Param | Type | Description | | --- | --- | --- | | `search` | string | Search by name, description, or ID. | | `name` | string | Filter by flow name. | | `type` | `code` | `nodal` | Filter by flow type. `flow_type` is accepted as an alias. | | `folder_id` | string | Filter by folder ID (`fld_...`). | | `limit` | integer | Maximum results, from 1 to 100. Default: 50. | ### Response `200` ```json [ { "id": "flow_k8Zt3xQ9mA2f", "name": "Invoice scraper", "description": "Scrapes invoices from the vendor portal.", "flow_type": "code", "folder_id": "fld_R7mP2qX9vK4c", "workspace_folder_id": null, "is_published": true, "queue_index": null, "default_inputs": null, "updated_at": "2026-03-15T10:30:00Z" } ] ``` | Field | Type | Description | | --- | --- | --- | | `id` | string | Flow ID (`flow_...`). | | `name` | string | Flow name. | | `description` | string | null | Flow description. | | `flow_type` | `code` | `nodal` | Flow type. | | `folder_id` | string | null | Personal parent folder ID. | | `workspace_folder_id` | string | null | Workspace or team parent folder ID. | | `is_published` | boolean | Whether the flow is published. | | `queue_index` | integer | null | Queue lane index when queued execution is enabled. | | `default_inputs` | object | null | Default input values used when triggering the flow. | | `updated_at` | datetime | Last update timestamp. | *** ## Search flows ```http GET /flows/search ``` Alias of `GET /flows`. It accepts the same filters and returns the same response. *** ## Get a flow ```http GET /flows/{id} ``` Returns the current definition and settings of a flow accessible to the authenticated user. ### Errors | Code | Description | | --- | --- | | `403` | API key lacks permission for this flow. | | `404` | Flow not found. | *** ## Trigger a flow ```http POST /flows/{id}/trigger ``` Dispatches a new run and returns immediately. `{id}` is the flow ID. ### Request body Any JSON object, merged into `$input` as flow input. ```json { "url": "https://example.com", "username": "user@example.com" } ``` ### Response `202` ```json { "run_id": 42, "flow_id": "flow_k8Zt3xQ9mA2f", "status": "pending" } ``` | Field | Type | Description | | --- | --- | --- | | `run_id` | integer | ID of the newly created run. | | `flow_id` | string | Flow ID. | | `status` | string | Always `"pending"` on trigger. | Poll `GET /flows/{id}/runs/{run_id}` to check completion. ### Errors | Code | Description | | --- | --- | | `403` | API key lacks permission, the flow has no published version, or its repository source is unavailable. | | `404` | Flow not found. | | `429` | Run quota reached. The response uses a `message` field. | *** ## List folders ```http GET /folders ``` Returns folders for the authenticated user. ### Query parameters | Param | Type | Description | | --- | --- | --- | | `search` | string | Search by folder name. | ### Response `200` ```json [ { "id": "fld_R7mP2qX9vK4c", "name": "Production", "parent_id": null, "is_shared": true } ] ``` | Field | Type | Description | | --- | --- | --- | | `id` | string | Folder ID (`fld_...`). | | `name` | string | Folder name. | | `parent_id` | string | null | Parent folder ID (`null` for root folders). | | `is_shared` | boolean | Whether the folder is shared with the workspace. | --- --- url: https://docs.puppetflow.com/reference/api/runs.md --- # Runs ## List runs ```http GET /flows/{id}/runs ``` Returns a paginated list of runs for the given flow. ### Query parameters | Param | Type | Default | Description | | --- | --- | --- | --- | | `status` | string | - | Filter by status: `pending`, `running`, `success`, `error`, `cancelled`. | | `per_page` | integer | `20` | Items per page. | | `page` | integer | `1` | Page number. | | `logs` | `0` | `1` | `0` | Include `console_logs` in the response. | | `code` | `0` | `1` | `0` | Include `code_snapshot` in the response. | Secret values are always masked with `••••••••` in API responses. ### Response `200` ```json { "data": [ { "id": 42, "flow_id": "flow_k8Zt3xQ9mA2f", "status": "success", "output": { "status": "success", "message": "Done" }, "error_message": null, "duration_ms": 12340, "created_at": "2026-03-15T10:30:00Z", "updated_at": "2026-03-15T10:30:12Z" } ], "current_page": 1, "last_page": 3, "per_page": 20, "total": 58 } ``` ### Pagination | Field | Type | Description | | --- | --- | --- | | `data` | Run\[] | Array of run objects. | | `current_page` | integer | Current page number. | | `last_page` | integer | Last page number. | | `per_page` | integer | Items per page. | | `total` | integer | Total number of runs. | *** ## Search runs across flows ```http GET /runs/search ``` Returns a paginated list of runs visible to the authenticated user. ### Query parameters | Param | Type | Description | | --- | --- | --- | | `workspace_id` | string | Limit results to a workspace ID. | | `flow_id` | string | Limit results to a flow ID. | | `flow_search` | string | Search by run ID, flow name, or flow ID. | | `search` | string | Alias for `flow_search`. | | `status` | string | Filter by one run status. | | `statuses[]` | string\[] | Filter by several run statuses. | | `date_from` | datetime | Earliest creation date. | | `date_to` | datetime | Latest creation date. | | `triggered_by` | string | Filter by triggering user ID (`user_...`). | | `legend` | string | Filter by run legend. | | `duration_min_ms` | integer | Minimum duration in milliseconds. | | `duration_max_ms` | integer | Maximum duration in milliseconds. | | `meta_presence` | `any` | `none` | Require metadata to be present or absent. Pro plan and above. | | `meta_predicate` | `and` | `or` | How multiple metadata filters are combined. Pro plan and above. | | `per_page` | integer | Items per page, up to 100. Default: 50. | | `page` | integer | Page number. | | `logs` | `0` | `1` | Include console logs. | | `code` | `0` | `1` | Include the code snapshot. | Metadata filters use `meta_filters[index][key]`, `meta_filters[index][operator]`, and `meta_filters[index][value]`. Supported operators are `contains`, `equals`, `not_equals`, `starts_with`, `ends_with`, `gt`, `gte`, `lt`, `lte`, and `exists`. Metadata search requires the Search Runs by Metadata entitlement, available from the Pro plan. When the entitlement is disabled, metadata parameters are ignored. *** ## Search runs for a flow ```http GET /flows/{id}/runs/search ``` Returns a lightweight list of runs, suitable for autocomplete or search UIs. Returns at most 50 runs. ### Query parameters | Param | Type | Description | | --- | --- | --- | | `search` | string | Search by run ID or status. | | `status` | string | Filter by status: `pending`, `running`, `success`, `error`, `cancelled`. | ### Response `200` ```json [ { "id": 42, "flow_id": "flow_k8Zt3xQ9mA2f", "trigger_id": null, "status": "success", "legend": null, "duration_ms": 12340, "created_at": "2026-03-15T10:30:00Z" } ] ``` | Field | Type | Description | | --- | --- | --- | | `id` | integer | Run ID. | | `flow_id` | string | Parent flow ID. | | `trigger_id` | string | null | Trigger ID when the run came from a trigger. | | `status` | string | Run status. | | `legend` | string | null | Run legend. | | `duration_ms` | integer | null | Run duration in milliseconds. | | `created_at` | datetime | Creation timestamp. | *** ## Get a run ```http GET /flows/{id}/runs/{run} ``` Returns the full details of a specific run. ### Query parameters | Param | Type | Default | Description | | --- | --- | --- | --- | | `logs` | `0` | `1` | `0` | Include `console_logs` in the response. | | `code` | `0` | `1` | `0` | Include `code_snapshot` in the response. | ### Response `200` ```json { "id": 42, "flow_id": "flow_k8Zt3xQ9mA2f", "status": "success", "output": { "status": "success", "message": "Processed 3 invoices", "invoiceIds": [1, 2, 3] }, "error_message": null, "duration_ms": 12340, "created_at": "2026-03-15T10:30:00Z", "updated_at": "2026-03-15T10:30:12Z", "waiting_for_human_validation": false, "human_validation_wait_id": null, "artifacts": { "downloads": [], "screenshots": [], "recording": null } } ``` ### Run object | Field | Type | Description | | --- | --- | --- | | `id` | integer | Run ID. | | `flow_id` | string | Parent flow ID. | | `status` | string | `pending`, `running`, `success`, `error`, or `cancelled`. | | `output` | object | null | Flow output data. | | `error_message` | string | null | Error message if the run failed. | | `duration_ms` | integer | null | Run duration in milliseconds. | | `console_logs` | array | Console log entries. Present only when `logs=1`. | | `code_snapshot` | string | Code at run time. Present only when `code=1`. | | `waiting_for_human_validation` | boolean | Whether the run is paused by `$waitHumanValidation()`. | | `human_validation_wait_id` | string | null | UUID to pass as `wait_id` when continuing the run. | | `artifacts` | object | array | Download, screenshot, and recording links for the run. It is an empty array when the recording and artifact entitlement is unavailable. | | `created_at` | datetime | Creation timestamp. | | `updated_at` | datetime | Last update timestamp. | *** ## Continue a waiting run ```http POST /flows/{id}/runs/{run}/continue ``` Continues a running flow paused by `$waitHumanValidation()`. ### Request body | Field | Type | Description | | --- | --- | --- | | `wait_id` | string (uuid), required | The pending validation ID, returned as `human_validation_wait_id` by the get run endpoint. | ```json { "wait_id": "0d4f6f0e-1d0a-4b9e-8a1e-6b8a1a2b3c4d" } ``` ### Response `200` ```json { "run_id": 42, "status": "running", "continue_requested": true } ``` ### Errors | Code | Description | | --- | --- | | `403` | API key lacks permission for the flow. | | `404` | Flow or run not found. | | `409` | Run is not active or is not waiting for this validation request. | | `422` | Missing or invalid `wait_id`. | *** ## Get run result ```http GET /flows/{id}/runs/{run}/result ``` Returns only the output, status and timing of a run - a lighter alternative to the full run endpoint. ### Response `200` ```json { "run_id": 42, "status": "success", "output": { "status": "success", "message": "Done", "count": 5 }, "error_message": null, "duration_ms": 12340 } ``` | Field | Type | Description | | --- | --- | --- | | `run_id` | integer | Run ID. | | `status` | string | Run status. | | `output` | object | null | Flow output data. | | `error_message` | string | null | Error message if the run failed. | | `duration_ms` | integer | null | Run duration in milliseconds. | --- --- url: https://docs.puppetflow.com/reference/api/artifacts.md --- # Artifacts Screenshots, downloaded files, and video recordings produced during a run. Artifact and recording endpoints require the recording entitlement and return `404` when it is unavailable. Captured response-body endpoints are not affected. ## List artifacts ```http GET /flows/{id}/runs/{run}/artifacts/{type} ``` Returns the list of artifact files for the given type. ### Path parameters | Param | Values | Description | | --- | --- | --- | | `{type}` | `screenshots`, `downloads` | Artifact category. | ### Response `200` ```json [ { "name": "screenshot_00.png", "size": 245760, "modified_at": "2026-03-15 10:30:10", "url": "https://your-instance.com/api/v1/flows/flow_k8Zt3xQ9mA2f/runs/42/artifacts/screenshots/screenshot_00.png" }, { "name": "screenshot_01.png", "size": 198400, "modified_at": "2026-03-15 10:30:12", "url": "https://your-instance.com/api/v1/flows/flow_k8Zt3xQ9mA2f/runs/42/artifacts/screenshots/screenshot_01.png" } ] ``` | Field | Type | Description | | --- | --- | --- | | `name` | string | File name. | | `size` | integer | File size in bytes. | | `modified_at` | string | Last modification time in `Y-m-d H:i:s` format. | | `url` | string | Authenticated API URL for the artifact. | ### Errors | Code | Description | | --- | --- | | `404` | Flow or run not found. | | `422` | Invalid artifact type (must be `screenshots` or `downloads`). | *** ## Download an artifact ```http GET /flows/{id}/runs/{run}/artifacts/{type}/{filename} ``` Downloads a specific artifact file as a binary stream. ### Path parameters | Param | Description | | --- | --- | | `{type}` | `screenshots` or `downloads`. | | `{filename}` | File name to download (as returned by the list endpoint). | ### Response `200` Binary file download with the appropriate content type (e.g. `image/png`, `application/pdf`, `application/octet-stream`). ### Errors | Code | Description | | --- | --- | | `404` | File, run, flow, or artifact type not found. | *** ## Download recording ```http GET /flows/{id}/runs/{run}/recording ``` Downloads the session recording as an MP4 video. ### Response `200` Binary file download with content type `video/mp4`. ### Errors | Code | Description | | --- | --- | | `404` | Flow, run, or recording not found. | ::: tip Recordings are only available when video recording is enabled in the flow settings. Check the [Video Recording](/guide/video-recording) guide for setup instructions. ::: *** ## Download the recording last frame ```http GET /flows/{id}/runs/{run}/recording/lastshot ``` Downloads the final available frame of the recording as a JPEG image. ### Response `200` Binary file download with content type `image/jpeg`. ### Errors | Code | Description | | --- | --- | | `404` | Flow, run, or recording frame not found. | *** ## Fetch a captured response body ```http GET /flows/{id}/runs/{run}/sniff-bodies/{captureId} ``` Returns the body of a network response captured by [`$sniffNetwork`](/reference/flow-api/page-evaluation#sniff-network) and kept for the run preview. `{captureId}` is the value found under `response.body.reference.captureId` in the run's nodal preview data. ### Response `200` The raw body as `text/plain; charset=utf-8`, with resolved secrets redacted. Parse it as JSON when the preview reference has `contentJsonAvailable: true`. ### Errors | Code | Description | | --- | --- | | `404` | Flow, run, or capture not found. Only captures still referenced by a retained preview snapshot are stored. | --- --- url: https://docs.puppetflow.com/reference/flow-api/globals.md --- # Flow Objects These objects are available in flow code. The `run` function receives them as arguments: ```js async function run($page, $input, $context, $client) { // ... } ``` `$context` and `$client` are optional parameters; `$client` is also available as a global. The Puppeteer `$browser` object is available globally. ## `$input` The input argument passed to the flow. It contains the flow inputs merged with webhook, manual, or API input data. ```js const url = $input.link; const username = $input.username; ``` ## `$context` Runtime metadata about the current run. In visual flows it is exposed as `$run.$context`. ```js const runId = $context.run_id; const flowId = $context.flow_id; ``` | Property | Description | | --- | --- | | `run_id` | Current run identifier. | | `flow_id` | Flow ID (used in URLs). | | `legend` | Run legend (set via `$legend()`). | | `meta` | Metadata object (set via `$meta()`). | ## `$page` A proxy to the Puppeteer [Page](https://pptr.dev/api/puppeteer.page) of the active named tab. It automatically follows tab changes made by `$gotoUrl()` and `$gotoTab()`. Use it for direct Puppeteer interaction not covered by the helpers. ```js await $page.waitForSelector('.loaded'); const title = await $page.title(); await $page.keyboard.press('Enter'); ``` ## `$client` The CDP session ([CDPSession](https://pptr.dev/api/puppeteer.cdpsession)) for the active named tab. It follows tab changes like `$page`. ```js const cookies = await $client.send('Network.getAllCookies'); ``` Puppetflow configures the browser download directory automatically. Do not override `Page.setDownloadBehavior`, because download helpers watch the configured run directory. ## `$browser` The Puppeteer [Browser](https://pptr.dev/api/puppeteer.browser) instance for browser-level operations. ## `$viewportWidth` and `$viewportHeight` The effective browser viewport dimensions in pixels. ```js if ($viewportWidth < 768) { await $clickElement('[aria-label="Open menu"]'); } ``` ## `$now` A Luxon `DateTime` representing the current date and time. ```js const timestamp = $now.toISO(); const tomorrow = $now.plus({ days: 1 }); ``` ## `$today` A Luxon `DateTime` representing the start of the current day. ```js const startOfToday = $today.toISO(); ``` --- --- url: https://docs.puppetflow.com/reference/flow-api/navigation.md --- # Navigation Page navigation, viewport control, screenshots, cookie persistence and login helpers. ## `$gotoUrl(url, tabName?, options?)` {#goto-url} Create or reuse a named browser tab, activate it, navigate to a URL, optionally bypass Content Security Policy, and wait for the page to settle. The tab name defaults to `Default`. ```js await $gotoUrl('https://example.com'); await $gotoUrl('https://example.com', 'Reports', { waitUntil: 'domcontentloaded', headers: { 'X-Custom': 'value' }, bypassCSP: false, }); ``` | Option | Default | Description | | --- | --- | --- | | `waitUntil` | `'networkidle2'` | Wait condition: `networkidle2` (at most 2 connections for 500 ms), `networkidle0` (no network activity for 500 ms), `load`, `domcontentloaded`, `commit`. | | `headers` | `{}` | Extra HTTP headers sent with the request. | | `bypassCSP` | `true` | Bypass Content Security Policy. | | `timeout` | `30000` | Navigation timeout in milliseconds. Self-hosted instances can override the default with `FLOW_NAVIGATION_TIMEOUT_MS`. | | `settleDelay` | `2000` | Grace period after navigation in milliseconds. Set to `0` to continue immediately. | ::: warning Throws if `url` is falsy or not a string. URLs without a scheme are prefixed with `https://`. A timeout is ignored when the browser reached the target URL and the document is already interactive or complete. ::: Returns the Puppeteer navigation `HTTPResponse`, or `null`. ## `$gotoTab(tabName?)` {#goto-tab} Switch to an existing named browser tab. The name defaults to `Default`. It throws if the tab does not exist or has been closed. ```js await $gotoTab('Reports'); ``` ## `$setViewport(width?, height?)` {#set-viewport} Set the browser viewport dimensions. ```js await $setViewport(1920, 1080); ``` Omitted dimensions use the current `$viewportWidth` and `$viewportHeight` values. ## `$screenshot(name?, options?)` {#screenshot} Take a screenshot of the current page. ```js await $screenshot('after-login'); await $screenshot('debug-step', { output: false }); ``` | Option | Default | Description | | --- | --- | --- | | `output` | `true` | Include this screenshot in the run's artifacts. | Names auto-increment when omitted: `screenshot_00`, `screenshot_01`, etc. Sub-directories in the name are created automatically. ## Cookies ### `$saveCookies(jarName?, options?)` {#save-cookies} Save all cookies, including HttpOnly cookies, and localStorage by origin for reuse across runs of the same flow. ```js await $saveCookies('my-session'); await $saveCookies('cookies-only', { persistLocalStorage: false }); ``` Default jar name: `"Default"`. `persistLocalStorage` defaults to `true`. ### `$loadCookies(jarName?, options?)` {#load-cookies} Load a previously saved browser-storage jar, restore its cookies and optionally restore localStorage. Returns `true` on success and `false` if the jar cannot be loaded. ```js const loaded = await $loadCookies('my-session'); if (!loaded) { // jar not found - need to login again } ``` The default jar is `"Default"`. Set `persistLocalStorage: false` to restore cookies without continuing localStorage persistence. ### `$clearCookies(jarName?)` {#clear-cookies} Delete a stored browser-storage jar. The jar name defaults to `"Default"`. Clearing the default or active jar also clears live cookies, localStorage, and sessionStorage. The `Default` jar is restored automatically before `run()` starts, then captured after each navigation and at the end of the flow. Use `$saveCookies()` and `$loadCookies()` when working with named jars or when you need to force a save or restore. ## `$loginRemember(options)` {#login-remember} Login with cookie persistence. Navigates to `loggedUrl` using the browser storage already restored for the run. If the logged-in marker is not detected, it runs `loginRecipe`, waits for the marker, then saves cookies and localStorage. ```js await $loginRemember({ loginUrl: 'https://app.example.com/login', loggedUrl: 'https://app.example.com/dashboard', loggedMarkerCondition: { selectorOrHandle: '.dashboard-header', }, loggedMarkerTimeout: 5000, gotoOptions: { waitUntil: 'domcontentloaded' }, loginRecipe: async () => { await $fillInput('#email', 'foo@example.com'); await $fillInput('#password', 'my_password'); await $clickElement('#login-btn'); }, }); ``` | Option | Required | Default | Description | | --- | --- | --- | --- | | `loginUrl` | yes | - | URL of the login page. | | `loginRecipe` | yes | - | Async function that performs the login steps. | | `loggedMarkerCondition` | yes\* | - | Marker object with `selectorOrHandle` and optional text filters, `operator`, and `count`. | | `loggedMarkerConditionRaw` | yes\* | - | Async function run in the flow context that must return a boolean. | | `loggedUrl` | yes | - | URL to navigate to for checking login state. | | `loggedMarkerTimeout` | no | `5000` | Timeout (ms) for the marker check. | | `gotoOptions` | no | `{ waitUntil: 'domcontentloaded' }` | Options passed to `$gotoUrl()` for both login and logged-state navigation. | \*Provide either `loggedMarkerCondition` or `loggedMarkerConditionRaw`. --- --- url: https://docs.puppetflow.com/reference/flow-api/interaction.md --- # Interaction & Selectors Click, type, scroll, and query elements. Most functions accept either a CSS selector string or a Puppeteer `ElementHandle`. ## Typing ### `$keyboardSpeed(milliseconds)` {#keyboard-speed} Set the default delay between keystrokes for subsequent input actions. ```js $keyboardSpeed(35); await $fillInput('#search', 'Puppetflow'); ``` Returns the configured delay in milliseconds. ### `$fillInput(selector, value, options?)` {#fill-input} Replace, append, or prepend an input value with realistic timing. Handles detached-node retries automatically. ```js await $fillInput('#email', 'user@example.com'); await $fillInput('#search', 'query', { speed: 50, sleep: 200, tabCount: 0 }); // Works with an ElementHandle too const input = await $page.$('#name'); await $fillInput(input, 'Alice'); ``` | Option | Default | Description | | --- | --- | --- | | `tabCount` | `1` | Number of `Tab` presses after typing. | | `sleep` | `500` | Delay (ms) between clearing and typing, and after tab. | | `speed` | keyboard speed | Typing delay per character (ms). | | `mode` | `replace` | `replace`, `append`, or `prepend` the value. | | `timeout` | `30000` | Max time (ms) to wait for the selector. | | `continueOnError` | `false` | Return without throwing if the element is not found. | | `visibleOnly` | `false` | Only consider visible elements. | | `index` | `0` | Pick the nth matching element. | ### `$keyboardPress(text, options?)` {#keyboard-press} Type text one keystroke at a time into whatever currently has focus, or into an element focused first through `options.selector`. Unlike `$fillInput`, nothing is cleared beforehand. A newline in the text presses `Enter`. ```js await $clickElement('#comment'); await $keyboardPress('Hello there'); // Focus a field first, then type slowly await $keyboardPress('user@example.com', { selector: '#email', speed: 60 }); ``` | Option | Default | Description | | --- | --- | --- | | `selector` | `null` | CSS selector to focus before typing. Leave empty to type into the focused element. | | `speed` | keyboard speed | Typing delay per character (ms). `0` types instantly. | | `timeout` | `30000` | Max time (ms) to wait for the selector. | | `continueOnError` | `false` | Return without throwing if the selector is not found. | | `visibleOnly` | `false` | Only consider visible elements. | | `index` | `0` | Pick the nth matching element. | ### `$keyboardShortcut(key, options?)` {#keyboard-shortcut} Press one key while holding modifiers. `key` is a single character or a key name such as `Enter`, `Tab`, `Escape`, `ArrowDown` or `F5`. `cmdOrCtrl` holds `Cmd` on macOS and `Ctrl` elsewhere, so the same flow works on both. ```js await $keyboardShortcut('a', { cmdOrCtrl: true }); // select all await $keyboardShortcut('Enter', { shift: true }); // soft line break await $keyboardShortcut('Tab', { repeat: 3 }); // move focus three fields ahead await $keyboardShortcut('s', { control: true, shift: true }); ``` | Option | Default | Description | | --- | --- | --- | | `cmdOrCtrl` | `false` | Hold the platform shortcut key (`Cmd` on macOS, `Ctrl` elsewhere). | | `control` | `false` | Hold `Ctrl`. | | `meta` | `false` | Hold `Meta` (`Cmd` on macOS, Windows key elsewhere). | | `shift` | `false` | Hold `Shift`. | | `alt` | `false` | Hold `Alt` (`Option` on macOS). | | `repeat` | `1` | Number of times to press the shortcut. | ## Clicking ### `$clickElement(selectorOrHandle, options?)` {#click-element} Click an element after an optional delay. Accepts a CSS selector or `ElementHandle`. ```js await $clickElement('#submit'); await $clickElement('.next-btn', { delay: 2000 }); await $clickElement('.optional', { continueOnError: true }); await $clickElement('button', { textMatch: 'Confirm', textFilter: 'exact', visibleOnly: true }); await $clickElement('.context-menu-target', { buttonType: 'right' }); // Click 40px to the right of the element center (e.g. an icon drawn next to it) await $clickElement('.row-label', { offsetX: 40, offsetY: 0 }); ``` | Option | Default | Description | | --- | --- | --- | | `delay` | `1000` | Delay (ms) before and after clicking. | | `buttonType` | `left` | Mouse button: `left`, `middle`, or `right`. | | `offsetX` | `0` | Horizontal shift (px) from the element center. When `offsetX` or `offsetY` is non-zero, the click is sent to that shifted point instead of the element itself. Negative values move left. | | `offsetY` | `0` | Vertical shift (px) from the element center. Negative values move up. | | `continueOnError` | `false` | Return `null` instead of throwing if the element is not found. | | `timeout` | `30000` | Max time (ms) to wait for the selector. | | `textMatch` | `null` | Text to match against each candidate's visible text. | | `textFilter` | `contains` | Match mode: `contains`, `exact`, `startsWith`, or `endsWith`. | | `textCaseSensitive` | `false` | Preserve letter casing when matching text. | | `visibleOnly` | `false` | Only consider visible elements. | ### `$clickElementAtIndex(selector, index, options?)` {#click-element-at-index} Click the nth element matching a selector. Indexes are zero-based; negative values count from the end (`-1` is the last match). Same options as `$clickElement`, except `offsetX` and `offsetY`. ```js await $clickElementAtIndex('.list-item button', 2); await $clickElementAtIndex('.tab', 0, { textMatch: 'Overview', textFilter: 'exact' }); ``` ### `$clickAtCoordinates(x, y, options?)` {#click-at-coordinates} Click viewport coordinates directly. This bypasses selector resolution. ```js await $clickAtCoordinates(320, 240); await $clickAtCoordinates(320, 240, { buttonType: 'right', delay: 250 }); ``` | Option | Default | Description | | --- | --- | --- | | `delay` | `1000` | Delay (ms) before and after clicking. | | `buttonType` | `left` | Mouse button: `left`, `middle`, or `right`. | ## Scrolling ### `$scrollByPixels(amount)` {#scroll-by-pixels} Scroll the page vertically by an exact pixel amount. Positive values scroll down and negative values scroll up. ```js await $scrollByPixels(500); await $scrollByPixels(-300); ``` ### `$scrollToElement(selectorOrHandle)` {#scroll-to-element} Scroll the page or its nearest scrollable container until an element is visible. ```js await $scrollToElement('#checkout'); const element = await $selectOneElement('.active-row'); await $scrollToElement(element); ``` ## Selectors ### Writing a selector Every selector field accepts standard CSS selector syntax. Prefer stable attributes that describe the element when they are available: ```css #submit .primary-button button[type="submit"] [data-testid="employees-tab"] nav [aria-label="Employees"] ``` Combine selectors to narrow the result. A space selects a descendant, while writing selectors without a space applies every condition to the same element: ```css [class*="Tabs_tab__"] span button[class*="Button_root__"][type="submit"] ``` Attribute selectors are useful when a site adds a generated value to a class or another attribute: ```css [class^="Tabs_"] /* starts with */ [class$="_active"] /* ends with */ [class*="Tabs_tab__"] /* contains */ ``` For example, `[class*="Tabs_tab__"] span` finds `span` elements below an element whose `class` attribute contains `Tabs_tab__`. Attribute values and class names are case-sensitive, so `Tabs_tab__` and `tabs_tab__` are different. Use the selector to identify candidate elements, then use `textMatch` when the desired element is distinguished by its visible text: ```js await $clickElement('[class*="Tabs_tab__"] span', { textMatch: 'Employees List', textFilter: 'contains', }); ``` In a nodal flow, enter the same CSS selector in the selector field and use the **Text** and **Text condition** fields for visible-text matching. ### `$selectOneElement(selectorOrHandle, options?)` {#select-one-element} Get an `ElementHandle` matching a selector with optional filtering. Returns `null` if not found (never throws). ```js const el = await $selectOneElement('.btn-primary'); const confirmBtn = await $selectOneElement('button', { textMatch: 'Confirm', textFilter: 'exact', visibleOnly: true }); const third = await $selectOneElement('.item', { index: 2 }); ``` | Option | Default | Description | | --- | --- | --- | | `textMatch` | `null` | Text to match against each candidate's visible text. | | `textFilter` | `contains` | Match mode: `contains`, `exact`, `startsWith`, or `endsWith`. | | `textCaseSensitive` | `false` | Preserve letter casing when matching text. | | `visibleOnly` | `false` | Only return visible elements. | | `index` | `0` | Pick the nth matching element. Negative values count from the end. | | `timeout` | `30000` | Max time (ms) to wait for the selector. | ### `$selectManyElements(selector, options?)` {#select-many-elements} Get all `ElementHandle`s matching a selector with optional filtering. Returns an empty array if none are found. ```js const rows = await $selectManyElements('table tr'); const visibleButtons = await $selectManyElements('button', { textMatch: 'Download', textFilter: 'startsWith', visibleOnly: true, }); ``` | Option | Default | Description | | --- | --- | --- | | `textMatch` | `null` | Text to match against each candidate's visible text. | | `textFilter` | `contains` | Match mode: `contains`, `exact`, `startsWith`, or `endsWith`. | | `textCaseSensitive` | `false` | Preserve letter casing when matching text. | | `visibleOnly` | `false` | Only return visible elements. | | `timeout` | `30000` | Max time (ms) to wait for the selector. | ### `$attributesFromOne(selectorOrHandle, getters, options?)` {#attributes-from-one} Extract named, JSON-compatible values from one element. Map each output key to a getter. Returns `null` if no element matches. Accepts the same `options` as `$selectOneElement` (`textMatch`, `textFilter`, `textCaseSensitive`, `visibleOnly`, `index`, `timeout`). ```js const product = await $attributesFromOne('.product', { title: 'textContent', sku: 'attribute:data-sku', link: 'href', }); const secondPrice = await $attributesFromOne('.price', { value: 'innerText' }, { index: 1, visibleOnly: true }); ``` Common getters include `textContent`, `innerText`, `value`, `href`, `src`, `className`, `id`, `tagName`, `outerHTML`, `innerHTML`, and `attribute:name`. ### `$attributesFromMany(selectorOrHandle, getters, options?)` {#attributes-from-many} Apply the same getters to every matching element. The helper returns an array of objects, or an empty array when nothing matches. The first argument can be a selector, one `ElementHandle`, or an array of handles. It accepts the same options as `$selectManyElements`: `textMatch`, `textFilter`, `textCaseSensitive`, `visibleOnly`, and `timeout`. ```js const products = await $attributesFromMany('.product', { title: 'innerText', sku: 'attribute:data-sku', }); const visibleLinks = await $attributesFromMany('a', { href: 'href' }, { visibleOnly: true }); ``` ### `$waitForSelectorCondition(selector, condition, options?)` {#wait-for-selector-condition} Wait for at least one element matching `selector` to satisfy a `condition` function (evaluated in the page context). ```js await $waitForSelectorCondition( '.status', (el) => el.textContent.includes('Complete'), { timeout: 15000 } ); ``` | Option | Default | Description | | --- | --- | --- | | `timeout` | `10000` | Max time (ms) to wait. | Selector-based helpers support deep selectors: use `>>>` to cross an open shadow root and `>>iframe>>` to cross an iframe boundary. Deep selectors use a 5-second default timeout when no timeout is supplied. ## Shadow DOM ### `$selectShadow(selector, rootSelector?, options?)` {#select-shadow} Find an element inside open shadow DOM roots. Recursively traverses shadow roots to find the first match. ```js const el = await $selectShadow('input.inner'); const el2 = await $selectShadow('span.label', '#host-element'); ``` Returns an `ElementHandle` or `null`. Options include `timeout` (default `5000`), `continueOnError` (default `true`), text matching, `visibleOnly`, and `index`. ### `$shadowInputFill(selector, value, options?)` {#shadow-input-fill} Fill an input located inside shadow DOM. Combines `$selectShadow` + `$fillInput`. ```js await $shadowInputFill('#shadow-input', 'value', { rootSelector: '#shadow-host', speed: 50, }); ``` Accepts `mode`, `tabCount`, `sleep`, `speed`, `continueOnError`, `visibleOnly`, and `index`, plus: | Option | Default | Description | | --- | --- | --- | | `rootSelector` | `null` | CSS selector for the shadow host root to start searching from. | | `timeout` | `5000` | Max time (ms) to wait for the selector. | --- --- url: https://docs.puppetflow.com/reference/flow-api/page-evaluation.md --- # Page Evaluation Run JavaScript inside the browser page context. These functions serialize your code and execute it remotely, so only serializable values can be passed in and returned. ## `$injectScriptLibrary(url)` {#inject-script-library} Load an external JavaScript library into the current page. ```js await $injectScriptLibrary('https://cdn.example.com/library.min.js'); ``` | Param | Description | | --- | --- | | `url` | URL of the JavaScript library to inject. | ## `$bridgeEvaluate(evaluationCode, bridgeValues?, bridgeFunctions?)` {#bridge-evaluate} Evaluate a function in the page context while bridging flow input, serializable values, and functions. The second argument injects values and the third injects functions. Returned promises are awaited automatically. ```js const title = await $bridgeEvaluate(() => document.title); const label = await $bridgeEvaluate(($input, { prefix }, { formatLabel }) => { return formatLabel( document.title, prefix, $input.workspaceName, ); }, { prefix: 'Current page', }, { formatLabel: (title, prefix, workspaceName) => { return `${prefix}: ${title} (${workspaceName})`; }, }); ``` | Param | Description | | --- | --- | | `evaluationCode` | Function receiving `($input, bridgeValues, bridgeFunctions)`. This `$input` includes the runtime `$context` key. The two bridge objects can be destructured directly in its arguments. | | `bridgeValues` | Serializable values passed into the page context. | | `bridgeFunctions` | Named functions reconstructed inside the page context. | ### Example: inject and use jQuery Combine both helpers to load jQuery, then use it from the page context: ```js await $injectScriptLibrary('https://code.jquery.com/jquery-3.7.1.min.js'); const titles = await $bridgeEvaluate(() => { return window.jQuery('h2').map((_, element) => { return window.jQuery(element).text(); }).get(); }); ``` ## `$httpRequest(url, options?)` {#http-request} Send an HTTP or HTTPS request outside the page context. The helper supports query parameters, headers, Basic or Bearer authentication, JSON, form, multipart and raw bodies, redirects and retries. ```js const response = await $httpRequest('https://api.example.com/invoices', { method: 'GET', query: { status: 'pending' }, headers: { Accept: 'application/json' }, responseFormat: 'json', retries: 2, }); ``` By default, `responseFormat: 'auto'` parses JSON responses and returns text for text, XML, JavaScript, and form content types. Use `json` or `text` to force a format. Binary responses and file uploads are not supported. Set `fullResponse: true` to receive `statusCode`, `statusMessage`, `url`, `headers`, and `body`. ```js const response = await $httpRequest('https://api.example.com/items', { method: 'POST', bodyType: 'json', body: { name: 'Example' }, fullResponse: true, neverError: true, }); console.log(response.statusCode, response.body); ``` Main options: * Request: `method`, `query`, `headers`, `auth`, `bodyType`, `body`, and `contentType` * Response: `responseFormat`, `encoding`, `fullResponse`, and `neverError` * Timing: `timeout` (default `30000`), `maxRedirects` (default `5`), and `followRedirects` * Retries: `retries` (default `0`), `retryDelay` (default `500`), and `retryStatusCodes` * Limits: `maxRequestBytes` and `maxResponseBytes`, both 50 MB by default * Session and TLS: `useBrowserSession`, `sendCredentialsOnCrossOriginRedirect`, and `allowUnauthorizedCerts` ## Network capture ### `$sniffNetwork(profileName?, filters?, options?)` {#sniff-network} Start an asynchronous network capture on all current browser tabs and tabs opened later. The call returns immediately with `{ profile, timeout, limit, maxBodyBytes, startedAt }`. Each matching request and response pair is sent to `options.sniffing`. Starting an already active profile throws an error. ```js await $sniffNetwork( 'Invoices API', { host: 'api.example.com', path: '/v1/invoices*', method: ['GET', 'POST'], resourceType: ['XHR', 'Fetch'], }, { timeout: 0, sniffing: async capture => { console.log( capture.request.url, capture.response?.status.code, capture.response?.body.contentJson, ); }, }, ); await $gotoUrl('https://app.example.com/invoices'); await $clickElement('#refresh'); const summary = await $stopSniffing('Invoices API'); console.log(summary.captured); ``` Filters are combined with AND logic: | Filter | Description | | --- | --- | | `url` | Complete URL pattern. | | `host` | Hostname pattern, for example `*.example.com`. | | `scheme` | One pattern or an array, for example `https`. | | `path` | Path and query pattern, for example `/api/*`. | | `method` | One pattern or an array, for example `GET` or `P*`. | | `resourceType` | One pattern or an array, commonly `XHR` or `Fetch`. | String filters support `*` wildcards and are case-insensitive. Pass a `RegExp`, or wrap a string in `#` characters, to use a regular expression. The callback receives: | Property | Description | | --- | --- | | `profile` | Capture profile name. | | `index` | Zero-based capture index. | | `tabName` | Named browser tab, or `null`. | | `resourceType` | CDP resource type. | | `request` | Request URL, method, headers and request data. | | `response.status` | Response status code and text. | | `response.headers` | Response headers. | | `response.mimeType` | Response MIME type. | | `response.body.content` | Response body when available. | | `response.body.contentJson` | Parsed JSON body when valid JSON. | | `response.body.encoding` | Body encoding. | | `response.body.bytes` | Response body size. | | `response.body.truncated` | Whether the configured size limit was exceeded. | | `response.body.unavailable` | Whether CDP could not provide the body. | | `error` | Network error, or `null`. | | `durationMs` | Request duration in milliseconds. | * `options.timeout` defaults to 60 seconds. Set it to `0` to keep the profile active until `$stopSniffing()` or the end of the flow. * `options.limit` defaults to `0` (unlimited). A positive value stops the profile after that many matching responses complete. * `options.showUnfilteredInLogs` logs matching and rejected requests. The run log records why a profile stopped: `Sniff Network stopped (limit|timeout|manual|flow-ended): N request(s)`. Self-hosted instances can change the per-response body limit with `RUNNER_HTTP_SNIFFING_MAX_BODY_BYTES`. See the [configuration reference](/reference/configuration#outbound-http). Callbacks run sequentially in request-arrival order. A callback failure is reported when the capture is drained. ### `$stopSniffing(profileName?)` {#stop-sniffing} Stop a capture profile, complete pending records, wait for queued callbacks and return a summary. ```js const result = await $stopSniffing('Invoices API'); // { profile, reason, captured, startedAt, stoppedAt, draining } ``` `reason` is `manual`, `limit`, or `timeout`. Calling `$stopSniffing()` after a profile stopped by limit or timeout returns its summary. Only a profile name that was never started raises an error. Do not call `$stopSniffing()` from inside its own callback when the caller must wait for complete draining. Stop it from the main flow after the browser actions that produce the requests. --- --- url: https://docs.puppetflow.com/reference/flow-api/files.md --- # Files & Downloads Download, upload, unzip, browse directories and work with PDFs. All file paths are relative to the run's `downloads` directory unless stated otherwise. Use `$getDownloadsPathFile()` to get absolute paths. ## Creating files ### `$writeFile(fileName, content, options?)` {#write-file} Write text or structured content to the run's downloads directory and return the absolute path. ```js const path = await $writeFile('result.json', { status: 'complete' }, { format: 'json', output: true, overwrite: true, }); ``` | Option | Default | Description | | --- | --- | --- | | `format` | `text` | Output format: `text`, `json`, `yaml`, `csv`, `toml`, or `xml`. | | `output` | `true` | Include the file in run artifacts. | | `overwrite` | `true` | Replace an existing file. | | `structuredSpacing` | `2` | JSON indentation, clamped from 0 to 10. | ## Downloading ### `$download(url, filename?, options?)` {#download} Download a file via HTTP using the page's cookies and user-agent. Works regardless of whether the browser is local or remote. ```js await $download('https://app.example.com/report.csv', 'report.csv'); await $download(linkUrl, 'invoice.pdf', { timeout: 60000 }); ``` | Option | Default | Description | | --- | --- | --- | | `output` | `true` | Include in run artifacts. | | `timeout` | `100000` | Timeout (ms). | If `filename` is omitted, the name is inferred from the URL. ### `$downloadFromBrowser(url, filename?, options?)` {#download-from-browser} Download via the browser session (navigates to the URL and triggers a download click). Useful for files that require browser context or session cookies that can't be extracted. Returns the absolute path to the downloaded file. ```js const filePath = await $downloadFromBrowser( 'https://app.example.com/export', 'export.xlsx' ); ``` | Option | Default | Description | | --- | --- | --- | | `output` | `true` | Include in run artifacts. | | `timeout` | `100000` | Timeout (ms). | ### `$waitForFile(dest?, options?)` {#wait-for-file} Wait for a browser-initiated download to complete. ```js await $clickElement('#export-btn'); await $waitForFile('export.csv'); ``` | Option | Default | Description | | --- | --- | --- | | `output` | `true` | Include in run artifacts. | | `timeout` | `100000` | Timeout (ms). | | `overrideExtension` | `false` | Append the original file extension to `dest`. | | `noThrow` | `false` | Return `false` instead of throwing on timeout. | ## Uploading ### `$upload(selectorOrHandle, filename, options?)` {#upload} Upload a file from the downloads directory or Media Library to an `` element. Accepts a CSS selector or `ElementHandle`. ```js await $upload('#file-input', 'document.pdf'); // With an ElementHandle const input = await $page.$('input[type="file"]'); await $upload(input, 'photo.jpg'); ``` `filename` is resolved inside the run downloads directory; paths that escape it are rejected. A Media Library ID in `media_XXXXXXXXXXXX` format is also accepted and staged for upload. Options include `timeout` (default `30000`), `continueOnError`, `visibleOnly`, and `index`. The helper returns `true`, or `null` when the target is not found and `continueOnError` is enabled. ## Archives ### `$unzipFile(zipPath, extractPath, options?)` {#unzip-file} Extract a ZIP archive from the downloads directory into a subdirectory. An existing extraction directory is replaced. The archive is removed by default. Returns the list of extracted filenames. ```js const files = await $unzipFile('archive.zip', 'extracted'); // files = ['file1.csv', 'file2.csv'] ``` | Option | Default | Description | | --- | --- | --- | | `store` | `true` | Keep extracted files after the run ends. Set `false` to auto-delete. | | `keepArchive` | `false` | Keep the ZIP file after extraction. | ## Directory operations ### `$scanDirectory(subPath, nameLike?)` {#scan-directory} List files in a directory, optionally filtering by name substring. Excludes `.crdownload` temp files. ```js const allFiles = await $scanDirectory('/absolute/path/to/dir'); const csvFiles = await $scanDirectory('/absolute/path', '.csv'); ``` ### `$scanDownloadsDirectory(subPath, nameLike?)` {#scan-downloads-directory} Same as `$scanDirectory` but relative to the downloads directory. ```js const files = await $scanDownloadsDirectory('extracted', '.csv'); ``` ### `$moveDownloadedFile(source, destination)` {#move-downloaded-file} Move a file to another path inside the downloads directory. ```js $moveDownloadedFile('temp-name.csv', 'final-report.csv'); ``` ### `$getDownloadsPathFile(file)` {#get-downloads-path-file} Get the absolute path to a file in the downloads directory. ```js const absPath = $getDownloadsPathFile('report.csv'); ``` ## PDF ### `$pdfSearch(filepath, text)` {#pdf-search} Search for a text string in a PDF file. Matching is case-insensitive. The path is resolved inside the run downloads directory. ```js const result = await $pdfSearch('document.pdf', 'Invoice Total'); // { found: true, count: 2, pages: [1, 3], totalPages: 5 } ``` **Returns:** | Property | Type | Description | | --- | --- | --- | | `found` | `boolean` | Whether any match was found. | | `count` | `number` | Total number of occurrences. | | `pages` | `number[]` | Page numbers containing the match (1-indexed). | | `totalPages` | `number` | Total number of pages in the PDF. | The PDF must contain searchable text. Scanned image-only pages require OCR before they can be searched. ### `$pdfGetText(filepath)` {#pdf-get-text} Extract all text content from a PDF file. The path is resolved inside the run downloads directory. ```js const result = await $pdfGetText('document.pdf'); console.log(result.text); result.pages.forEach(p => { console.log(`Page ${p.page}: ${p.text.substring(0, 100)}...`); }); ``` **Returns:** | Property | Type | Description | | --- | --- | --- | | `text` | `string` | Full text content of the PDF. | | `pages` | `Array<{ page, text }>` | Per-page text (1-indexed, non-empty pages only). | | `totalPages` | `number` | Total number of pages. | --- --- url: https://docs.puppetflow.com/reference/flow-api/utilities.md --- # Utilities Timing, logging, metadata, variables, date helpers and pattern matching. ## Timing ### `$sleep(ms)` {#sleep} Pause the run for the given number of milliseconds. ```js await $sleep(2000); // wait 2 seconds ``` ### `$stopwatchStart(name?)` {#stopwatch-start} Start or resume a named stopwatch and return its current elapsed time in milliseconds. The default name is `default`. ```js $stopwatchStart('checkout'); await $sleep(500); ``` ### `$stopwatchCheck(name?)` {#stopwatch-check} Read a stopwatch without stopping it. ```js const elapsed = $stopwatchCheck('checkout'); ``` Throws when the named stopwatch has not been started. ### `$stopwatchStop(name?, options?)` {#stopwatch-stop} Stop a stopwatch and return its elapsed time. The elapsed time is retained, so calling `$stopwatchStart()` again resumes it. ```js const elapsed = $stopwatchStop('checkout'); const finalElapsed = $stopwatchStop('checkout', { reset: true }); ``` Set `reset` to `true` to reset the stored elapsed time after reading it. ## Values and numbers ### `$if(condition, valueIfTrue, valueIfFalse)` {#if} Return one of two values. This helper is available in code flows and Code nodes. ```js const status = $if(total > 0, 'ready', 'empty'); ``` ### `$ifEmpty(value, fallback)` {#if-empty} Return the fallback when `value` is `undefined`, `null`, an empty string, an empty array, or an empty object. ```js const label = $ifEmpty($input.label, 'Untitled'); ``` ### `$max(...numbers)` {#max} Return the highest supplied number. ```js const highest = $max(12, 38, 7); // 38 ``` ### `$min(...numbers)` {#min} Return the lowest supplied number. ```js const lowest = $min(12, 38, 7); // 7 ``` ## Logging & metadata ### `$log(...messages)` {#log} Log messages to the run's console output and append them to the output trace. ```js $log('Processing invoice', invoiceId); $log('Found', items.length, 'items'); ``` ### `$legend(value)` {#legend} Set a short caption for the run. Displayed in the runs list and anywhere the run appears in the UI. ```js $legend('3 invoices processed'); $legend(`${company} - ${period}`); ``` ### `$meta(key, value)` {#meta} Attach filterable metadata to the run. Accepts a key/value pair or an object for bulk updates. Supports markdown in values. ```js $meta('invoiceCount', 42); $meta('status', 'processed'); // Bulk update $meta({ status: 'processed', region: 'EU', total: '€1,234' }); ``` ## Variables ### `$vars(variableId)` {#vars} Resolve a variable at runtime. Variables are configured in the flow's settings. ```js const email = $vars('variable-id-for-email'); const password = $vars('variable-id-for-password'); const city = $vars('variable-id-for-json.address.city'); ``` Use dotted paths to read nested keys from JSON variables. For **OTP/TOTP** variables, a fresh code is computed on every call: ```js const otpCode = $vars('variable-id-for-otp'); // fresh 6-digit TOTP code await $fillInput('#otp', otpCode); ``` Throws if the variable ID is not found, with a message listing available variables. ### `$totp(variableId)` {#totp} Compute a fresh TOTP code from a TOTP variable ID. A literal 4-to-10-digit code is returned unchanged, which allows manual or API input to override a variable reference. ```js const otpCode = $totp($input.otpVariableId); ``` ## Pattern matching ### `$matchSequence(items, patterns)` {#match-sequence} Find the first consecutive sequence in an array where each element matches the corresponding regex pattern. * With **1 pattern**: returns the matching string. * With **N patterns**: returns an array of N consecutive matches. * Returns `null` if no match is found. ```js const lines = ['Total', '€1,234.00', 'Tax', '€234.00']; const total = $matchSequence(lines, [/^Total$/, /€[\d.,]+/]); // ['Total', '€1,234.00'] const taxLine = $matchSequence(lines, [/€234/]); // '€234.00' ``` Patterns can be `RegExp` objects or strings. Always pass them as an array, even when using a single pattern. ## Date helpers ### `$parseDates(format, ...dateStrings)` {#parse-dates} Parse date strings according to a format pattern. Returns an array of `Date` objects. Supported tokens: `dd`, `mm`, `yyyy`, `yy`. ```js const [start, end] = $parseDates('dd/mm/yyyy', '15/03/2026', '31/12/2026'); const [d] = $parseDates('mm-dd-yy', '03-15-26'); ``` Throws on invalid dates or format mismatches. ### `$sortDates(format, dates, order?)` {#sort-dates} Sort an array of date strings by chronological order using the same format tokens as `$parseDates()`. `order` defaults to `'asc'`; pass `'desc'` for newest first. ```js const dates = ['31/12/2026', '15/03/2026', '01/01/2026']; const asc = $sortDates('dd/mm/yyyy', dates); // ['01/01/2026', '15/03/2026', '31/12/2026'] const desc = $sortDates('dd/mm/yyyy', dates, 'desc'); // ['31/12/2026', '15/03/2026', '01/01/2026'] ``` ### `$currentDate(ts?)` {#current-date} Get date components from a timestamp. Defaults to `Date.now()`. ```js const d = $currentDate(); // { day: '18', month: '03', year: 2026 } const d2 = $currentDate(1711234567890); ``` **Returns:** `{ day: string, month: string, year: number }` - `day` and `month` are zero-padded. ### `$currentDateMinusOneMonth(ts?)` {#current-date-minus-one-month} Same as `$currentDate` but shifted one month back. ```js const prev = $currentDateMinusOneMonth(); // In March 2026 → { day: '18', month: '02', year: 2026 } ``` ### `$currentDatePlusOneMonth(ts?)` {#current-date-plus-one-month} Same as `$currentDate` but shifted one month forward. ```js const next = $currentDatePlusOneMonth(); // In March 2026 → { day: '18', month: '04', year: 2026 } ``` --- --- url: https://docs.puppetflow.com/reference/flow-api/response.md --- # Response & Output Build the flow's return value. Every flow node must return a response object - these helpers produce the expected format. ## `$setOutput(keyOrObject, value?)` {#set-output} Add data to the response output. Called before `$generateResponse*` to attach extra fields. ```js $setOutput('invoiceCount', 5); $setOutput('total', 1234.56); // Bulk merge $setOutput({ status: 'done', items: ['a', 'b', 'c'] }); ``` All keys set via `$setOutput` are merged into the final response alongside `status` and `message`. ## `$generateResponse(status, message, data?)` {#generate-response} Build a response object with a custom status string. This is the base function used by the success/error shorthands. ```js return $generateResponse('success', 'Processed 3 invoices', { invoiceIds: [1, 2, 3], }); ``` **Returns:** ```js { status: 'success', message: 'Processed 3 invoices', invoiceIds: [1, 2, 3], // ... any keys set via $setOutput() $context: { /* runtime context */ } } ``` When **"Include input in output"** is enabled in the flow settings, the original input is attached under a `$input` key. ## `$generateResponseSuccess(message, data?)` {#generate-response-success} Shorthand for `$generateResponse('success', ...)`. ```js return $generateResponseSuccess('Done', { count: 5 }); ``` ## `$generateResponseError(message, data?)` {#generate-response-error} Shorthand for `$generateResponse('error', ...)`. Logs the message to stderr. ```js return $generateResponseError('Login failed - invalid credentials'); ``` ## `$stopSuccess(message, data?)` {#stop-success} Immediately stop the current run and return a success response. This is useful inside nested helpers where returning from `run()` is not possible. ```js function finishEarly(count) { if (count === 0) { $stopSuccess('Nothing to process', { count }); } } ``` ## `$stopFail(message, data?)` {#stop-fail} Immediately stop the current run and return an error response. ```js function requireInvoice(invoice) { if (!invoice) { $stopFail('Invoice not found'); } } ``` --- --- url: https://docs.puppetflow.com/reference/flow-api/notifications.md --- # Notifications Send messages to notification channels and pause flows for human validation. ## `$notify(channelId, message, options?)` {#notify} Send a notification to a configured channel (Slack, Discord, or Telegram). `channelId` is the channel ID. ```js await $notify('channel-id', 'Deployment complete!'); await $notify('channel-id', 'New invoice downloaded', { link: { url: 'https://app.example.com/invoices/42', label: 'View invoice' }, showRunId: true, }); ``` | Option | Default | Description | | --- | --- | --- | | `link` | `null` | `{ url, label }` - rendered as a button (Telegram inline keyboard, Discord button, Slack action). | | `showFlowId` | `false` | Prefix the message with the flow ID. | | `showRunId` | `false` | Prefix the message with the run ID. | Throws if the channel ID is not found (lists available channels in the error message). ## `$waitHumanValidation(waitingMessage?, channelId?, options?)` {#wait-human-validation} Pause the run until a human clicks **"Continue run"** in the Puppetflow UI. Optionally sends a notification to a channel when pausing. ```js // Notify and wait await $waitHumanValidation('Please review before continuing.', 'channel-id'); // Silent wait (no notification) await $waitHumanValidation(); ``` When `channelId` is provided, the notification includes a link back to the run in the UI. The default options for the notification are: | Option | Default | | --- | --- | | `showFlowId` | `true` | | `showRunId` | `true` | | `link` | Auto-generated link to the run page. | These can be overridden via the `options` parameter. ::: tip If the flow or run is deleted while waiting, the function throws an error and aborts instead of waiting forever. ::: --- --- url: https://docs.puppetflow.com/reference/flow-api/email.md --- # Email Wait for incoming emails through mailbox watchers. ## `$waitForEmail(watcherId, options?)` {#wait-for-email} Wait for an email matching a named mailbox watcher's rules. `watcherId` is the watcher ID configured in the flow settings. ```js const email = await $waitForEmail('mbwa-watcher-id'); await $fillInput('#code', email.parsed); // Custom timeout const invoiceEmail = await $waitForEmail('mbwa-watcher-id', { timeout: 600000, }); ``` | Option | Default | Description | | --- | --- | --- | | `timeout` | Watcher setting or `300000` | Maximum wait time in milliseconds. | The returned email includes its metadata and a `parsed` value when the watcher extracts content with a regular expression. The helper throws an error when the timeout is reached. --- --- url: https://docs.puppetflow.com/reference/flow-api/debugging.md --- # Debugging Interactive breakpoints for step-by-step flow debugging. ## `$breakpoint(label?, context?)` Set an interactive breakpoint. When breakpoint mode is enabled, the run pauses and a REPL opens where you can run arbitrary JavaScript, inspect variables, take screenshots, and continue when ready. ```js await $breakpoint('after-login', { user: username, cookies: cookieCount }); ``` Breakpoint mode is enabled with `ENABLE_BREAKPOINT=true` or automatically by the `php artisan flow:run` command. Otherwise, `$breakpoint` calls are skipped. ### REPL commands | Command | Description | | --- | --- | | `continue` or `c` | Resume the run. | | `screenshot` or `s` | Take a debug screenshot (saved with timestamp). | | `url` or `u` | Print the current page URL. | | `help` | List available commands. | | Any JS expression | Evaluate in the flow context with access to all globals and helpers. | ### Context The `context` parameter lets you expose additional variables inside the REPL: ```js const rows = await $bridgeEvaluate(() => document.querySelectorAll('tr').length); await $breakpoint('check-table', { rows, expectedCount: 10 }); // In the REPL: `rows` and `expectedCount` are available ``` All standard globals (`$page`, `$browser`, `$input`, `$context`, `$client`) and helper functions (`$sleep`, `$fillInput`, `$gotoUrl`, `$gotoTab`, `$screenshot`, etc.) are available in the REPL. --- --- url: https://docs.puppetflow.com/reference/configuration.md --- # Configuration Puppetflow is configured with environment variables. This page covers settings intended for instance administrators. Flow-specific options remain in the application. The **Default** column shows the application fallback when a variable is absent. `.env.minimal.example` and the production Compose stack override some defaults for their deployment model. ## Application | Variable | Default | Description | | --- | --- | --- | | `APP_NAME` | `Puppetflow` | Application name shown in the interface and generated messages. | | `APP_ENV` | `production` | Environment name. | | `APP_DEBUG` | `false` | Shows detailed errors when enabled. Keep disabled in production. | | `APP_URL` | `http://localhost` | Public application URL used in generated links. | | `APP_KEY` | - | Encryption key generated with `php artisan key:generate`. | | `APP_DEFAULT_TIMEZONE` | `UTC` | Default timezone assigned to new users. | | `APP_AUTO_MIGRATE` | `false` | Runs database migrations when the application container starts. | | `APP_SERVER_WORKERS` | - | Number of workers used by the built-in PHP development server. It does not affect the production image. | | `APP_MEMORY_LIMIT` | `512M` | Runtime memory limit applied to the web server, queue workers, and application commands in the official images. | | `APP_QUEUES_COUNTER` | `1` | Number of indexed flow queues. It must match the available `queue-N` worker services. The production Compose files use `2`. | ### Safe mode | Variable | Default | Description | | --- | --- | --- | | `APP_SAFE_MODE` | `false` | Bypasses normal authentication and signs in as an instance administrator. | ::: danger Never enable `APP_SAFE_MODE` on a publicly accessible or production instance. ::: ### Licensing | Variable | Default | Description | | --- | --- | --- | | `LICENSE_SERVER_URL` | `https://lic.puppetflow.com` | License server used to activate and refresh a license. | | `LICENSE_MANAGED` | - | Base64-encoded license file supplied by a managed deployment. Store this value as a secret. | ## Database, queue, cache, and sessions | Variable | Default | Description | | --- | --- | --- | | `DB_CONNECTION` | `pgsql` | Database driver. Supported values are `pgsql` and `sqlite`. | | `DB_HOST` | `127.0.0.1` | Database host. | | `DB_PORT` | `5432` | Database port. | | `DB_DATABASE` | `laravel` | Database name. | | `DB_USERNAME` | `root` | Database username. | | `DB_PASSWORD` | - | Database password. | | `DB_SSLMODE` | `prefer` | PostgreSQL SSL mode. | | `DB_FOREIGN_KEYS` | `true` | Enables SQLite foreign key enforcement. | | `DB_SQLITE_BUSY_TIMEOUT` | `5000` | SQLite lock wait timeout in milliseconds. | | `DB_SQLITE_JOURNAL_MODE` | `WAL` | SQLite journal mode. | | `DB_SQLITE_SYNCHRONOUS` | `NORMAL` | SQLite synchronization mode. | | `DB_SQLITE_TRANSACTION_MODE` | `IMMEDIATE` | SQLite transaction mode. Puppetflow requires `IMMEDIATE`. | | `QUEUE_CONNECTION` | `database` | Queue driver. Keep `database` unless using a durable external Redis service. | | `DB_QUEUE_RETRY_AFTER` | `900` | Seconds before an unacknowledged database-queue job is retried. | | `CACHE_STORE` | `database` | Cache store. Keep `database` unless using a durable external Redis service. | | `SESSION_DRIVER` | `database` | Session storage driver. Keep `database` unless using a durable external Redis service. | | `SESSION_LIFETIME` | `120` | Session lifetime in minutes. | | `SESSION_ENCRYPT` | `false` | Encrypt session data. | | `REDIS_CLIENT` | `phpredis` | Redis client. | | `REDIS_HOST` | `127.0.0.1` | Redis host. | | `REDIS_PORT` | `6379` | Redis port. | | `REDIS_PASSWORD` | - | Redis password. | The provided PostgreSQL container uses `puppetflow` for its database name and username. The application connection values must match the container configuration. See [Database](/self-hosting/database) for PostgreSQL and SQLite deployment requirements. The Redis container included in the production Compose stack is non-persistent and intended only for browser stream coordination. Do not point queues or sessions at it. PostgreSQL is the durable default; Redis application drivers require an external Redis service with persistence and backups. ## Social authentication | Variable | Default | Description | | --- | --- | --- | | `SOCIALITE_ENABLED` | `false` | Master switch for social sign-in. | | `SOCIALITE_GOOGLE_ENABLED` | `true` | Enables Google when social authentication is active. | | `SOCIALITE_GOOGLE_CLIENT_ID` | - | Google OAuth client ID. | | `SOCIALITE_GOOGLE_CLIENT_SECRET` | - | Google OAuth client secret. | | `SOCIALITE_GOOGLE_REDIRECT_URI` | - | Google callback URL, usually `${APP_URL}/auth/google/callback`. | | `SOCIALITE_GITHUB_ENABLED` | `true` | Enables GitHub when social authentication is active. | | `SOCIALITE_GITHUB_CLIENT_ID` | - | GitHub OAuth client ID. | | `SOCIALITE_GITHUB_CLIENT_SECRET` | - | GitHub OAuth client secret. | | `SOCIALITE_GITHUB_REDIRECT_URI` | - | GitHub callback URL, usually `${APP_URL}/auth/github/callback`. | ## Browser gateway | Variable | Default | Description | | --- | --- | --- | | `PINOKIO_ENABLED` | `true` | Enables the Pinokio browser gateway. | | `PINOKIO_HOST` | `localhost` | Pinokio host. Use `pinokio` with the provided Compose service. | | `PINOKIO_PORT` | `3000` | Pinokio port. | | `PINOKIO_TOKEN` | - | Token shared by Puppetflow and Pinokio. | | `PINOKIO_SECURE` | `false` | Uses `wss://` instead of `ws://`. | | `PINOKIO_BROWSER_ARCHIVE_URL` | - | `.tar.gz` containing a Chromium-based `chrome` executable that Pinokio downloads on first start and launches instead of the bundled Chromium. See [Bring Your Own Browser](/self-hosting/bring-your-own-chrome). | | `PINOKIO_CHROME_EXTRA_ARGS` | - | Extra whitespace-separated flags added to every browser launch. | | `BROWSER_DISABLE_WEB_SECURITY` | `false` | Disables browser web security globally. | | `BROWSER_USER_AGENT` | - | Instance-wide browser user agent. Workspace and flow settings override it. Empty uses the browser identity without its headless marker. | | `BROWSER_LANGUAGE` | - | Instance-wide default browser language. Workspace and flow settings can override it. | | `BROWSER_TIMEZONE` | - | IANA time zone applied to every browser session. Empty uses the host zone or derives one from the browser language. | | `BROWSER_IDENTITY_LOG` | `true` | Whether run logs name the browser build serving the run (name, version, executable hash, user agent). Set to `false` on shared instances so users cannot read the exact browser version from their run logs. | | `BROWSER_HIDE_CDP` | `true` | Reduces observable Chrome DevTools Protocol side effects. Set to `false` to preserve Puppeteer console and page-error events. | When `BROWSER_HIDE_CDP=true`, the Runtime domain is disabled between navigations and Puppeteer's `pptr:` source markers are removed. This improves resistance to automation detection, but flow code cannot rely on `page.on('console')` or `page.on('pageerror')`. ### Grabber and blueprints | Variable | Default | Description | | --- | --- | --- | | `GRABBER_CHROME_STORE_URL` | Chrome Web Store listing | Chrome installation link shown by the Grabber onboarding dialog. | | `GRABBER_FIREFOX_STORE_URL` | Firefox Add-ons listing | Firefox installation link shown by the Grabber onboarding dialog. | | `BLUEPRINTS_API_URL` | `https://puppetflow.com/api/blueprints` | API endpoint used to load public blueprints. | | `DOCUMENTATION_URL` | `https://docs.puppetflow.com` | Base URL used by contextual documentation links in the application. | ### Outbound HTTP | Variable | Default | Description | | --- | --- | --- | | `INTEGRATION_HTTP_ALLOW_HTTP` | `true` | Allows integrations to call endpoints over unencrypted HTTP. | | `INTEGRATION_HTTP_ALLOW_PRIVATE` | `true` | Allows integrations to call private and loopback addresses. | | `RUNNER_HTTP_REQUEST_ALLOW_PRIVATE` | `false` | Allows flow code running in the sandbox to call private and loopback addresses. | | `RUNNER_HTTP_SNIFFING_MAX_BODY_BYTES` | `5242880` | Maximum response body size retained by each network capture. | ### Nodal run previews | Variable | Default | Description | | --- | --- | --- | | `RUNNER_NODAL_PREVIEW_MAX_HISTORY_BYTES` | `1048576` | Maximum combined size of retained node snapshots and execution histories for one run. The most recent execution snapshots are removed first. | | `RUNNER_NODAL_PREVIEW_MAX_EXECUTIONS_PER_NODE` | `3` | Maximum number of execution snapshots retained for each node. The first executions are kept; later ones are only counted. Each snapshot gets a share of the history budget, so raising this value also shrinks each retained iteration. | | `RUNNER_NODAL_PREVIEW_MAX_STRING_CHARS` | `100` | Maximum length of a string value inside a snapshot. Longer strings are truncated with a `... (truncated)` suffix. | | `RUNNER_INTERNAL_OUTPUT_MAX_BYTES` | `4194304` | Maximum size of the preview file the server accepts from a run. Above this size the preview is dropped and the nodal editor shows a notice instead of runtime values. | Network capture bodies are never part of these snapshots: they are stored separately in the `flow_run_sniff_bodies` table, only for captures still referenced by a retained snapshot, and loaded on demand by the editor. They count toward the run storage size. These limits affect only the run preview shown in the nodal editor. They do not change flow execution values or the final output. Restart queue workers after changing them. ### Managed proxies | Variable | Default | Description | | --- | --- | --- | | `MANAGED_PROXIES` | - | JSON array of proxy servers provisioned as read-only resources in every workspace. Empty is equivalent to `[]`. | Each entry accepts `label`, `scheme`, `host`, and `port`. It can also include `key`, `country_code`, `group`, `username`, and `password`. ```dotenv MANAGED_PROXIES='[{"key":"shared-fr","label":"Shared France","scheme":"http","host":"proxy.example.com","port":8080,"country_code":"FR","group":"Managed","username":"user","password":"secret"}]' ``` `scheme` must be `http`, `https`, `socks4`, or `socks5`. `key` is an optional stable identifier used to synchronize the entry across configuration changes. It defaults to `label`. Define an explicit key if the label may be renamed, so flows keep the same proxy assignment. Managed proxies appear in the normal proxy table and flow proxy selector. Workspace users can use them, but cannot edit or delete them. Credentials are encrypted in the database and are never sent to the browser. Removing an entry from `MANAGED_PROXIES` removes it from each workspace during the next synchronization. Flows specifically assigned to that proxy are reset to no proxy. ## Live view | Variable | Default | Description | | --- | --- | --- | | `BROWSER_STREAM_INTERNAL_URL` | `http://localhost:6080` | Stream URL used by Puppetflow services. | | `BROWSER_STREAM_INTERNAL_PORT` | `6080` | Stream server port. | | `BROWSER_STREAM_PUBLIC_URL` | `http://localhost:6080` | Stream URL reached by users' browsers. | | `BROWSER_STREAM_ALLOWED_ORIGINS` | `*` | Comma-separated application origins accepted by the stream server. Restrict this to the application origin in production. | | `BROWSER_STREAM_SECRET` | - | Shared secret used to sign and verify stream access tokens. Must contain at least 32 characters. | | `BROWSER_STREAM_BIND_ADDRESS` | `0.0.0.0` | Host address on which Compose publishes the stream server. | | `BROWSER_STREAM_PUBLIC_PORT` | `6080` | Host port on which Compose publishes the stream server. | | `FLOW_RUN_SCREENCAST_QUALITY` | `60` | Live-view image quality. | | `FLOW_RUN_SCREENCAST_NTH_FRAME` | `1` | Sends one frame out of every configured number. | ## Run storage | Variable | Default | Description | | --- | --- | --- | | `FLOW_EXECUTION_DIR` | `data/execution` | Temporary workspace used while a flow run is active. | | `APP_STORAGE_DISK` | `puppetflow-local` | Durable storage backend for completed run artifacts and application uploads. | | `APP_STORAGE_LOCAL_ROOT` | `data/storage` | Local storage path used by the `puppetflow-local` backend. | | `APP_STORAGE_S3_PREFIX` | - | Optional key prefix used by the `puppetflow-s3` backend. | | `APP_STORAGE_R2_PREFIX` | - | Optional key prefix used by the `puppetflow-r2` backend. | See [Storage](/self-hosting/storage) for backend credentials and migration steps. ## MCP and OAuth | Variable | Default | Description | | --- | --- | --- | | `PASSPORT_PRIVATE_KEY` | - | OAuth signing private key. | | `PASSPORT_PUBLIC_KEY` | - | OAuth signing public key. | | `PASSPORT_CONNECTION` | - | Optional database connection used by OAuth. | | `MCP_BROKER_ENDPOINT` | `https://mcp.puppetflow.com/mcp` | Universal MCP broker endpoint shown in workspace settings. | | `MCP_BROKER_CALLBACK_URL` | `https://mcp.puppetflow.com/oauth/tenant/callback` | Broker callback accepted during tenant delegation. | | `MCP_CLIENT_ALLOW_HTTP` | `false` | Allows outbound MCP client connections over unencrypted HTTP. | | `MCP_CLIENT_ALLOW_PRIVATE` | `false` | Allows outbound MCP client connections to private or loopback addresses. | MCP token access does not require OAuth keys. OAuth clients require valid Passport keys. ## Mail ### Incoming mail | Variable | Default | Description | | --- | --- | --- | | `MAILBOX_SMTP_PORT` | `2525` | Host port published for incoming mailbox email. | ### Outgoing mail | Variable | Default | Description | | --- | --- | --- | | `MAIL_MAILER` | `log` | Mail transport. Use `smtp` to send invitations. | | `MAIL_SCHEME` | - | SMTP scheme, such as `tls` or `smtps`. | | `MAIL_HOST` | `127.0.0.1` | SMTP host. | | `MAIL_PORT` | `2525` | SMTP port. | | `MAIL_USERNAME` | - | SMTP username. | | `MAIL_PASSWORD` | - | SMTP password. | | `MAIL_FROM_ADDRESS` | `noreply@puppetflow.com` | Sender address. | | `MAIL_FROM_NAME` | `Puppetflow` | Sender name. | ## Debugging | Variable | Default | Description | | --- | --- | --- | | `ENABLE_BREAKPOINT` | `false` | Enables interactive flow breakpoints. Development only. | --- --- url: https://docs.puppetflow.com/self-hosting/quick-start.md --- # Self-Hosted Quick Start Self-hosting runs Puppetflow on infrastructure you control. Choose it when data location, network isolation, infrastructure-level customization, or hardware-based capacity matters more than a managed setup. You are responsible for the server, database, browser workers, HTTPS, backups, monitoring, and updates. The bundled Redis service is ephemeral and only coordinates live browser streams. ## Get started Run the installer on the server: ```bash curl -fsSL https://puppetflow.com/install.sh | bash ``` The installer: 1. Checks Docker Engine and Docker Compose v2, and installs Docker on Linux when needed. 2. Creates a `puppetflow` directory in the current directory. 3. Downloads the production SQLite Compose file and minimal environment template. 4. Generates the application key, browser-stream secret, and Pinokio token. 5. Asks whether to start Puppetflow immediately. Open `http://localhost:8000` after the services start. An empty installation redirects to onboarding, where you can activate the license and create the first administrator. The automated installer targets a single-host SQLite deployment. Use the [Installation guide](/self-hosting/installation) for public URLs, PostgreSQL, manual installation, and the first-start procedure. ## When Cloud is a better fit If you do not need to operate the infrastructure yourself, [Puppetflow Cloud](/guide/quick-start) removes the deployment and maintenance work. --- --- url: https://docs.puppetflow.com/self-hosting/installation.md --- # Installation This page covers the complete self-hosted installation. Read the [Self-Hosted Quick Start](/self-hosting/quick-start) first for the deployment overview. ## Requirements * A Linux server with `curl` * A server with at least 2 GB RAM (4 GB recommended for Chromium sessions) The installer checks for Docker Engine and Docker Compose v2. If Docker is missing, it installs the supported Docker version automatically. A domain name, reverse proxy, and HTTPS are only needed when the instance must be publicly accessible. The automated installation uses SQLite and is intended for a single-host deployment. Use PostgreSQL when you need higher write concurrency, horizontal scaling, or managed database features. See [Database](/self-hosting/database) before choosing a backend. ## Quick install ```bash curl -fsSL https://puppetflow.com/install.sh | bash ``` The installer: * verifies Docker Engine and Docker Compose v2 * creates a `puppetflow` directory in the current directory * downloads the production SQLite Compose file * creates `.env` from the minimal template * generates `APP_KEY`, `BROWSER_STREAM_SECRET`, and `PINOKIO_TOKEN` * asks whether to run `docker compose up -d` If you choose not to start immediately: ```bash cd puppetflow docker compose up -d ``` The application is available on `http://localhost:8000`. For a public installation, edit `APP_URL`, `BROWSER_STREAM_PUBLIC_URL`, and `BROWSER_STREAM_ALLOWED_ORIGINS` in `puppetflow/.env` before starting, then configure HTTPS. ## Manual PostgreSQL installation Save the PostgreSQL production example from [Docker Compose](/self-hosting/docker-compose) as `docker-compose.yml`. Copy the [minimal `.env`](/self-hosting/environment#minimal-env) next to it, switch its database block to PostgreSQL, and configure the required secrets. ```bash docker compose pull docker compose up -d ``` ## First-time setup The automated SQLite stack runs a one-shot `migrate` service before the application starts. For a manual stack without a migration service, run: ```bash docker compose exec app php artisan migrate --force ``` Open the application in your browser. When no users exist, the login page redirects to registration and the first registered user becomes the instance administrator. ## Services overview The production stack includes: | Service | Description | Port | | --- | --- | --- | | **app** | Puppetflow application | Host port 8000 | | **queue-1**, **queue-2** | Flow workers for the indexes configured by `APP_QUEUES_COUNTER` | - | | **scheduler** | Cron scheduler for triggers | - | | **pinokio** | Chromium gateway | 3000 | | **stream-server** | Live browser stream service | 6080 | | **mailbox-smtp** | SMTP server for receiving emails | Host port 2525 | | **redis** | Ephemeral browser stream coordination | 6379 | | **postgres** | PostgreSQL database | 5432 | | **init-volumes** | One-shot volume initialization | - | | **migrate** | One-shot database migration | - | ## Updating ```bash docker compose pull docker compose up -d docker compose exec app php artisan migrate --force ``` ## Custom domain and HTTPS For production, place a reverse proxy such as Nginx, Caddy, or Traefik in front of the application and browser stream service. Configure: * `APP_URL` with the public application origin * `BROWSER_STREAM_PUBLIC_URL` with the public browser-stream origin * `BROWSER_STREAM_ALLOWED_ORIGINS` with the application origin ## Email receiving To receive emails on custom domains: 1. Set up a [mailbox integration](/guide/integrations#mailbox-integration). 2. Point your domain's MX record to the server's public IP. 3. Set `MAILBOX_SMTP_PORT=25` in `.env` and ensure host port 25 is publicly accessible. Received emails become available to mailbox watchers and flows. --- --- url: https://docs.puppetflow.com/self-hosting/grabber-browser-extension.md --- # Connect the Grabber Browser Extension Install Puppetflow Grabber from the [Chrome Web Store](https://chromewebstore.google.com/detail/puppetflow-grabber/behdpfaljjpaeekihhnjfhfhigfbkjdc) or [Firefox Add-ons](https://addons.mozilla.org/firefox/addon/puppetflow-grabber/), then reload the Puppetflow editor tab. ## If the editor cannot connect Check the following: * The extension is installed and enabled. * The Puppetflow tab was reloaded after installing or reloading the extension. * The editor is using HTTP or HTTPS. If the editor shows `Puppetflow Grabber is not connected`, reload both the extension and the editor tab. For instructions on picking elements and using selectors, read the [Grabber Browser Extension guide](/guide/grabber-browser-extension). --- --- url: https://docs.puppetflow.com/self-hosting/bring-your-own-chrome.md --- # Bring Your Own Browser Puppetflow runs flows in the Chromium bundled with the Pinokio image. A self-hosted instance can run any other Chromium-based browser instead, by giving Pinokio the URL of a browser archive in `.env`. ## Quick switch To run another browser, for example [CloakBrowser](https://github.com/CloakHQ/CloakBrowser): ```dotenv PINOKIO_BROWSER_ARCHIVE_URL=https://cloakbrowser.dev/chromium-v146.0.7680.177.3/cloakbrowser-linux-x64.tar.gz ``` To go back to the bundled Chromium, comment the line out. In both cases, apply with: ```bash docker compose up -d pinokio ``` The first switch to a new browser downloads it (a couple hundred MB, progress is shown in `docker compose logs -f pinokio`); flows started meanwhile wait and retry. Switching back is instant, and the downloaded browser stays on disk for the next time. Confirm which one is running with: ```bash docker compose logs pinokio | grep "browser binary" ``` Use the `linux-arm64` archive on ARM hosts (Apple Silicon with Docker Desktop, Graviton). The rest of this page covers the details: how the browser is chosen, the archive format, mounting a browser installed on the host, licenses, and vendor flags. ## Which browsers work Any Chromium-based build that speaks the Chrome DevTools Protocol works, including Google Chrome, Chrome for Testing, and patched builds such as CloakBrowser. Pinokio downloads the browser directly from the URL you provide. Puppetflow does not bundle or redistribute third-party browsers. You choose the build and accept its publisher's license. The rest of the stack does not change. The application, queue workers, and browser stream continue to communicate with Pinokio over WebSocket. ## How it works At startup, Pinokio picks the browser in this order: 1. `CHROME_PATH` when set explicitly on the `pinokio` service. 2. `/opt/browser/chrome` when that file exists (a directory [mounted from the host](#mounting-a-browser-directory)). 3. The archive named by `PINOKIO_BROWSER_ARCHIVE_URL`, installed under `/opt/browsers`. 4. The bundled `/usr/bin/chromium`. Whichever is chosen, the startup log reports it: ```bash docker compose logs pinokio | grep "browser binary" ``` The line reports: * the engine: `chromium`, `downloaded`, or `custom` * the executable path * the product name and version from `--version` * the executable SHA-256 Example: ```text engine=downloaded path=/opt/browsers/8b71ce53b4fd1313/chrome name="Chromium" version="146.0.7680.177" sha256="3cf5…d34f" ``` Patched builds usually report `Chromium` as their name. Use the engine and hash to distinguish them from the bundled browser. Each run also prints an abbreviated `Browser:` line in its console log. ## Downloading a browser archive ```dotenv PINOKIO_BROWSER_ARCHIVE_URL=https://example.com/releases/browser-linux-x64.tar.gz ``` The archive must be a `.tar.gz` or `.zip`. Pinokio detects the format from its content, not the URL. Its root, or single top-level directory, must contain: * a `chrome` executable * its shared libraries * `.pak` resources * locales Use an HTTPS URL from the browser publisher. After editing `.env`: ```bash docker compose up -d pinokio docker compose logs -f pinokio ``` On the first start, Pinokio downloads the archive into the `pinokio-downloads` volume, extracts it, and fixes permissions. The log reports: 1. `browser_archive_install_start` 2. download progress 3. `browser_archive_downloaded` with the archive SHA-256 4. `browser_archive_install_done` 5. the usual `browser binary` line Pinokio answers `/health` during installation, but `/ready` reports `browser_installing` and new sessions receive HTTP 503. Runs retry until the browser is ready. Subsequent starts reuse the installed binary. Changing the URL installs another archive alongside it. If a publisher replaces the file at the same URL, remove the volume to force a new download. A download failure is logged, Pinokio exits, and Docker restarts it. Check the URL and that the archive matches the CPU architecture of the host (see [Requirements](#requirements)). ### Example: Chrome for Testing Google publishes [Chrome for Testing](https://googlechromelabs.github.io/chrome-for-testing/) as versioned `.zip` archives without auto-update. Choose the `linux64` or `linux-arm64` archive containing `chrome`. Do not select `chromedriver` or `chrome-headless-shell`. ```dotenv # Intel/AMD hosts PINOKIO_BROWSER_ARCHIVE_URL=https://storage.googleapis.com/chrome-for-testing-public/153.0.8010.52/linux64/chrome-linux64.zip # ARM hosts (Apple Silicon with Docker Desktop, Graviton) # PINOKIO_BROWSER_ARCHIVE_URL=https://storage.googleapis.com/chrome-for-testing-public/153.0.8010.52/linux-arm64/chrome-linux-arm64.zip ``` The startup log then reports `name="Google Chrome for Testing"`. Each URL is immutable and tied to its version, so switching versions means changing the URL; the previous one stays installed in the volume. ### Example: CloakBrowser CloakBrowser publishes Linux builds of its patched Chromium per release. Pick the file for your architecture: ```dotenv # Intel/AMD hosts PINOKIO_BROWSER_ARCHIVE_URL=https://cloakbrowser.dev/chromium-v146.0.7680.177.3/cloakbrowser-linux-x64.tar.gz # ARM hosts (Apple Silicon with Docker Desktop, Graviton) # PINOKIO_BROWSER_ARCHIVE_URL=https://cloakbrowser.dev/chromium-v146.0.7680.177.3/cloakbrowser-linux-arm64.tar.gz PINOKIO_CHROME_EXTRA_ARGS=--fingerprint-platform=windows ``` Each release also ships a `SHA256SUMS` file next to the archives; the hash Pinokio logs after the download should match the entry for your file. On Linux, the CloakBrowser wrapper normally adds `--fingerprint-platform=windows` so the browser presents itself as a Windows desktop. `macos` is also accepted. See the [CloakBrowser README](https://github.com/CloakHQ/CloakBrowser#fingerprint-configuration) for options such as `--fingerprint=`. Pinokio does not add vendor flags. ::: warning Third-party licenses The browser keeps its own license, which you accept when downloading it. * CloakBrowser's wrappers are MIT. * Its compiled binary has a separate [Binary License](https://github.com/CloakHQ/CloakBrowser/blob/main/BINARY-LICENSE.md). * Google Chrome has its own [terms of service](https://www.google.com/chrome/terms/). Check that your use complies with the browser publisher's current terms. ::: ## Mounting a browser directory The archive URL method is preferred. Mount a directory only when the browser is not available as a downloadable Linux archive or must be installed with a license key. This method is still supported. Pinokio checks `CHROME_PATH`, then `/opt/browser/chrome`, before downloaded and bundled browsers. ### 1. Mount the directory Create `docker-compose.override.yml`: ```yaml # docker-compose.override.yml services: pinokio: volumes: - /absolute/path/to/browser-directory:/opt/browser:ro ``` Docker Compose loads this override automatically. Mount the complete browser directory, including libraries, `.pak` files, and locales. Chromium loads these resources relative to its executable. ### 2. Select the executable The default mounted executable is `/opt/browser/chrome`. If it has another name, set its complete container path: ```yaml services: pinokio: environment: CHROME_PATH: /opt/browser/my-browser ``` An explicit invalid `CHROME_PATH` prevents Pinokio from starting. Without `CHROME_PATH`, a mount that does not contain `/opt/browser/chrome` is ignored and Pinokio tries the next browser source. ### 3. Apply and verify ```bash docker compose up -d pinokio docker compose logs pinokio | grep "browser binary" ``` The log should contain `engine=custom path=/opt/browser/chrome`, or the explicit `CHROME_PATH`. ### Installing CloakBrowser for a mount The current Node.js and Python CLIs can download a browser into `~/.cloakbrowser`: ```bash npx cloakbrowser install # or pip install cloakbrowser python -m cloakbrowser install ``` The installer downloads a build for the machine on which it runs. A macOS binary cannot run inside the Linux Pinokio container. On an Apple Silicon Mac using Docker Desktop, download the Linux ARM64 build from a container: ```bash docker run --rm --platform linux/arm64 \ -v ~/.cloakbrowser:/root/.cloakbrowser \ node:22-slim \ npx -y cloakbrowser install ``` Mount the resulting `~/.cloakbrowser/chromium-` directory. Use an absolute host path in the Compose override. ## Requirements * The binary must be a Linux build for the same CPU architecture as the Pinokio image: x86_64 on Intel/AMD hosts, aarch64 on ARM hosts (Apple Silicon Macs running Docker Desktop, Graviton servers). A macOS binary will not run inside the container even on a Mac. * Pinokio runs as an unprivileged user (uid 10001). Downloaded archives are fixed up automatically; mounted directories must be world-readable and the executable world-executable: `chmod -R a+rX` on the directory. Use an absolute host path, Docker Compose does not expand `~`. * The Pinokio image already contains the shared libraries and base fonts a Chromium build needs, so no additional packages are required inside the container. ## Extra launch flags Use `PINOKIO_CHROME_EXTRA_ARGS` in `.env` to pass whitespace-separated flags to every browser launch. This is how vendor-specific options reach the binary. Window and screen size come from the flow viewport, so do not set them here. Without a GPU, Chromium normally renders WebGL with SwiftShader. The following flags use the Mesa `llvmpipe` renderer included in the Pinokio image instead. Creating the first WebGL context can take about two extra seconds: ```dotenv PINOKIO_CHROME_EXTRA_ARGS=--use-gl=angle --use-angle=gl-egl --ignore-gpu-blocklist --enable-unsafe-swiftshader ``` ## Reverting Comment out `PINOKIO_BROWSER_ARCHIVE_URL` in `.env`, or remove the override file for a mounted directory. Then restart Pinokio: ```bash docker compose up -d pinokio ``` The bundled Chromium is used again. Downloaded archives remain in the `pinokio-downloads` volume. To reclaim the space: ```bash docker volume rm _pinokio-downloads ``` --- --- url: https://docs.puppetflow.com/self-hosting/docker-compose.md --- # Docker Compose Puppetflow provides a self-contained production stack based on published images. ## Production The following configuration runs Puppetflow from published container images. * PostgreSQL stores application state. * An ephemeral Redis service coordinates live browser streams. * Pinokio provides Chromium. * The stream server provides live browser viewing. Start from the minimal `.env`, then switch its database block to PostgreSQL as described below. ```yaml services: # App (nginx + php-fpm via supervisor) app: image: ghcr.io/puppetflow/puppetflow:latest pull_policy: always restart: unless-stopped ports: - "8000:8000" volumes: - puppetflow-framework:/app/storage - puppetflow-uploads:/app/data/storage - puppetflow-execution:/app/data/execution env_file: - .env depends_on: pinokio: condition: service_started stream-server: condition: service_started postgres: condition: service_healthy healthcheck: test: ["CMD-SHELL", "curl -fsS http://localhost:8000/up"] interval: 30s timeout: 5s retries: 3 start_period: 15s # Queue index 1 workers queue-1: image: ghcr.io/puppetflow/puppetflow:latest pull_policy: always restart: unless-stopped command: ["php", "artisan", "queue:work", "--queue=1", "--tries=1", "--timeout=630", "--sleep=3", "--max-jobs=500", "--max-time=3600"] deploy: replicas: 2 volumes: - puppetflow-framework:/app/storage - puppetflow-uploads:/app/data/storage - puppetflow-execution:/app/data/execution env_file: - .env environment: BROWSER_STREAM_INTERNAL_URL: "http://stream-server:6080" RUNNER_API_INTERNAL_URL: "http://app:8000/api/internal/runner" depends_on: postgres: condition: service_healthy stream-server: condition: service_started # Queue index 2 worker queue-2: image: ghcr.io/puppetflow/puppetflow:latest pull_policy: always restart: unless-stopped command: ["php", "artisan", "queue:work", "--queue=2", "--tries=1", "--timeout=630", "--sleep=3", "--max-jobs=500", "--max-time=3600"] deploy: replicas: 1 volumes: - puppetflow-framework:/app/storage - puppetflow-uploads:/app/data/storage - puppetflow-execution:/app/data/execution env_file: - .env environment: BROWSER_STREAM_INTERNAL_URL: "http://stream-server:6080" RUNNER_API_INTERNAL_URL: "http://app:8000/api/internal/runner" depends_on: postgres: condition: service_healthy stream-server: condition: service_started # Scheduler scheduler: image: ghcr.io/puppetflow/puppetflow:latest pull_policy: always restart: unless-stopped command: ["php", "artisan", "schedule:work"] volumes: - puppetflow-framework:/app/storage - puppetflow-uploads:/app/data/storage - puppetflow-execution:/app/data/execution env_file: - .env depends_on: postgres: condition: service_healthy # Incoming mailbox SMTP server mailbox-smtp: image: ghcr.io/puppetflow/puppetflow:latest pull_policy: always restart: unless-stopped command: ["php", "artisan", "mailbox:serve", "--port=2525"] ports: - "${MAILBOX_SMTP_PORT:-2525}:2525" volumes: - puppetflow-framework:/app/storage - puppetflow-uploads:/app/data/storage - puppetflow-execution:/app/data/execution env_file: - .env depends_on: postgres: condition: service_healthy # Browser stream server stream-server: image: ghcr.io/puppetflow/puppetflow-stream-server:latest pull_policy: always restart: unless-stopped stop_grace_period: 30s ports: - "${BROWSER_STREAM_BIND_ADDRESS:-0.0.0.0}:${BROWSER_STREAM_PUBLIC_PORT:-6080}:6080" env_file: - .env depends_on: redis: condition: service_healthy # Create the execution subdirectory before mounting it init-volumes: image: busybox volumes: - puppetflow-uploads:/uploads - puppetflow-execution:/execution command: ["sh", "-c", "chown -R 33:33 /uploads /execution"] restart: "no" # Pinokio browser gateway pinokio: image: ghcr.io/puppetflow/pinokio:latest pull_policy: always restart: unless-stopped shm_size: "1gb" depends_on: init-volumes: condition: service_completed_successfully volumes: - puppetflow-execution:/app/data/execution - pinokio-downloads:/opt/browsers environment: TOKEN: "${PINOKIO_TOKEN:-}" BROWSER_ARCHIVE_URL: "${PINOKIO_BROWSER_ARCHIVE_URL:-}" CHROME_EXTRA_ARGS: "${PINOKIO_CHROME_EXTRA_ARGS:-}" # PostgreSQL postgres: image: postgres:17-alpine restart: unless-stopped volumes: - puppetflow-db:/var/lib/postgresql/data environment: POSTGRES_DB: "${DB_DATABASE:-puppetflow}" POSTGRES_USER: "${DB_USERNAME:-puppetflow}" POSTGRES_PASSWORD: "${DB_PASSWORD:?DB_PASSWORD must be configured}" healthcheck: test: ["CMD-SHELL", "pg_isready -U \"$${POSTGRES_USER}\" -d \"$${POSTGRES_DB}\""] interval: 5s timeout: 5s retries: 5 # Redis redis: image: redis:8-alpine restart: unless-stopped command: - /bin/sh - -ec - | if [ -n "$${REDIS_PASSWORD:-}" ] && [ "$${REDIS_PASSWORD}" != "null" ]; then exec redis-server --save "" --appendonly no --requirepass "$${REDIS_PASSWORD}" fi exec redis-server --save "" --appendonly no environment: REDIS_PASSWORD: "${REDIS_PASSWORD:-}" healthcheck: test: ["CMD-SHELL", "if [ -n \"$$REDIS_PASSWORD\" ] && [ \"$$REDIS_PASSWORD\" != \"null\" ]; then redis-cli --no-auth-warning -a \"$$REDIS_PASSWORD\" ping; else redis-cli ping; fi"] interval: 5s timeout: 3s retries: 5 volumes: puppetflow-framework: puppetflow-uploads: puppetflow-execution: puppetflow-db: pinokio-downloads: ``` The bundled Redis service has no persistence or volume. Use it only for transient browser stream coordination. Queues, cache, locks, and sessions remain in PostgreSQL by default. If you move them to Redis, use an external deployment with persistence and backups. ### Prerequisites * Docker Engine and Docker Compose v2. * A [minimal `.env`](/self-hosting/environment#minimal-env) next to the Compose file, switched to the documented PostgreSQL block, with `APP_KEY`, `DB_PASSWORD`, and `BROWSER_STREAM_SECRET` configured. Its `APP_QUEUES_COUNTER=2` setting matches the two queue indexes in this stack. Nothing else is required for a local installation. PostgreSQL, the ephemeral browser-stream Redis broker, Pinokio, storage, and networking are created by Docker Compose. For a public deployment, configure HTTPS, set `APP_URL` to the public application origin, set `BROWSER_STREAM_PUBLIC_URL` to the public stream origin, and set `BROWSER_STREAM_ALLOWED_ORIGINS` to the application origin. ### Starting and updating ```bash docker compose pull docker compose up -d ``` ### Volumes * `puppetflow-framework` - Framework state, logs, cache, and generated application files. * `puppetflow-uploads` - Durable application uploads and completed run artifacts when using local storage. * `puppetflow-execution` - Temporary run workspace shared with the browser service. * `puppetflow-db` - PostgreSQL data. * `pinokio-downloads` - Browser archives downloaded by Pinokio when `PINOKIO_BROWSER_ARCHIVE_URL` is set. Stays empty otherwise. Remove it to force a fresh download. ### Networking Published ports: * `8000`: application * `6080`: browser stream * `2525`: incoming SMTP Put a reverse proxy in front of ports `8000` and `6080` for HTTPS. Override the stream address and port with `BROWSER_STREAM_BIND_ADDRESS` and `BROWSER_STREAM_PUBLIC_PORT`. ## Scaling Each queue index from `1` through `APP_QUEUES_COUNTER` must have a matching worker service. To add replicas to an existing index: ```bash docker compose up -d --scale queue-1=3 ``` To add another index, increase `APP_QUEUES_COUNTER`, add a `queue-N` service running `--queue=N`, and restart the application. Each worker processes one flow at a time. Scale based on your concurrency needs and available RAM (each Chromium session uses ~200-500 MB). --- --- url: https://docs.puppetflow.com/self-hosting/environment.md --- # Environment Variables Start with the minimal configuration below. Puppetflow already provides defaults for settings that do not need to be changed during installation. See the [Configuration Reference](/reference/configuration) only when you need to customize the instance. ## Minimal `.env` Copy `.env.minimal.example` to `.env`, or create a `.env` file with the following content: ```dotenv APP_ENV=production APP_URL=http://localhost:8000 APP_QUEUES_COUNTER=2 APP_KEY= # Generate with: echo "base64:$(openssl rand -base64 32)" DB_CONNECTION=sqlite DB_DATABASE=/app/storage/database.sqlite # Redis is used only by the browser stream relay. REDIS_HOST=redis REDIS_PORT=6379 PINOKIO_HOST=pinokio PINOKIO_PORT=3000 PINOKIO_TOKEN= RUNNER_API_INTERNAL_URL=http://localhost:8000/api/internal/runner BROWSER_STREAM_INTERNAL_URL=http://localhost:6080 BROWSER_STREAM_PUBLIC_URL=http://localhost:6080 BROWSER_STREAM_ALLOWED_ORIGINS=* # Generate with: openssl rand -hex 32 BROWSER_STREAM_SECRET= ``` The [automated installer](/self-hosting/installation#quick-install) generates `APP_KEY`, `BROWSER_STREAM_SECRET`, and `PINOKIO_TOKEN`. For a manual installation: 1. Generate `APP_KEY` and `BROWSER_STREAM_SECRET` with the commands shown in the comments. 2. For a public deployment, set `APP_URL` to the application origin, `BROWSER_STREAM_PUBLIC_URL` to the browser-stream origin, and restrict `BROWSER_STREAM_ALLOWED_ORIGINS` to the application origin. This configuration uses SQLite on one host and stores the database in the shared framework volume. * `APP_QUEUES_COUNTER=2` matches the two indexed worker services. * `PINOKIO_TOKEN` may remain empty when Pinokio does not require authentication. Before using the PostgreSQL Compose file, switch the database block to: ```dotenv DB_CONNECTION=pgsql DB_HOST=postgres DB_PORT=5432 DB_DATABASE=puppetflow DB_USERNAME=puppetflow # Use a strong, unique password. DB_PASSWORD= ``` For database selection, external PostgreSQL, and SQLite requirements, see [Database](/self-hosting/database). ## Startup and first account ```dotenv APP_AUTO_MIGRATE=false APP_SAFE_MODE=false ``` The first account is not configured through environment variables. When the instance has no users, the login page redirects to the registration form and the first registered user becomes the instance administrator. ::: danger `APP_SAFE_MODE=true` bypasses normal authentication and 2FA. Never enable it on a public or production instance. ::: ## Queue, cache, and sessions ```dotenv QUEUE_CONNECTION=database DB_QUEUE_RETRY_AFTER=900 CACHE_STORE=database SESSION_DRIVER=database SESSION_LIFETIME=120 SESSION_ENCRYPT=false ``` The production Compose stack stores queued jobs, cache entries, distributed locks, and sessions in PostgreSQL. This is the recommended configuration because PostgreSQL uses the persistent `puppetflow-db` volume. The bundled Redis container is intentionally ephemeral and is reserved for live browser stream coordination. Do not use it for queues or sessions because recreating the container can discard queued jobs and log users out. To use Redis for application state, connect Puppetflow to a separate durable Redis service with persistence, backups, and high availability configured: ```dotenv QUEUE_CONNECTION=redis CACHE_STORE=redis SESSION_DRIVER=redis REDIS_CLIENT=phpredis REDIS_HOST=durable-redis.example.internal REDIS_PORT=6379 REDIS_PASSWORD= ``` Because the same Redis connection variables are passed to the browser stream relay, it will use the external service as well. The bundled `redis` container can then be removed from a customized Compose deployment. ## Social sign-in ```dotenv SOCIALITE_ENABLED=false SOCIALITE_GOOGLE_ENABLED=true SOCIALITE_GOOGLE_CLIENT_ID= SOCIALITE_GOOGLE_CLIENT_SECRET= SOCIALITE_GOOGLE_REDIRECT_URI="${APP_URL}/auth/google/callback" SOCIALITE_GITHUB_ENABLED=true SOCIALITE_GITHUB_CLIENT_ID= SOCIALITE_GITHUB_CLIENT_SECRET= SOCIALITE_GITHUB_REDIRECT_URI="${APP_URL}/auth/github/callback" ``` `SOCIALITE_ENABLED` is the master switch. Each provider also requires its own credentials. ## Browser engine ```dotenv PINOKIO_BROWSER_ARCHIVE_URL= PINOKIO_CHROME_EXTRA_ARGS= ``` Both values are empty by default, so Pinokio uses its bundled Chromium. * `PINOKIO_BROWSER_ARCHIVE_URL` points to a `.tar.gz` or `.zip` containing a Chromium-based `chrome` executable. * `PINOKIO_CHROME_EXTRA_ARGS` adds whitespace-separated flags to every browser launch. See [Bring Your Own Browser](/self-hosting/bring-your-own-chrome) for setup and license considerations. ## Live view ```dotenv BROWSER_STREAM_INTERNAL_URL=http://stream-server:6080 BROWSER_STREAM_INTERNAL_PORT=6080 BROWSER_STREAM_PUBLIC_URL=https://stream.your-domain.com BROWSER_STREAM_ALLOWED_ORIGINS=https://your-domain.com BROWSER_STREAM_SECRET= FLOW_RUN_SCREENCAST_QUALITY=60 FLOW_RUN_SCREENCAST_NTH_FRAME=1 ``` The internal URL is set automatically on queue services by the production Compose file. The public URL must be reachable from the user's browser. `BROWSER_STREAM_ALLOWED_ORIGINS` is a comma-separated list when more than one application origin is allowed. ## Storage ```dotenv FLOW_EXECUTION_DIR=data/execution APP_STORAGE_DISK=puppetflow-local APP_STORAGE_LOCAL_ROOT=data/storage ``` `FLOW_EXECUTION_DIR` is the local workspace used while runs are active. `APP_STORAGE_DISK` selects the durable backend for completed artifacts and application uploads. The local backend works without additional services. To use private object storage instead, follow the [Storage overview](/self-hosting/storage), [Amazon S3 setup](/self-hosting/storage/aws-s3), or [Cloudflare R2 setup](/self-hosting/storage/cloudflare-r2). ## MCP and OAuth ```dotenv PASSPORT_PRIVATE_KEY= PASSPORT_PUBLIC_KEY= PASSPORT_CONNECTION= ``` MCP access tokens work without Passport keys. OAuth clients require valid Passport keys. MCP and repository webhook URLs use `APP_URL`. ## Mail ### Incoming mailbox email ```dotenv MAILBOX_SMTP_PORT=2525 ``` This controls the host port published for incoming email. ### Outgoing email ```dotenv MAIL_MAILER=smtp MAIL_SCHEME=tls MAIL_HOST=smtp.example.com MAIL_PORT=587 MAIL_USERNAME=puppetflow@example.com MAIL_PASSWORD=secret MAIL_FROM_ADDRESS=puppetflow@example.com MAIL_FROM_NAME=Puppetflow ``` Outgoing email is used for workspace invitations and other account messages. ## Debugging ```dotenv ENABLE_BREAKPOINT=false ``` `ENABLE_BREAKPOINT` is intended for development only. --- --- url: https://docs.puppetflow.com/self-hosting/database.md --- # Database Puppetflow supports PostgreSQL and SQLite. Choose the database with `DB_CONNECTION`. ## Choose a backend Use PostgreSQL for production deployments that need: * multiple application or worker hosts * horizontal scaling * higher write concurrency * managed backups, replicas, or high availability Use SQLite for a small mono-instance deployment that runs on one host. SQLite keeps the complete database in one local file and does not require a separate database server. * [Configure PostgreSQL](/self-hosting/database/postgresql) * [Configure SQLite](/self-hosting/database/sqlite) The `.env.minimal.example` file selects SQLite for mono-instance installations. The PostgreSQL Docker Compose stack persists its data in the `puppetflow-db` volume. ## Application state The database stores more than users, flows, and run history. With the default configuration, it also stores: * queued jobs * cache entries and distributed locks * sessions * scheduler coordination * mailbox delivery state * references to uploaded files and run artifacts Back up the database even when durable files are stored in S3 or R2. Object storage does not replace the database. ## Scaling rules PostgreSQL supports multiple Puppetflow application and worker instances connecting to the same database. SQLite is supported only when every process runs on one host and accesses the same local database file. Do not place the SQLite file on NFS, SMB, S3, R2, or a Kubernetes multi-node volume. Do not use SQLite for a horizontally scaled Kubernetes deployment. ## Change the database configuration After changing database environment variables, recreate every Puppetflow service and run migrations: ```bash docker compose up -d --force-recreate app queue-1 queue-2 scheduler mailbox-smtp docker compose exec app php artisan config:clear docker compose exec app php artisan migrate --force ``` Changing `DB_CONNECTION` does not copy existing data. Migrate data with database-specific tools before switching an existing installation. ::: warning Back up the current database before changing its configuration or running an upgrade. ::: --- --- url: https://docs.puppetflow.com/self-hosting/database/postgresql.md --- # PostgreSQL PostgreSQL is the default database for the production Compose stack and the recommended backend for horizontal scaling or deployments with application and worker processes on multiple hosts. ## Bundled PostgreSQL The production Docker Compose stack includes PostgreSQL 17 and stores its data in the persistent `puppetflow-db` volume. Configure the shared `.env` file: ```dotenv DB_CONNECTION=pgsql DB_HOST=postgres DB_PORT=5432 DB_DATABASE=puppetflow DB_USERNAME=puppetflow DB_PASSWORD= DB_SSLMODE=prefer ``` Set a strong, unique `DB_PASSWORD`. The `DB_DATABASE`, `DB_USERNAME`, and `DB_PASSWORD` values are also used to initialize the bundled PostgreSQL container. Start the stack and apply migrations: ```bash docker compose up -d docker compose exec app php artisan migrate --force ``` ## External PostgreSQL For a managed or external PostgreSQL service: ```dotenv DB_CONNECTION=pgsql DB_HOST=postgres.example.internal DB_PORT=5432 DB_DATABASE=puppetflow DB_USERNAME=puppetflow DB_PASSWORD= DB_SSLMODE=require ``` Allow connections from every Puppetflow application and worker host. The database user must be able to create and alter tables, indexes, foreign keys, and check constraints when migrations run. When the external service replaces the bundled database: 1. Remove the `postgres` service from the customized Compose file. 2. Remove `depends_on: postgres` from `app`, `queue-1`, `queue-2`, `scheduler`, and `mailbox-smtp`. 3. Remove the unused `puppetflow-db` volume. 4. Recreate the Puppetflow services. ## Queue, cache, and sessions The recommended configuration keeps application state in PostgreSQL: ```dotenv QUEUE_CONNECTION=database DB_QUEUE_RETRY_AFTER=900 CACHE_STORE=database SESSION_DRIVER=database ``` This configuration keeps queued jobs, cache entries, distributed locks, and sessions durable. Use Redis for these features only when connecting to a separate Redis deployment with persistence and backups. ## Backups Back up PostgreSQL independently from S3, R2, or local file storage. A basic logical backup is: ```bash docker compose exec -T postgres pg_dump \ --username=puppetflow \ --dbname=puppetflow \ --format=custom > puppetflow.dump ``` Restore into an empty database: ```bash cat puppetflow.dump | docker compose exec -T postgres pg_restore \ --username=puppetflow \ --dbname=puppetflow \ --clean \ --if-exists ``` Test restore procedures regularly. Managed PostgreSQL services should also use automated snapshots and point-in-time recovery when available. ## Operational checklist * Monitor free disk space, connections, slow queries, and lock waits. * Keep automated backups outside the database host. * Require TLS for external database connections. * Restrict network access to Puppetflow hosts. * Run `php artisan migrate --force` once during each application upgrade. --- --- url: https://docs.puppetflow.com/self-hosting/database/sqlite.md --- # SQLite SQLite is supported for small mono-instance installations on one host. It removes the separate database server, but it does not provide PostgreSQL's write concurrency, horizontal scaling, replicas, or managed high availability. ## Requirements SQLite deployments require: * PHP 8.4 or newer * one Docker host or one non-containerized server * a persistent local filesystem for the database file * the same database file mounted into the app, queue, scheduler, and mailbox services PHP 8.4 is required so Laravel starts write transactions with `BEGIN IMMEDIATE`. Puppetflow uses this behavior to serialize identity mutations and mailbox message claims safely. Do not use SQLite with a multi-node Docker Swarm or Kubernetes deployment. Do not store the database on NFS, SMB, S3, R2, or another network filesystem. ## Configure Puppetflow Use an absolute path on a persistent local volume: ```dotenv DB_CONNECTION=sqlite DB_DATABASE=/app/storage/database.sqlite DB_FOREIGN_KEYS=true DB_SQLITE_BUSY_TIMEOUT=5000 DB_SQLITE_JOURNAL_MODE=WAL DB_SQLITE_SYNCHRONOUS=NORMAL DB_SQLITE_TRANSACTION_MODE=IMMEDIATE QUEUE_CONNECTION=database DB_QUEUE_RETRY_AFTER=900 CACHE_STORE=database SESSION_DRIVER=database ``` The production Compose stack already mounts the `puppetflow-framework` volume at `/app/storage` in every Puppetflow service. This makes `/app/storage/database.sqlite` persistent and visible to the app, queue workers, scheduler, and mailbox server on the same Docker host. Keep `DB_SQLITE_TRANSACTION_MODE=IMMEDIATE`. Puppetflow rejects SQLite configurations that use another transaction mode. ## Docker Compose Use the dedicated [SQLite Compose file](https://puppetflow.com/install/docker-compose.prod-sqlite.yml), which is also installed by the automated installer. It has no PostgreSQL service and mounts `puppetflow-framework` at `/app/storage` in every PHP service. The SQLite stack runs one replica for each of `queue-1` and `queue-2`. This limits write contention while retaining the two queue indexes configured by `APP_QUEUES_COUNTER=2`. ## Initialize the database The SQLite stack creates the database file through its one-shot `init-volumes` service and applies migrations through its one-shot `migrate` service: ```bash docker compose up -d ``` Only hand-built stacks need to create the file and run `php artisan migrate --force` manually. When no users exist, the login page redirects to registration and the first registered user becomes the instance administrator. ## Backups The SQLite database must be backed up separately from uploads and run artifacts. Do not copy the live database file without coordinating with SQLite, especially while WAL mode is active. Create a consistent online backup with SQLite's `VACUUM INTO` command: ```bash docker compose exec app php artisan tinker --execute=" DB::statement(\"VACUUM INTO '/app/storage/database-backup.sqlite'\"); " docker compose cp \ app:/app/storage/database-backup.sqlite \ ./database-backup.sqlite ``` The backup destination must not already exist. Remove or rename the previous backup before running the command again. To restore: 1. Stop `app`, `queue-1`, `queue-2`, `scheduler`, and `mailbox-smtp`. 2. Preserve the current database file for rollback. 3. Replace `/app/storage/database.sqlite` with the backup. 4. Start the services and run `php artisan migrate --force`. ## Limitations * SQLite supports only one writer at a time. * Long write transactions can delay queue workers and web requests. * A single database file cannot coordinate Puppetflow instances on different hosts. * Database-backed queues, sessions, cache entries, and locks increase write activity. * High-volume mailbox ingestion or flow execution should use PostgreSQL. Move to PostgreSQL before adding hosts or increasing write-heavy workloads. Changing `DB_CONNECTION` does not transfer existing data automatically. --- --- url: https://docs.puppetflow.com/self-hosting/storage.md --- # Storage Puppetflow uses one durable storage backend for flow run artifacts and application uploads such as avatars and icons. Choose the backend with `APP_STORAGE_DISK`. | Backend | Value | Recommended for | | --- | --- | --- | | Local filesystem | `puppetflow-local` | A single server or development | | Amazon S3 | `puppetflow-s3` | AWS deployments and managed object storage | | Cloudflare R2 | `puppetflow-r2` | S3-compatible storage without egress fees | ## How storage works Files produced during a run are first written to the local execution workspace configured by `FLOW_EXECUTION_DIR`. Chromium and media-processing tools require this local workspace. When the run finishes, Puppetflow verifies and moves durable files to the selected storage backend. The execution workspace and durable storage have different roles: * `FLOW_EXECUTION_DIR` is temporary working space for active runs. Keep it local and shared with the browser service. * `APP_STORAGE_DISK` selects where completed artifacts and uploads are retained. * `APP_STORAGE_LOCAL_ROOT` is only used when the selected backend is `puppetflow-local`. Network response bodies captured by `$sniffNetwork` do not use the storage backend. During execution, they stay in the local workspace. When the run ends, Puppetflow imports them into the `flow_run_sniff_bodies` database table. Captured bodies are deleted with the run and count toward its storage size. Puppetflow records stored files in the database. Public application URLs remain Puppetflow URLs. With S3 or R2, Puppetflow redirects authorized requests to short-lived signed object URLs, so the bucket can remain private. Media Library uploads depend on the backend: * With `puppetflow-local`, Puppetflow proxies the upload. * With S3 or R2, the browser uses a short-lived presigned URL for one object. Puppetflow authorizes the destination, reserves storage quota, verifies the cloud object, and creates the media record. Bucket credentials are never sent to the browser. ## Choose a backend * [Configure Amazon S3](/self-hosting/storage/aws-s3) * [Configure Cloudflare R2](/self-hosting/storage/cloudflare-r2) For local storage: ```dotenv APP_STORAGE_DISK=puppetflow-local APP_STORAGE_LOCAL_ROOT=data/storage ``` The production Docker Compose stack persists `data/storage` in the `puppetflow-uploads` volume. ## Configuration variables The local backend uses: ```dotenv APP_STORAGE_DISK=puppetflow-local APP_STORAGE_LOCAL_ROOT=data/storage ``` Amazon S3 uses: ```dotenv APP_STORAGE_DISK=puppetflow-s3 APP_STORAGE_S3_PREFIX=puppetflow AWS_ACCESS_KEY_ID= AWS_SECRET_ACCESS_KEY= AWS_SESSION_TOKEN= AWS_DEFAULT_REGION= AWS_BUCKET= AWS_ENDPOINT= AWS_URL= AWS_USE_PATH_STYLE_ENDPOINT=false ``` Cloudflare R2 uses: ```dotenv APP_STORAGE_DISK=puppetflow-r2 APP_STORAGE_R2_PREFIX=puppetflow R2_ACCESS_KEY_ID= R2_SECRET_ACCESS_KEY= R2_SESSION_TOKEN= R2_REGION=auto R2_BUCKET= R2_ENDPOINT=https://.r2.cloudflarestorage.com R2_URL= R2_USE_PATH_STYLE_ENDPOINT=false ``` Leave session-token variables empty when using long-lived access keys. AWS workload identities can omit the AWS access key variables. See the backend-specific guides for bucket permissions and endpoint details. For direct Media Library uploads, the S3 or R2 bucket CORS policy must allow the Puppetflow `APP_URL` origin, the `PUT` method, and these request headers: * `Content-Type` * `Content-MD5` * `x-amz-checksum-sha256` Do not use a wildcard origin when the application is deployed with authenticated users. ## Apply a configuration change After changing storage environment variables, recreate every Puppetflow service that reads the shared `.env` file: ```bash docker compose up -d --force-recreate app queue-1 queue-2 scheduler mailbox-smtp docker compose exec app php artisan config:clear ``` ## Migrate existing files The migration command copies both run artifacts and application uploads. It verifies each copy before updating the stored location. 1. Configure the target backend credentials while keeping `APP_STORAGE_DISK` set to the current backend. 2. Recreate the application services so the target configuration is loaded. 3. Start with a dry run: ```bash docker compose exec app php artisan storage:migrate \ --from=puppetflow-local \ --to=puppetflow-s3 \ --dry-run ``` 4. Run the migration after checking the output: ```bash docker compose exec app php artisan storage:migrate \ --from=puppetflow-local \ --to=puppetflow-s3 ``` 5. Set `APP_STORAGE_DISK` to the target backend and recreate the application services again. Use `puppetflow-r2` as the target for R2. Every supported backend can be a source or target. Optional flags: * `--keep-source` retains verified source objects. * `--flow-id=` restricts migration to one flow. * `--chunk=` changes the database batch size. For a busy production instance, schedule a maintenance window so no new uploads or completed runs are written while the final migration and backend switch are performed. Back up the database and local storage before migrating. ::: warning Do not configure an S3 or R2 lifecycle rule that deletes objects independently of Puppetflow. The database would still reference those deleted objects. Use Puppetflow retention and cleanup instead. ::: ## Cleanup requirements Puppetflow records durable deletions in the database before removing files from local storage, S3, or R2. Queue workers process normal deletion jobs, and the scheduler retries pending deletions every minute. Keep the `queue-1`, `queue-2`, and `scheduler` services running. If the scheduler is stopped, failed deletions remain pending. After restoring it, you can process pending deletions immediately: ```bash docker compose exec app php artisan storage:cleanup-pending ``` Do not delete objects directly from the storage backend. Puppetflow checks database references before deletion and removes the corresponding storage records only after the backend operation succeeds. --- --- url: https://docs.puppetflow.com/self-hosting/storage/aws-s3.md --- # Amazon S3 This guide creates a private S3 bucket and credentials limited to Puppetflow storage. Puppetflow uses the bucket for completed run artifacts and application uploads. ## 1. Create the bucket 1. Sign in to the [AWS Management Console](https://console.aws.amazon.com/). 2. Search for **S3** in the top search bar and open the service. 3. In **S3 > General purpose buckets**, select **Create bucket**. 4. Enter a globally unique bucket name, such as `my-company-puppetflow-prod`. 5. Select the AWS Region closest to the Puppetflow server. 6. Keep **Object Ownership** set to **ACLs disabled (recommended)**. 7. Keep all four **Block Public Access** settings enabled. 8. Leave default encryption enabled. **SSE-S3** is sufficient unless your organization requires a customer-managed KMS key. 9. Select **Create bucket**. Record the bucket name and region. Do not enable static website hosting or add a public bucket policy. ## 2. Create a least-privilege policy The example below restricts Puppetflow to the `puppetflow/` prefix. 1. Search for **IAM** in the AWS Console and open it. 2. In the left menu, open **Access management > Policies**. 3. Select **Create policy**. 4. Select the **JSON** policy editor. 5. Paste the policy below. 6. Replace both occurrences of `my-company-puppetflow-prod` with your bucket name. 7. Select **Next**, name the policy `PuppetflowStorageAccess`, then select **Create policy**. ```json { "Version": "2012-10-17", "Statement": [ { "Sid": "ReadBucketLocationAndMultipartUploads", "Effect": "Allow", "Action": [ "s3:GetBucketLocation", "s3:ListBucketMultipartUploads" ], "Resource": "arn:aws:s3:::my-company-puppetflow-prod" }, { "Sid": "ListPuppetflowPrefix", "Effect": "Allow", "Action": "s3:ListBucket", "Resource": "arn:aws:s3:::my-company-puppetflow-prod", "Condition": { "StringLike": { "s3:prefix": [ "puppetflow", "puppetflow/*" ] } } }, { "Sid": "ManagePuppetflowObjects", "Effect": "Allow", "Action": [ "s3:GetObject", "s3:PutObject", "s3:DeleteObject", "s3:AbortMultipartUpload", "s3:ListMultipartUploadParts" ], "Resource": "arn:aws:s3:::my-company-puppetflow-prod/puppetflow/*" } ] } ``` If you change `APP_STORAGE_S3_PREFIX`, update `puppetflow` in the policy to the same value. ## 3. Give Puppetflow access ### Server running outside AWS 1. In IAM, open **Access management > Users**. 2. Select **Create user** and enter a name such as `puppetflow-storage`. 3. On the permissions step, choose **Attach policies directly**. 4. Search for and select `PuppetflowStorageAccess`. 5. Finish creating the user. 6. Open the new user and select the **Security credentials** tab. 7. Under **Access keys**, select **Create access key**. 8. Select **Application running outside AWS**, acknowledge the recommendation, and continue. 9. Add an optional description such as `Puppetflow production storage`. 10. Create the key and immediately copy both the **Access key ID** and **Secret access key**. The secret is shown only once. ### Server running on AWS Prefer an IAM role instead of long-lived access keys. Attach `PuppetflowStorageAccess` to the EC2 instance profile, ECS task role, or EKS service account role used by Puppetflow. Leave `AWS_ACCESS_KEY_ID` and `AWS_SECRET_ACCESS_KEY` unset so the AWS SDK can use the workload credentials. ## 4. Configure Puppetflow Add these values to the shared Puppetflow `.env` file: ```dotenv APP_STORAGE_DISK=puppetflow-s3 AWS_ACCESS_KEY_ID=AKIA... AWS_SECRET_ACCESS_KEY=... AWS_SESSION_TOKEN= AWS_DEFAULT_REGION=eu-west-3 AWS_BUCKET=my-company-puppetflow-prod AWS_ENDPOINT= AWS_URL= AWS_USE_PATH_STYLE_ENDPOINT=false APP_STORAGE_S3_PREFIX=puppetflow ``` * Use the region selected when creating the bucket. * Leave `AWS_ENDPOINT` and `AWS_URL` empty for AWS S3. * Leave `AWS_SESSION_TOKEN` empty for a normal IAM user access key. Temporary credentials supply this value with their session token. * Omit the access key variables when using an IAM workload role. Apply the configuration as described on the [Storage overview](/self-hosting/storage#apply-a-configuration-change). ## 5. Verify access If the AWS CLI is configured with the same user or role, verify that the bucket is reachable: ```bash aws s3api list-objects-v2 \ --bucket my-company-puppetflow-prod \ --region eu-west-3 \ --prefix puppetflow/ \ --max-items 1 ``` An exit code of zero means the check succeeded, even when the prefix is empty. An HTTP `403` usually means the identity or policy is wrong. An HTTP `301` generally means the configured region is wrong. For an existing installation, follow [Migrate existing files](/self-hosting/storage#migrate-existing-files) after the credentials are configured. ## Security checklist * Keep all S3 Block Public Access settings enabled. * Never place AWS credentials in source control. * Restrict the policy to one bucket and one prefix. * Rotate access keys periodically, or use an AWS workload role. * Do not add a public bucket policy. Puppetflow generates temporary signed URLs. See the AWS documentation for [creating a bucket](https://docs.aws.amazon.com/AmazonS3/latest/userguide/create-bucket-overview.html) and [blocking public access](https://docs.aws.amazon.com/AmazonS3/latest/userguide/access-control-block-public-access.html). --- --- url: https://docs.puppetflow.com/self-hosting/storage/cloudflare-r2.md --- # Cloudflare R2 Cloudflare R2 exposes an S3-compatible API and does not charge egress fees. This guide creates a private bucket and an API token restricted to Puppetflow storage. ## 1. Create the bucket 1. Sign in to the [Cloudflare dashboard](https://dash.cloudflare.com/). 2. Select the Cloudflare account that will own the bucket. 3. In the left menu, open **Storage & databases > R2**. 4. On the **Overview** page, select **Create bucket**. 5. Enter a bucket name, such as `puppetflow-prod`. 6. Choose a location hint or leave automatic placement selected. 7. Select **Create bucket**. Keep the bucket private. You do not need to enable an `r2.dev` public URL or connect a custom domain because Puppetflow generates temporary signed URLs. ## 2. Create S3 API credentials Creating a bucket does not automatically create credentials. You must generate a separate R2 API token: 1. Return to **Storage & databases > R2 > Overview**. 2. Select **Manage > API Tokens**. Depending on the dashboard version, this button may be labelled **Manage R2 API Tokens**. 3. Under **User API Tokens**, select **Create User API token**. An account API token also works, but a user token is easier to restrict to the person managing this installation. 4. Enter a descriptive token name, such as `Puppetflow production storage`. 5. Set **Permissions** to **Object Read & Write**. 6. Under **Specify bucket(s)**, choose **Apply to specific buckets only**. 7. Select the `puppetflow-prod` bucket. 8. Configure an expiration if required by your security policy. 9. Select **Create User API Token**. The confirmation page displays: * **Access Key ID** * **Secret Access Key** * The account-specific **S3 API endpoint** Copy the credentials immediately and save them in your password manager or secret store: * Copy **Access Key ID** to `R2_ACCESS_KEY_ID`. * Copy **Secret Access Key** to `R2_SECRET_ACCESS_KEY`. * Copy the **S3 API endpoint** to `R2_ENDPOINT`. The **Secret Access Key** cannot be displayed again. If you leave this page without saving it, create a new token and delete the unusable token. Do not use the API token value itself as `R2_SECRET_ACCESS_KEY`. The endpoint has this format: ```text https://.r2.cloudflarestorage.com ``` The endpoint is also displayed on the R2 **Overview** page. The value between `https://` and `.r2.cloudflarestorage.com` is your Cloudflare account ID. Use this S3 API endpoint, not an `r2.dev` URL, custom domain, dashboard URL, or bucket URL. ## 3. Configure Puppetflow Add these values to the shared Puppetflow `.env` file: ```dotenv APP_STORAGE_DISK=puppetflow-r2 R2_ACCESS_KEY_ID= R2_SECRET_ACCESS_KEY= R2_SESSION_TOKEN= R2_REGION=auto R2_BUCKET=puppetflow-prod R2_ENDPOINT=https://.r2.cloudflarestorage.com R2_URL= R2_USE_PATH_STYLE_ENDPOINT=false APP_STORAGE_R2_PREFIX=puppetflow ``` * `R2_ACCESS_KEY_ID` and `R2_SECRET_ACCESS_KEY` come from the token confirmation page. * `R2_REGION` must be `auto`. The bucket's location hint is not used as the S3 API region. * `R2_ENDPOINT` is the account-level S3 API endpoint. Do not append the bucket name. * Leave `R2_SESSION_TOKEN` and `R2_URL` empty. Apply the configuration as described on the [Storage overview](/self-hosting/storage#apply-a-configuration-change). ## 4. Verify access If the AWS CLI is configured with the R2 access key and secret, verify the bucket through its S3-compatible endpoint: ```bash aws s3api list-objects-v2 \ --bucket puppetflow-prod \ --endpoint-url https://.r2.cloudflarestorage.com \ --region auto \ --prefix puppetflow/ \ --max-items 1 ``` An exit code of zero means the check succeeded, even when the prefix is empty. A `403` response usually means the credentials, token permissions, account ID, or selected bucket is wrong. For an existing installation, follow [Migrate existing files](/self-hosting/storage#migrate-existing-files) after the credentials are configured. Use `puppetflow-r2` as the migration target. ## Security checklist * Keep the bucket private and leave public development access disabled. * Restrict the API token to **Object Read & Write** on the Puppetflow bucket only. * Never place R2 credentials in source control. * Rotate API tokens according to your security policy. * Do not expose the bucket through a custom domain. Puppetflow generates temporary signed URLs. See the Cloudflare documentation for [creating R2 buckets](https://developers.cloudflare.com/r2/buckets/create-buckets/) and [generating S3 API credentials](https://developers.cloudflare.com/r2/get-started/s3/#generate-api-credentials). --- --- url: https://docs.puppetflow.com/self-hosting/license-activation.md --- # License Activation Self-hosted Puppetflow instances require a signed license file. The file identifies your plan, instance allowance, usage limits, and enabled features. ## Get a license file For a paid plan: 1. Sign in to your account at [puppetflow.com](https://puppetflow.com). 2. Open **Account > Resources**. 3. Select your self-hosted license. 4. Click **Download license**. For the free Community plan, open the activation screen in your self-hosted installation and select **Free Community license**. Submit your email address, then follow the link sent by email to download the file. The downloaded file is either a `.license` file or a `.zip` archive containing it. Do not edit or rename its contents because the license is cryptographically signed. ## Choose the license holder for client work * **Your own organization:** Use a paid plan for internal business operations. Community is limited to personal, non-commercial use. * **Consulting on a client's instance:** * The account and license must belong to the client. * The instance must run in the client's Puppetflow Cloud account or on infrastructure controlled by the client. * Consultants do not need a separate license solely to install, configure, or maintain that instance. * **Hosting for clients:** If you control the instance and use it to run workflows, store credentials, or process data for clients, you need an Enterprise order or separate written agreement that expressly authorizes managed-service use. * **White-label branding:** The built-in white-label features are included with an active Enterprise subscription and do not require a separate written agreement. * **Client access, embedding, or resale:** These uses require an Enterprise order or separate written agreement that expressly authorizes the specific use. White-label branding alone does not grant these rights. See the [Terms of Service](/legal/terms-of-service) for the controlling rules. ## Activate a self-hosted instance 1. Install Puppetflow and create the first user. The first registered user becomes the instance administrator. 2. Sign in to the Puppetflow instance. 3. Open **Admin > Server**. 4. Select the **License** tab. 5. In **Activation file**, drop the downloaded `.license` or `.zip` file into the upload area. 6. Click **Upload and activate**. After activation, the License page displays the plan, status, limits, enabled features, and license identifier. ## Refresh entitlements Puppetflow periodically contacts the license service to refresh the signed entitlement token. To refresh immediately: 1. Open **Admin > Server > License**. 2. Click the refresh button next to the license status. An immediate refresh is useful after changing plans, applying a feature override, or receiving an updated license. ## Replace or remove a license Use **Replace license** in the Activation file section to upload a newer file. Replacing the file preserves the instance identity and refreshes its entitlements. Use **Delete license** only when moving the license to another installation or intentionally deactivating the instance. Features that require a license become unavailable after removal. ## Troubleshooting ### The upload is rejected * Confirm that the upload is the original `.license` file or downloaded `.zip` archive. * Download the file again from **Account > Resources**. * Verify that the license is active and has an available instance slot. * Do not extract, edit, or repackage the file. ### The license is active but features are outdated Click the refresh button on **Admin > Server > License**. If the displayed entitlements remain unchanged, download the license again and use **Replace license**. ### The instance cannot refresh its license Allow outbound access from the Puppetflow application container to the endpoint configured by `LICENSE_SERVER_URL`. The default is `https://lic.puppetflow.com`. Check the application logs for connection, DNS, TLS, or timeout errors. ### The MCP broker does not recognize the instance URL The universal MCP broker accepts only self-hosted URLs reported by an active licensed instance. After changing the instance domain or port, the broker can show "That self-hosted origin is not an active licensed instance." Update the reported address: 1. Set `APP_URL` to the new public origin in your instance configuration and restart the application. 2. Open **Admin > Server > License** on your instance and click the **Refresh button**, or use **Replace license** to upload the license file again. 3. Start the connection again from your MCP client. The instance also reports its address automatically on its periodic license check, so the new URL is picked up within a day even without a manual refresh. ### The License tab is unavailable Only an instance administrator can manage the activation file. Sign in with the first registered account or another user with the instance admin role. --- --- url: https://docs.puppetflow.com/self-hosting/admin.md --- # Admin Panel The first user to register is automatically promoted to admin. Admins have access to a system-wide administration panel. ## Accessing the panel The **Admin** group in the sidebar contains **Users**, **Workspaces**, and **Server**. It is only visible to instance administrators. ## Server settings The Server page contains **General** and **License** tabs. **Branding** and **SSO** tabs appear when their instance features are enabled. ### Authentication * **Invitation requests** - When enabled, anyone can request an account. An administrator must approve the request and assign its workspaces. When disabled, only direct workspace invitations can be used to create an account. * **Require magic link** - Users sign in and accept invitations with a one-time email code or secure link instead of a password. Before activation, Puppetflow sends a confirmation code to the administrator email address to verify outgoing mail. ### Data storage Shows the storage used by instance data and the active storage limit. ### Version The **About** card displays the application name and current Puppetflow version. ### License Shows license status, plan, entitlements, usage, and activation controls. See [License Activation](/self-hosting/license-activation). ## User management View, create, edit, and delete user accounts across the entire instance. | Action | Description | | --- | --- | | **Add user** | Add a new user with name, email, and password. | | **Edit user** | Update name, email, or password. | | **Delete user** | Remove the user and their personal resources. | | **View workspaces** | See which workspaces a user belongs to. | | **View flows** | See flows owned by a user. | | **Impersonate** | Sign in as a user for administration and support. | | **Invitation requests** | Approve a registration request and assign workspaces, or reject it. | | **Bulk delete** | Delete several selected users. | | **Search** | Find users by name or email. | ## Workspace management View and manage all workspaces on the instance. | Action | Description | | --- | --- | | **Create workspace** | Create a new workspace. | | **Edit workspace** | Update workspace details. | | **Delete workspace** | Permanently remove a workspace and all its contents. | | **Transfer ownership** | Move ownership to another member. | | **View members** | See workspace members and their roles. | | **View flows** | See all flows in a workspace. | | **Switch to workspace** | Open the workspace as an administrator. | ## Roles | Role | Scope | Description | | --- | --- | --- | | **Admin** | Instance | Full access to the admin panel and all workspaces. | | **Owner** | Workspace | Full control over a specific workspace. | | **Admin** | Workspace | Manage workspace settings and members. | | **Manager** | Workspace | Manage flows and shared resources. | | **Member** | Workspace | Create and manage own flows, access shared resources. |