Which Backend Kinds Does orx Support? A Complete Guide to OpenResearch Compute Backends

The orx CLI supports nine distinct backend kinds—hf_job, k8s_job, modal_job, slurm_job, ssh_job, ray_job, openresearch_job, local_job, and tinker_job—each defined in the BackendDescriptor.kind field in src/jobs/mod.rs and implemented in the alphaXiv/OpenResearch repository.

The orx command-line interface enables researchers to launch and supervise machine learning jobs across heterogeneous compute environments, from local workstations to cloud sandboxes. Understanding the available orx backend kinds is essential for configuring runs to target specific infrastructure, whether you are submitting to a Slurm cluster, a Kubernetes deployment, or a managed OpenResearch sandbox.

The Nine Backend Kinds in OpenResearch

All valid backend descriptors use a kind string that ends with the suffix _job. The central definition resides in src/jobs/mod.rs (lines 52-54), where the BackendDescriptor struct encodes the compute target. The following table enumerates each supported orx backend kind, its corresponding platform, and the implementation module:

Backend Kind	Compute Target	Primary Source File
hf_job	Hugging Face job (namespace + job ID)	src/local/hf.rs
k8s_job	Kubernetes job (namespace + job name, optional context)	src/local/k8s.rs
modal_job	Modal sandbox (app namespace + sandbox ID)	src/local/modal.rs
slurm_job	Slurm cluster (login-node host + SLURM job ID)	src/local/slurm.rs
ssh_job	Direct SSH execution (host + remote run directory)	src/local/ssh.rs
ray_job	Ray Jobs (address + submission ID)	src/local/ray.rs
openresearch_job	OpenResearch managed sandbox (org + sandbox ID)	src/local/openresearch.rs
local_job	Local process controller (run directory)	src/local/localrun.rs
tinker_job	Tinker controller (run directory)	src/local/localrun.rs

How BackendDescriptor Validates orx Backend Kinds

The BackendDescriptor struct serves as the unified configuration format across all compute targets. Defined in src/jobs/mod.rs at lines 52-54, this struct contains the kind field that determines which underlying module handles job execution.

Each backend kind has a corresponding typed accessor method implemented in the same file (lines 106-190). These helper methods—including hf_ref(), k8s_ref(), modal_ref(), slurm_ref(), ssh_ref(), ray_ref(), openresearch_ref(), local_ref(), and tinker_ref()—validate the kind field and extract the specific parameters required for that backend type. If you invoke a method on an incompatible descriptor (for example, calling k8s_ref() on an hf_job), the method returns an error with the message "Unsupported backend kind".

Creating Backend Descriptors in Rust

When programmatically interacting with the OpenResearch API, you construct BackendDescriptor instances to specify your compute target. Below are practical examples demonstrating how to instantiate different orx backend kinds:

use serde_json::json;
use crate::jobs::BackendDescriptor;

// 1. Hugging Face job descriptor
let hf_desc = BackendDescriptor {
    kind: "hf_job".to_string(),
    namespace: Some("my_hf_org".into()),
    job_id: Some("12345".into()),
    ..Default::default()
};
println!("HF JSON: {}", hf_desc.to_json());

// 2. Kubernetes job descriptor
let k8s_desc = BackendDescriptor {
    kind: "k8s_job".to_string(),
    namespace: Some("default".into()),
    job_id: Some("my-pod".into()),
    context: Some("minikube".into()),
    ..Default::default()
};
println!("K8s JSON: {}", k8s_desc.to_json());

// 3. OpenResearch sandbox descriptor
let or_desc = BackendDescriptor {
    kind: "openresearch_job".to_string(),
    namespace: Some("my_org".into()),
    job_id: Some("sandbox_01".into()),
    flavor: Some("h100_sxm:2".into()),
    ..Default::default()
};
println!("OpenResearch JSON: {}", or_desc.to_json());

// 4. Parse a descriptor received from a supervisor
let json_str = r#"{"kind":"ssh_job","namespace":"box1","jobId":".orx/runs/r1"}"#;
let parsed = BackendDescriptor::parse(json_str).expect("valid descriptor");
assert_eq!(parsed.kind, "ssh_job");
assert_eq!(parsed.ssh_ref().unwrap(), ("box1", ".orx/runs/r1"));

Command Dispatch: How orx Uses Backend Kinds

The orx CLI utilities orx up and orx supervise dynamically route execution based on the kind field stored in a run's backend_json column. This dispatch logic appears in two critical locations:

• src/commands/supervise.rs (lines 73-96): Parses the descriptor and dispatches to the appropriate backend supervisor implementation based on the kind value.
• src/commands/up.rs (lines 2074-2077): Converts a run into a ComputeBackend by inspecting the descriptor's kind field and instantiating the correct local handler.

When you execute orx up with a specific backend configuration, the CLI deserializes the JSON descriptor, validates that the kind field matches one of the nine supported orx backend kinds, and then delegates to the corresponding module in src/local/ to manage the job lifecycle.

Summary

• Nine backend kinds are supported: hf_job, k8s_job, modal_job, slurm_job, ssh_job, ray_job, openresearch_job, local_job, and tinker_job.
• The BackendDescriptor struct in src/jobs/mod.rs (lines 52-54) defines the unified schema for all backends.
• Typed accessor methods in src/jobs/mod.rs (lines 106-190) validate kind and extract backend-specific parameters.
• The orx commands dispatch to implementation modules in src/local/ based on the kind field parsed from backend_json.
• All valid kind strings must end with the _job suffix as implemented in the alphaXiv/OpenResearch source code.

Frequently Asked Questions

What are the nine orx backend kinds supported by OpenResearch?

The nine supported kinds are hf_job (Hugging Face), k8s_job (Kubernetes), modal_job (Modal), slurm_job (Slurm), ssh_job (SSH), ray_job (Ray), openresearch_job (OpenResearch sandbox), local_job (local process), and tinker_job (Tinker controller). Each kind maps to a specific implementation file in src/local/.

How does orx validate which backend kind is being used?

According to the source code in src/jobs/mod.rs (lines 106-190), orx uses typed accessor methods like hf_ref(), k8s_ref(), and ssh_ref() on the BackendDescriptor struct. These methods check the kind field and return an error if the descriptor does not match the expected backend type.

Can I use multiple backend kinds in a single orx run?

No, each run is associated with exactly one backend_json entry containing a single kind value. The dispatch logic in src/commands/up.rs and src/commands/supervise.rs routes the entire run to one specific backend implementation based on that solitary kind field.

What happens if I specify an unsupported backend kind?

If you provide a kind string that does not match one of the nine recognized variants, the accessor methods in src/jobs/mod.rs will return an error stating "Unsupported backend kind", and the CLI command will fail before attempting to launch the job.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}