From a verified binary to your first controlled operation.

Install HelixFlow, activate its machine license, connect an MCP client, and start with a test environment.

1. Download and install

Choose the binary matching the operating system and architecture of the target machine. Verify its SHA-256 hash on the Downloads page, then place it in a durable location.

Operating system

Architecture

Open Downloads

Extract the Windows archive

Extract the ZIP in the download folder. The commands below use the extracted .exe file.

Expand-Archive -LiteralPath '.\helixflow-windows-amd64.exe.zip' -DestinationPath '.'

Verify file integrity

From the download folder, calculate the hash and compare it with the value shown on the Downloads page.

Get-FileHash .\helixflow-windows-amd64.exe -Algorithm SHA256

Use a durable location

Move the binary out of the temporary download folder. This guide uses the example path C:\Outils\HelixFlow\helixflow-windows-amd64.exe

.\helixflow-windows-amd64.exe version

2. Activate the machine license

Generate the request on the machine that will run HelixFlow. Sign in to request a demo or perpetual license, then transfer the downloaded license file back to that machine if it is offline.

.\helixflow-windows-amd64.exe license request --out request.json

The request identifies the machine for licensing. Review where you transfer it and do not publish it.

Submit request.json for a demo

After approval, download helixflow.lic on your account page, transfer it to the target machine if needed, then import and inspect it:

.\helixflow-windows-amd64.exe license import helixflow.lic
.\helixflow-windows-amd64.exe license status

3. Configure a profile

The profile contains the server address, environment class, TLS policy, and credential source. Credentials stay in the operating-system keyring or supported process environment.

Choose an explicit configuration root

Use the same root in your terminal and MCP client. This guide uses C:\Outils\HelixFlow\config

$env:HELIXFLOW_CONFIG_DIR = 'C:\Outils\HelixFlow\config'

Create the profiles directory, then create C:\Outils\HelixFlow\config\profiles\validation.yaml

base_url: https://st01.example.test:8444
env_class: test
tls:
  mode: system
credentials:
  source: env

Replace the illustrative address with your test target. env_class accepts test, preprod, or prod. HTTPS is required except on loopback.

Enter credentials in PowerShell

The Windows profile uses credentials.source: env. Run this interactive prompt in the same PowerShell session, then start your MCP client from that session.

$stCredentials = Get-Credential -Message 'SecureTransport credentials for validation'
$env:HELIXFLOW_LOGIN = $stCredentials.UserName
$env:HELIXFLOW_PASSWORD = $stCredentials.GetNetworkCredential().Password
Remove-Variable stCredentials

These variables live only in this PowerShell process and its children. Enter them again in each new session and close the session after use.

System keyring

On macOS and Linux, use the service helixflow/validation and the login and password entries. If the keyring utility is configured, these commands prompt interactively.

keyring set helixflow/validation login
keyring set helixflow/validation password

The keyring must be accessible to the MCP process running under the same operating-system account.

Never paste SecureTransport credentials into this site, an MCP configuration file, or an assistant conversation.

4. Connect your assistant

Configure your MCP client to launch the local binary over standard input and output. Point HelixFlow to your profile directory through its environment.

Claude Desktop

Add the following entry to %APPDATA%\Claude\claude_desktop_config.json

A Desktop process launched outside the PowerShell session does not inherit its credentials. Use a verified launch method from that session or use Claude Code.

Claude Code

Keep SecureTransport credentials in the operating-system keyring or the supported process environment. Never paste them into a conversation.

5. Perform a first read

Start with server_info to verify the MCP connection without contacting SecureTransport. Then request a read using the exact test profile name.

The validation profile maps to validation.yaml. Confirm its target before the first call. Reads can use a thirty-second cache by default.

6. Prepare a change

Flow changes use an explicit cycle. These names are MCP tools, not terminal commands.

Validate the flow document with flow_validate.
Preview it with flow_plan and review the returned plan reference.
Confirm before flow_apply uses the same document and plan reference.

A plan expires after fifteen minutes by default. A changed document must be planned again. MCP refuses mutations against a production profile.

For flow_path or certificate files, set HELIXFLOW_FLOW_DIR in the MCP environment. Files must remain below that allowed root.

7. Troubleshoot

The client cannot find the binary: Check the absolute path, architecture-specific filename, and execute permission on macOS or Linux. Run version again in a terminal.
No profile is found: Check HELIXFLOW_CONFIG_DIR and its profiles subdirectory. The requested name matches the YAML filename without its extension.
TLS connection fails: Check the address, certificate, and trust chain. For an internal authority, use tls.mode: ca with a valid tls.ca_path.
Authentication is refused: Check the keyring service or the environment inherited by the MCP process. A desktop process can have a different environment from your terminal.
The license is refused: Run license status on the target machine. Confirm that helixflow.lic belongs to that machine and that a demo has not expired.

Report an incident Contact