From a verified binary to your first controlled operation.

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.

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

From the extracted binary’s folder, run these commands in a terminal under your user account. They install HelixFlow and select the same folders for your terminal, Claude and Codex. Keep this session open for the following steps. Replace “you” with your account name in the illustrative paths: C:\Users\you\HelixFlow\helixflow-windows-amd64.exe

.\helixflow-windows-amd64.exe version

2. Activate the machine license

Generate request.json with the current release on the machine that will run HelixFlow. The request remains a JSON file; the license you receive is an HFL1 .lic file. A demo lasts 7 days (168 hours); a perpetual license never expires. Both are bound to the machine.

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

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

Have an older JSON license? Keep the old binary and ask the publisher to reissue it using a fresh request from the current client. Renaming the file does not convert it. Migration does not restart an evaluation period. Contact

Download helixflow.lic from your account after issuance (a perpetual license requires publisher approval). Place it in the terminal’s current folder, then import and check it:

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

3. Configure a profile

A profile is a small YAML text file that tells HelixFlow which SecureTransport (ST) server to contact and how to sign in. Create it on your computer. The portal receives neither this file nor your ST credentials.

Before you start: ask for your ST connection details

SecureTransport manages your organisation’s accounts and file transfers. These examples use its administrator access.

1. Ask for the ST administration HTTPS address and port, such as https://st01.example.test:8444. 8444 is an example; your port may differ. Do not include /api/v2.0 or a Web page path in base_url.
2. Ask for an ST administrator account with permission for your read operations. Your HelixFlow portal account and an ST file-transfer account do not replace this administrator account.
3. Confirm with the ST team that your computer can reach this address over the internal network or VPN, then test the account in the ST Web console. Ask the team to resolve expired passwords or locked accounts.

Server certificate: “Is this the expected ST server?”

The tls block verifies the server: system uses authorities trusted by your operating system; ca uses the authority file supplied by your team; insecure disables this verification.

Client certificate: “Who is connecting to ST?”

The client_auth block presents your certificate to ST and uses its private key locally to prove your identity. This is called mTLS. The private key is never sent to the server; only the public certificate can be shared.

Choose one of the two methods below: A. Sign in with a username and password · B. Sign in with a client certificate

Choose an explicit configuration root

If you opened a new terminal, restore these four variables before any license or MCP setup command. The folders stay under your user directory, including with Codex on Windows: C:\Users\you\HelixFlow\config

$env:HELIXFLOW_CONFIG_DIR = 'C:\Users\you\HelixFlow\config'

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

Open a text editor, paste one complete example and save it as validation.yaml, not validation.yaml.txt. Keep indentation spaces; do not use tabs. These examples are alternatives: replace the file contents instead of joining them together.

A. Sign in with a username and password

Use your ST administrator username and password. YAML only specifies where HelixFlow finds them: never put their values in login or password fields.

Example with server verification

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

Replace the example address. env_class describes the actual target: test for a lab, preprod for staging, prod for production. Never label a production server as test. validation is the filename without .yaml.

Lab example with tls.mode: insecure

If your lab uses an untrusted self-signed server certificate, this example allows an initial test. HTTPS still encrypts the connection, but HelixFlow no longer verifies the server’s identity: an impersonating server could capture your credentials.

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

Use insecure only in an isolated lab. For normal use, choose system or reuse the tls block from the certificate example below (mode: ca and an absolute path to server-ca.pem). Obtain this authority certificate from your ST team. Username/password authentication does not require insecure mode.

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

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

printf 'ST login: '; IFS= read -r HELIXFLOW_LOGIN
printf 'ST password: '; IFS= read -rs HELIXFLOW_PASSWORD; printf '\n'
export HELIXFLOW_LOGIN HELIXFLOW_PASSWORD

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

B. Sign in with a client certificate

This method replaces the ST password with a trusted certificate mapped to your ST administrator. Set up ST with its administration team first, then configure your computer.

1. Obtain the files from the ST or PKI team

PKI is the team or service that issues certificates. Request an X.509 certificate for client authentication (clientAuth usage), its matching key and the trusted authorities. Renaming a file does not change its format.

client.pem

Your public certificate in PEM format, followed by intermediate certificates if needed. It contains your identity and an expiry date.

client.key

The matching private key in unencrypted PEM format, protected by operating-system permissions. If you receive a P12/PFX or an encrypted PEM key, use the P12 alternative below with help from your PKI team.

client-issuer-ca.pem

The public certificate of the authority that signed your client certificate, with any required intermediates. The ST team uses it to establish trust.

server-ca.pem

The authority your computer uses to verify the ST server’s HTTPS certificate. It may differ from the authority that signed your client certificate.

2. Configure certificate authentication in SecureTransport

Perform these steps in the ST administration console with an authorised administrator. The labels below match classic ST interfaces and may vary by version.

