Using remote machines

AxonX can call a service on another machine. Tasks execute in the called service's Python environment and use its plugins, workspace, and log directory. CLI direct connections and Studio backend forwarding require separate credential configuration.

Prepare the target service

Install AxonX, required research plugins, and model dependencies on the target machine, configure a separate service token, then start:

export AXONX_SERVICE_TOKEN='<target service token>'
axonx start --service.host 0.0.0.0 --service.port 1024

The target's HTTP(S) address must be reachable by clients. The built-in Uvicorn service does not handle TLS; terminate HTTPS externally for deployment across networks. See Deployment guide.

CLI direct connections

export AXONX_TARGET_TOKEN='<target service token>'
axonx version --target 'http://research.example:1024'
axonx get_task_definition --task demo --target 'http://research.example:1024'
axonx submit --task demo --x 1 --y 2 --target 'http://research.example:1024'

The domain here is a placeholder and must be replaced. The CLI connects directly to the target; it requires neither a running local AxonX service nor adding the target to local targets.

With an explicit --target, the CLI reads credentials from AXONX_TARGET_TOKEN by default; without one, it connects to the local service and reads AXONX_SERVICE_TOKEN. --token overrides the environment source.

Continue selecting the same target when waiting, checking status, and reading logs. TaskHandle does not turn the remote address into automatic routing information; retain the target address alongside it in scripts or experiment records.

Studio backend forwarding

Studio requests its own same-origin backend, and the browser stores the local service token. The backend selects preconfigured remote credentials based on the request's target.

One target: built-in remote configuration

Set these values in .env in the local startup directory:

AXONX_SERVICE_TOKEN=your-local-service-token
AXONX_TARGET=192.0.2.10:1024
AXONX_TARGET_TOKEN=your-target-service-token

Replace the address and credentials, then start the local service:

axonx start --config remote

The built-in remote configuration extends default and adds the target address and token to targets. Set the local token in Studio, then select the remote machine. AXONX_TARGET does not redirect ordinary CLI commands that omit --target; direct CLI access still requires the explicit address as shown above.

Multiple targets: custom configuration

Use custom YAML for multiple targets or other service settings. This example uses research-cluster.yaml:

extends: default
service:
  host: 127.0.0.1
  token: ${AXONX_SERVICE_TOKEN}
targets:
  - address: http://research.example:1024
    token: ${AXONX_REMOTE_RESEARCH_TOKEN}

export AXONX_SERVICE_TOKEN='<local service token>'
export AXONX_REMOTE_RESEARCH_TOKEN='<target service token>'
axonx start --config research-cluster.yaml

After restarting, select the target in Studio's machine entry. The remote token remains in server configuration; the browser does not need to store it directly.

Addresses are normalized, and targets does not allow duplicate addresses. Forwarding fails if the target is unconfigured; selectable UI targets should match local configuration. Restart the current service after configuration changes.

Connectivity and resources

axonx list_machines
axonx machine_status --target 'http://research.example:1024'

list_machines asks the current service to check its targets. A direct CLI query of the target's machine_status returns that target's resource information.

CPU, memory, and GPU fields are readings taken at query time. When GPU detection is unavailable, inspect the returned fields rather than concluding the machine definitely has no GPU. These fields provide no resource reservation, GPU binding, or automatic machine selection.

Studio's Machine resources page displays the same kinds of returned values as CPU, memory, and GPU cards. The screenshot below shows the English resource area with machine addresses removed; readings and device counts describe the example machine at capture time, not AxonX deployment requirements.

Remote files and plugins

Locally installed plugins do not automatically appear remotely. To install on the target, use:

axonx plugin list --target 'http://research.example:1024'
axonx plugin install ./plugins/a158 --target 'http://research.example:1024'

After installation, restart the target service as indicated by restart_required, then query Task definitions. Remote workers run code in that environment, and source_tasks only locates directories in the target workspace.

To reuse local upstream artifacts, first transfer the required task snapshots or copy data according to your deployment method. Raw data, Agent sessions, and model environments do not migrate with remote calls.

Common failures

Symptom	Assessment and action
Connection refused	Check target process, listening host/port, and network entry
401	For direct calls, check target token; for Studio, check both local and targets credentials
Target unconfigured	Add the normalized address to local targets and restart
Task registered name missing	Check target plugin installation and restart, rather than only the local environment
Schema or response fields differ	Compare service and plugin versions on both sides
Target task has no upstream files	Confirm data and Task directories were transferred to the target

Authentication · Plugin management · Task synchronization · Machine API

Source: targets model, Remote client, Job routing.