Advanced Topics

Boot

Learn how to boot and configure the dxflow engine with various deployment modes and network options

The dxflow engine boots in different modes for different scenarios, from local development to production services.

Quick start: dxflow boot up --http serves over HTTP in the foreground. With no protocol flag, the engine listens on a Unix socket only.

Boot modes

Mode	How	Behavior
Foreground (default)	`dxflow boot up`	Runs in the current terminal; interactive logs; stops when the terminal closes
Background	`dxflow boot up --daemon`	Runs as a system service (Linux only); persists across reboots
Instant	automatic	Internal boot for CLI commands that finish their work before returning; starts and shuts down on its own

Global configuration

These flags must be placed before the boot command:

dxflow [GLOBAL_FLAGS] boot up [BOOT_FLAGS]

Flag	Short	Default	Description
`--config-profile`	`-C`	`default`	Configuration profile to use
`--log-level`	`-L`	`info`	Logging verbosity (debug, info, error, disabled)
`--no-color`	`-N`	`false`	Disable colored terminal output

Boot command options

Flag	Default	Description
`--http`	`false`	Serve over HTTP
`--https`	`false`	Serve over HTTPS
`--console`	`false`	Serve the web console (auto-enables HTTP)

Unix socket default: With no protocol flag, the engine listens on a Unix socket only. Pass --http/--https to expose a network listener, or --console to serve the web console (which auto-enables HTTP when no other protocol is requested).

Flag	Short	Default	Description
`--proxy`	`-p`	`false`	Enable subdomain allocation service
`--bridge`	`-b`	`false`	Connect to hub dxflow instance

Mutual Exclusion: --proxy and --bridge cannot be used together on the same machine.

Flag	Short	Default	Description
`--daemon`	`-d`	`false`	Run as background service (Linux only)

Supported Platforms: Linux with SystemD or OpenRC

Network architecture

--proxy and --bridge define an engine's role in a hub-and-node topology. They are mutually exclusive on the same machine.

Aspect	Proxy mode (hub)	Bridge mode (node)
Role	Central hub — provides subdomains	Node — receives a subdomain from a hub
Connections	Receives connections	Makes connections
Requirements	Public IP + DNS control	Internet access only (works behind NAT/firewall)
Performance	Direct routing, low latency	Tunneled, higher latency
Best for	Production platforms, multi-tenant routing	Development, testing, low-traffic external access

Subdomain format: ab1234567890.your-domain.com (lowercase: 2 letters + 1–10 alphanumeric characters, 3–12 total), allocated under the hub's proxy-domain. The hub manages SSL for its nodes. Point each node at your hub with bridge-gateway — see tunneling.

Bridge management

When engine is running with --bridge, you can manage connections dynamically:

# Check bridge status and get identity
dxflow bridge list

# Disconnect from hub (stops tunnel, keeps engine running)
dxflow bridge disconnect <identity>

# Reconnect to hub (restores tunnel)
dxflow bridge connect <identity>

Note: You need the bridge identity to disconnect/connect. Use dxflow bridge list to find the identity first.

This allows dynamic bridge management without restarting the entire engine.

Quick start examples

Development setup

Start with debug logging for development:

dxflow --log-level=debug boot up --http

Production hub

Deploy as a hub server with HTTPS and daemon mode. The production profile must set proxy-domain:

dxflow --config-profile=production config set proxy-domain "your-domain.com"
dxflow --config-profile=production boot up --https --proxy --daemon

Production node

Connect to a hub as an edge instance. The edge profile must set bridge-gateway and bridge-identity:

dxflow --config-profile=edge config set bridge-gateway "https://your-domain.com/"
dxflow --config-profile=edge config set bridge-identity "mynode01"
dxflow --config-profile=edge boot up --bridge --daemon

Service management

Starting & stopping

# Start serving over HTTP (foreground mode)
dxflow boot up --http

# Start as daemon service
dxflow boot up --http --daemon

# Stop daemon service
dxflow boot down

Health monitoring

# Quick availability check
dxflow ping

# Detailed health status
dxflow healthcheck

Daemon configuration

Log Files: /tmp/dxflow.out and /tmp/dxflow.err
Service File: ~/.config/systemd/user/dxflow.service (user unit)
PID Management: Handled by systemd

# Service management (user unit)
systemctl --user status dxflow
systemctl --user start dxflow
systemctl --user stop dxflow
systemctl --user restart dxflow

# View logs
journalctl --user -u dxflow -f
tail -f /tmp/dxflow.out
tail -f /tmp/dxflow.err

Log Files: /tmp/dxflow.out and /tmp/dxflow.err
Service File: /etc/init.d/dxflow

# Service management
rc-service dxflow status
rc-service dxflow start
rc-service dxflow stop
rc-service dxflow restart

# View logs
tail -f /tmp/dxflow.out
tail -f /tmp/dxflow.err

Architecture patterns

Hub-Node setup

Scenario: One hub machine manages multiple node machines

Internet Users → [Hub: your-domain.com] (--proxy --https --daemon)
                      ├── ab1234567890.your-domain.com → API server (--bridge)
                      ├── cd9876543210.your-domain.com → Dev server (--bridge)
                      ├── ef5a8b2c9d1e.your-domain.com → Local machine (--bridge)
                      └── gh7x4m8n2p5q.your-domain.com → CI/CD (--bridge)

Important: Each machine can only be a hub OR node, never both simultaneously.

Troubleshooting

Port already in use

Check processes using configured ports: netstat -tulpn | grep :PORT
Stop conflicting services or change port configuration

Permission denied (daemon)

On SystemD the engine installs a user service (systemctl --user); make sure a user session/login lingering is available for it to persist after logout
On OpenRC the service unit lives at /etc/init.d/dxflow and may require elevated privileges to install

Cannot use proxy and bridge together

These modes are mutually exclusive on the same machine
Choose one architecture role per instance

Bridge connection fails

Ensure hub instance has --proxy enabled
Check network connectivity to hub
Verify hub is accessible and running

Bridge disconnects frequently

Check network stability and firewall settings
Review hub server logs for connection issues
Consider network timeout configurations

For boot-related assistance:

Check engine status: dxflow ping
Review detailed health: dxflow healthcheck
Check logs in daemon mode (see platform-specific locations above)
Report issues at GitHub

Licensing

Create and manage dxflow licenses and understand the available permissions

Container Runtimes

Configure Docker, Podman, Singularity, and Apptainer, including running them through a VM wrapper (OrbStack, Lima, WSL) on macOS and Windows