1. Keep a tested backup administrator login using a password and prepare a recovery procedure before changing settings.
2. In Setup > Certificates > Trusted CAs, import the client certificate’s issuing authority and its intermediates with the ST team. Import public certificates only, never client.key.
3. In Setup > Admin Settings, enable administrator login using client certificates. Select Client certificates: optional and accept trusted issuers (any trusted issuer). Save. Do not require certificates for this initial test.
4. In Accounts > Administrators, open the intended administrator and set Certificate DN to the exact subject of their client certificate. The DN is the full identity, such as CN=helixflow-reader,O=Example; it is not necessarily the username. Save.
5. Have the ST team apply the setting and restart the ST administration service following its procedure. This can interrupt console access; restarting only the file-transfer HTTP service does not replace this step.
6. After the restart, verify that the backup password login still works. Then test the new certificate profile with a read operation as described below.

To display the public certificate’s subject, run this command from its folder if OpenSSL is installed. Copy the value after subject=, without that prefix, and ask the ST team to verify its exact match with Certificate DN. Otherwise, ask the team for the DN.

openssl x509 -in client.pem -noout -subject -issuer -dates -nameopt RFC2253

This procedure covers the administrator API. Authentication > Login Settings and a transfer account’s Login Certificates configure a different access. If the administrator uses LDAP or external authentication, have the ST team confirm certificate/dual compatibility before continuing.

Axway references: consult “Administrator login options” and administrator management for your version. Axway SecureTransport 5.5 — Administrator Guide · Axway — LDAP (KB 71206)

3. Create the profile and protect the key on your computer

Create a certs folder under the configuration root chosen above and put the files there. Replace “you” in ca_path with your account name: this path must be absolute. The ../certs paths in client_auth start from the profiles folder containing validation.yaml and work on all three systems.

config/
  profiles/
    validation.yaml
  certs/
    server-ca.pem
    client.pem
    client.key

base_url: https://st01.example.test:8444
env_class: test
tls:
  mode: ca
  ca_path: 'C:/Users/you/HelixFlow/config/certs/server-ca.pem'
client_auth:
  mode: certificate
  cert_path: ../certs/client.pem
  key_path: ../certs/client.key

There is no credentials block: this selects certificate-only authentication without an ST username/password. If your system already trusts the server certificate, use tls.mode: system and remove ca_path. Verify that the hostname in base_url appears in the server certificate.

On Windows, open client.key Properties > Security > Advanced. With support assistance if needed, restrict access to your Windows account; SYSTEM and local administrators may retain access. Remove other user/group access, including overly broad inherited permissions. HelixFlow rejects an insufficiently protected key.

chmod 700 "$HELIXFLOW_CONFIG_DIR/certs"
chmod 600 "$HELIXFLOW_CONFIG_DIR/certs/client.key"

base_url: https://st01.example.test:8444
env_class: test
tls:
  mode: ca
  ca_path: 'C:/Users/you/HelixFlow/config/certs/server-ca.pem'
client_auth:
  mode: certificate
  format: pkcs12
  cert_path: ../certs/client.p12
  passphrase_entry: p12-passphrase

keyring set helixflow/validation p12-passphrase

credentials:
  source: env

4. Verify the connection without changing ST

Connect your assistant in the next step, then call server_info to check the local MCP. This does not test ST. Next, ask to list accounts using the validation profile: a response without errors confirms the ST connection and read permissions for that call. An empty list can simply mean no accounts are visible. 4. Connect your assistant · 5. Perform a first read

4. Connect your assistant

These three examples use the same binary, license and folders. Run the commands in the guide’s terminal session. If securetransport already exists, update its existing entry in your client.

Claude Desktop

Replace “you” with your account name in every path. Merge this entry with your other servers in %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.

On Linux, use Claude Code or another MCP client that supports stdio.

Claude Code

With Claude Code installed, register the server for your user account:

Codex

With the Codex CLI installed, register the same server. Codex will explicitly use the shared license folder:

Check only the client you use, then fully quit and restart Claude or Codex to load its updated configuration. In the assistant, call server_info and check the reported version.

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.

1. Validate the flow document with flow_validate.
2. Preview it with flow_plan and review the returned plan reference.
3. 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. For a production target, follow the approval requirements returned by the tool.

Subscriptions (options, flow attributes, no transfer configuration) are managed through flow documents. For routes, a template that executes other routes can be updated in a targeted way: its description, the status of one step, or one execute-route step appended at the end; removing such a step is refused. A complete export now round-trips.

The flows folder set by HELIXFLOW_FLOW_DIR is the allowed root for flow_path documents and certificates imported through a flow. The client_auth connection certificate stays in the certs folder described in step 3.

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

“unknown authority”: check server-ca.pem and tls.ca_path. An incorrect hostname requires fixing base_url or the certificate, not switching to insecure. “certificate required” or “bad certificate”: have the client certificate, its chain and ST’s trusted authorities checked.

Authentication is refused

A 401 error means ST rejected the identity; 403 may indicate insufficient permissions. With a password, check credentials, account locks and the keyring or environment received by the MCP process. With a certificate, check Certificate DN, the trusted issuer, the optional setting and the administration restart. Confirm whether ST requires dual mode.

The certificate file or key is rejected

Check paths relative to the profile folder, validity dates, the certificate/key match and permissions. A standalone encrypted PEM key is unsupported: use a P12 with its password in the keyring. For P12, also check the helixflow/validation → p12-passphrase entry.

The license is refused

Run license status in the configured session above. Check HFL1 format, the target machine and expiration. HELIXFLOW_LICENSE_DIR must match in the terminal and MCP client. An older JSON license must be reissued.