Remoting
Point the CLI at a remote engine and every command targets it instead of the local machine. Keep one profile per environment and switch between them with a flag.
How it works
Remoting needs two dxflow instances:
- Server — a booted engine on the remote machine, serving the REST API over HTTP or HTTPS.
- Client — your local CLI, which turns each command into an API call against that address.
dxflow workflow list becomes GET /api/workflow/ with an Authorization: Bearer <jwt> header. Nothing else changes: the same commands, flags, and output work locally and remotely.
Setup
Boot the engine on the remote machine
dxflow config set http-port 8080
dxflow boot up --http --daemon
Point the client at it
dxflow config set connection-address "http://your-server:8080"
dxflow config set connection-key "/path/to/server-private-key.pem"
The key is the engine's own private key, at ~/.dxflow/private-key.pem on the server. Copy it across, or register a dedicated key — see Authentication.
Verify
dxflow engine ping
dxflow workflow list
The CLI handles the session for you: it signs the challenge with your key, stores the token as connection-token, and refreshes it when it expires.
Other ways to authenticate
Manual token — for CI or a host where the private key can't go:
ssh remote "dxflow engine token" # print a token on the server
dxflow config set connection-token "eyJhbGciOi..." # paste it into the client
Manual tokens expire and are not refreshed for you.
Pairing code — for a browser rather than the CLI. Run dxflow engine pair on the server and enter the code in the console.
Profiles
Each profile carries its own address, key, and token, so environments never bleed into each other. Select one with --config-profile <name> (short -C).
# Configure once
dxflow -C dev config set connection-address "http://dev-server:8080"
dxflow -C dev config set connection-key "/keys/dev-key.pem"
dxflow -C prod config set connection-address "https://prod-server.com"
dxflow -C prod config set connection-key "/keys/prod-key.pem"
# Then target either
dxflow -C dev workflow create ./my-workflow.yml --start
dxflow -C prod workflow list
dxflow -C prod engine stats
Leaving -C off uses the default profile, which is your local engine unless you've pointed it elsewhere.
Configuration storage
| Profile | Configuration file |
|---|---|
| Default | ~/.dxflow/default_config.yaml |
| Custom | ~/.dxflow/{profile-name}_config.yaml |
# ~/.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..." # managed for you
Any setting can be overridden for one command with an environment variable — useful in CI, where no config file exists:
export CONNECTION_ADDRESS="https://staging-server.com"
export CONNECTION_KEY="/ci/keys/staging-key.pem"
dxflow workflow create ./workflow.yml --start
dxflow engine healthcheck || exit 1
| Environment variable | Config key |
|---|---|
CONNECTION_ADDRESS | connection-address |
CONNECTION_KEY | connection-key |
CONNECTION_TOKEN | connection-token |
Troubleshooting
| Symptom | Fix |
|---|---|
connection refused | The engine isn't booted, or it's listening on a different port. Check with curl "$(dxflow config get connection-address)/api/engine/ping/". |
| Request times out | A firewall or security group is blocking the port. The engine only listens where --http/--https opened one. |
401 Unauthorized | dxflow config unset connection-token && dxflow engine ping re-runs the challenge. |
| Signature rejected | The private key doesn't match a key registered on that server. Check dxflow key list there. |
| Commands hit the wrong engine | dxflow config get connection-address shows the active profile's target; pass -C <profile> explicitly. |
| TLS certificate errors | --https serves the chain at https-cert / https-key. Point those at a trusted certificate, activate a link to get one issued, or terminate TLS at a proxy in front. |
Store private keys with chmod 600, use a separate key per environment, and prefer HTTPS for anything crossing a network you don't control.