Advanced Topics

Remoting

Control distributed dxflow servers from a single CLI using profile-based, key-authenticated connections.

Remoting lets one local CLI control distributed dxflow servers over HTTP/HTTPS, with separate profiles per environment.

Remoting needs two dxflow instances: a server (runs the REST API) and a client (the CLI that connects to it).

How it works

Two instances communicate over HTTP/HTTPS:

Client (local CLI) — runs your commands, manages profile config, handles authentication, and converts each command into an HTTP API call.
Server (remote target) — runs the REST API, executes the workflow engine, and manages resources.

CLI commands map directly to API calls. For example, dxflow workflow list becomes GET /api/workflow/ with an Authorization: Bearer <jwt-token> header.

Server setup (on the remote machine):

dxflow config set http-port 8080
dxflow boot up --daemon
# Exposes http://your-server:8080/api/engine/ping, /api/workflow/*, /api/shell/*

Client setup (on your local machine):

dxflow config set connection-address "http://your-server:8080"
dxflow config set connection-key "/path/to/server-key.pem"
# All commands now target the remote server
dxflow engine ping
dxflow workflow list

You point the CLI at the remote server's private key, and it handles the session token for you — requesting one when needed, reusing a valid one, and refreshing it automatically when it expires. This is the same key-based sign-in described in the Authentication docs.

Getting started

Set the server address

# HTTPS for production (recommended)
dxflow config set connection-address "https://your-server.com"
# HTTP for dev/testing
dxflow config set connection-address "http://192.168.1.100:8080"

Set up authentication

dxflow config set connection-key "/path/to/server-private-key.pem"

Verify

dxflow engine ping

Once authenticated, all dxflow commands target the remote server.

Authentication methods

Key-based (recommended) — automatic. The CLI signs in with your private key, and the server issues a session token that is stored and refreshed for you.

dxflow config set connection-key "/path/to/server-private-key.pem"

Manual token — for quick testing, temporary access, or environments without private-key access:

dxflow engine token                                  # run on the remote server
dxflow config set connection-token "eyJhbGciOiJSUzI1NiJ9..."
dxflow engine ping

Environment variables — temporary override with no permanent config change (useful for CI/CD):

export CONNECTION_ADDRESS="https://temp-server.com"
export CONNECTION_KEY="/temp/keys/temp-key.pem"
dxflow engine ping

Profiles

Profiles keep multiple servers isolated — each has its own connection settings and credentials with no cross-contamination. Switch profiles with --config-profile <name> (short: -C <name>).

# Development
dxflow --config-profile dev config set connection-address "http://dev-server:8080"
dxflow --config-profile dev config set connection-key "/keys/dev-key.pem"
dxflow -C dev engine ping

# Production
dxflow --config-profile prod config set connection-address "https://prod-server.com"
dxflow --config-profile prod config set connection-key "/keys/prod-key.pem"
dxflow -C prod engine ping

# Multi-cloud (one profile per provider)
dxflow -C aws   config set connection-address "https://dxflow.us-west-2.amazonaws.com"
dxflow -C aws   config set connection-key "/keys/aws-key.pem"
dxflow -C gcp   config set connection-address "https://dxflow.us-central1.gcp.com"
dxflow -C gcp   config set connection-key "/keys/gcp-key.pem"
dxflow -C azure config set connection-address "https://dxflow.eastus.azure.com"
dxflow -C azure config set connection-key "/keys/azure-key.pem"

Common use cases

# Promote a workflow through environments
dxflow -C dev workflow create ./my-workflow.yaml
dxflow -C dev workflow logs my-workflow --live
dxflow -C staging workflow create ./my-workflow.yaml
dxflow -C prod workflow create ./my-workflow.yaml

# Monitor / deploy across clouds
dxflow -C aws engine stat
dxflow -C gcp engine stat
dxflow -C azure engine stat

# CI/CD via env vars
export CONNECTION_ADDRESS="https://staging-server.com"
export CONNECTION_KEY="/ci/keys/staging-key.pem"
dxflow workflow create ./build-artifacts/workflow.yaml
dxflow engine healthcheck || exit 1

# Disaster-recovery failover
if ! dxflow -C primary engine ping; then
  dxflow -C backup workflow create ./critical-services.yaml
fi

Configuration storage

Profile	Configuration file
Default	`~/.dxflow/default_config.yaml`
Custom	`~/.dxflow/{profile-name}_config.yaml`

# Example: ~/.dxflow/production_config.yaml
connection-address: "https://prod.company.com"  # Base URL (no /api suffix)
connection-key: "/secure/keys/prod-key.pem"     # RSA private key path
connection-token: "eyJhbGc..."                  # Auto-generated JWT token

Each setting can be overridden temporarily via an environment variable:

Environment variable	Config key
`CONNECTION_ADDRESS`	`connection-address`
`CONNECTION_KEY`	`connection-key`
`CONNECTION_TOKEN`	`connection-token`

Troubleshooting

Connection issues

dxflow config get connection-address                                    # verify address
curl -k "$(dxflow config get connection-address)/api/engine/healthcheck/" # test HTTP
ping your-server.com                                                     # DNS
telnet your-server.com 443                                              # firewall/port

For timeouts/network errors: confirm the server is running and reachable, check corporate firewall/proxy settings, verify HTTPS certificates, or try HTTP for testing.

Authentication issues

chmod 600 /path/to/your-key.pem        # fix key permissions
dxflow config unset connection-token   # force token refresh
dxflow engine ping
dxflow config set connection-token "new-token-from-server"  # manual token (temporary)

Also check that the private key matches the public key on the server, the key file is intact, and the system clock is synchronized (affects token timing).

Profile issues

dxflow config get connection-address          # verify active config
dxflow --config-profile correct-env engine ping  # use explicit profile
ls ~/.dxflow/*_config.yaml                     # list profiles

Ensure each profile has unique settings, no typos in profile names, and correct profile-specific credentials.

Security best practices

Store private keys with chmod 600 and use a separate key per environment.
Use HTTPS for production.
Create separate profiles per team member and environment.
Monitor authentication logs and rotate keys periodically.

Common commands

# Connection management
dxflow config                                          # view current config
dxflow config get connection-address
dxflow config set connection-address "https://new-server.com"
dxflow config set connection-key "/path/to/new-key.pem"
dxflow engine ping
dxflow engine healthcheck

# Profile operations
dxflow --config-profile aws engine stat
dxflow -C gcp workflow list
dxflow -C dev config set connection-address "https://dev-server.com"
dxflow -C prod config unset connection-token   # force token refresh
dxflow -C prod engine ping

Tunneling

Expose local services through authenticated WebSocket bridges using the proxy-bridge architecture

Agent

How the dxflow agent creates and operates workflows — providers, capabilities, and sessions