# OpenResearch CLI (`orx`) Internal Structure: A Deep Dive into the Rust Architecture

> Explore the internal structure of the OpenResearch CLI orx. Discover its Rust architecture, layered design, and separation of local and remote operations for efficient workflow management.

- Repository: [alphaXiv/OpenResearch](https://github.com/alphaXiv/OpenResearch)
- Tags: deep-dive
- Published: 2026-09-13

---

**The OpenResearch CLI (`orx`) is a single-binary Rust application organized into distinct layers—entry point, command routing, local mode, remote clients, and job runners—with strict separation between offline-local functionality and remote API operations.**

The `orx` command-line tool from the **alphaXiv/OpenResearch** repository follows a modular architecture that separates concerns between CLI parsing, local computation, and remote API communication. Understanding how the OpenResearch CLI (`orx`) structure is organized helps developers extend compute backends, debug agent integrations, or contribute to the core Rust codebase.

## Entry Point and Command Dispatch ([`src/main.rs`](https://github.com/alphaXiv/OpenResearch/blob/main/src/main.rs))

The application starts in [`src/main.rs`](https://github.com/alphaXiv/OpenResearch/blob/main/src/main.rs), which defines the top-level **clap**-driven argument structure. This file contains the `Cli` struct and the `Command` enum that enumerates every user-visible sub-command.

The entry point sets up the async runtime, parses arguments, and dispatches to the appropriate handler through a match expression:

```rust
match cli.command {
    Some(Command::Login(args)) => login::run(args).await,
    // …
}

```

*(source: [`src/main.rs`](https://github.com/alphaXiv/OpenResearch/blob/main/src/main.rs) lines 63-66)*

Each variant of the `Command` enum maps directly to a module under `src/commands/`. The [`main.rs`](https://github.com/alphaXiv/OpenResearch/blob/main/main.rs) file orchestrates the initial setup but delegates all business logic to specialized command modules.

## Command Routing Layer (`src/commands/`)

The [`src/commands/mod.rs`](https://github.com/alphaXiv/OpenResearch/blob/main/src/commands/mod.rs) file aggregates all command implementations and establishes the `run` convention. Every sub-command module (such as `login`, `projects`, or `up`) exposes an async `run` function that receives the corresponding argument struct and returns `anyhow::Result<()>`.

This pattern enforces consistent error handling across the CLI. Error bubbles propagate naturally through the async stack, allowing network I/O and compute operations to fail gracefully without blocking the runtime.

## Local Mode Architecture (`src/local/`)

The **local mode** represents the core offline functionality of the OpenResearch CLI (`orx`) structure. The [`src/local/mod.rs`](https://github.com/alphaXiv/OpenResearch/blob/main/src/local/mod.rs) module handles all work that stays completely on the local machine—including the SQLite store, local Git branches, and launching compute backends—with **no references** to the remote API client.

This layer defines the canonical list of compute targets through constants `BACKENDS`, `FLAVORED_BACKENDS`, and `FLAVOR_REQUIRED_BACKENDS`. When executing `orx up`, the system resolves compute defaults using helper functions `apply_compute_default` and `resolve_compute_default`:

```rust
let (backend, flavor) = resolve_compute_default(...);
match backend.as_str() {
    "hf" => jobs::hf::run(flavor, …).await,
    "modal" => jobs::modal::run(flavor, …).await,
    // …
}

```

*(source: [`src/local/mod.rs`](https://github.com/alphaXiv/OpenResearch/blob/main/src/local/mod.rs) lines 84-100 and [`src/commands/up.rs`](https://github.com/alphaXiv/OpenResearch/blob/main/src/commands/up.rs))*

Sub-modules under `src/local/` include `projects`, `experiments`, `resolve`, `git`, `skills`, and compute-specific back-ends (`hf`, `modal`, `k8s`, `ssh`, `slurm`, `ray`, `openresearch`).

## Remote API and Configuration

When online functionality is required, the CLI uses [`src/client.rs`](https://github.com/alphaXiv/OpenResearch/blob/main/src/client.rs) (containing generated DTOs) and the `src/remote/` directory for low-level HTTP wrappers. This separation ensures that remote communication is isolated from local operations.

State persistence is handled by three key files:

- **[`src/config.rs`](https://github.com/alphaXiv/OpenResearch/blob/main/src/config.rs)** – Manages `~/.orx/config.toml` for user preferences and compute defaults
- **[`src/store.rs`](https://github.com/alphaXiv/OpenResearch/blob/main/src/store.rs)** – Provides SQLite abstraction for projects, experiments, and runs
- **[`src/workspace_state.rs`](https://github.com/alphaXiv/OpenResearch/blob/main/src/workspace_state.rs)** – Maintains in-memory representation of a running workspace

## Background Jobs and Compute Backends (`src/jobs/`)

The `src/jobs/` directory contains modular job runners for each supported compute backend. Each module (such as [`tinker.rs`](https://github.com/alphaXiv/OpenResearch/blob/main/tinker.rs), [`ssh.rs`](https://github.com/alphaXiv/OpenResearch/blob/main/ssh.rs), [`ray.rs`](https://github.com/alphaXiv/OpenResearch/blob/main/ray.rs), or [`modal.rs`](https://github.com/alphaXiv/OpenResearch/blob/main/modal.rs)) implements a concrete **backend** launch strategy.

Jobs implement a `run` method that spawns the appropriate process—whether a Docker container, SSH command, or cloud API call—and writes execution logs back to the SQLite store defined in [`src/store.rs`](https://github.com/alphaXiv/OpenResearch/blob/main/src/store.rs). This architecture makes adding new compute targets a matter of implementing a new job module.

## Agent Integration and Permission Gating (`src/local/harness/`)

The `src/local/harness/` directory bridges the OpenResearch CLI (`orx`) structure with external coding agents (Claude, Codex, OpenCode, Cursor). It contains the permission gate system that controls what agents are allowed to execute.

The hidden `plan-gate` and `mcp-gate` commands implement a server-side permission bridge. These read a JSON payload from stdin, evaluate whether the requested sub-command is read-only, and output an allow/deny decision:

```rust
let payload = read_stdin();
if readonly_verbs_are_real_commands(&payload.command) {
    println!("allow");
} else {
    println!("deny");
}

```

*(source: [`src/local/harness/plan_gate.rs`](https://github.com/alphaXiv/OpenResearch/blob/main/src/local/harness/plan_gate.rs))*

This gating mechanism ensures agents cannot perform destructive operations without explicit user approval.

## Supporting Systems

**Telemetry** – Anonymous usage statistics are handled by [`src/telemetry.rs`](https://github.com/alphaXiv/OpenResearch/blob/main/src/telemetry.rs) and the `Telemetry` command, respecting user opt-out preferences stored in [`src/config.rs`](https://github.com/alphaXiv/OpenResearch/blob/main/src/config.rs).

**Updates** – Self-update logic for the CLI binary and macOS app bundle resides in `src/updates/`, exposed through the `Update` and `InstallCli` commands.

## Summary

- The **entry point** in [`src/main.rs`](https://github.com/alphaXiv/OpenResearch/blob/main/src/main.rs) uses **clap** to parse arguments and dispatch to async command handlers.
- **Command routing** follows a strict convention in [`src/commands/mod.rs`](https://github.com/alphaXiv/OpenResearch/blob/main/src/commands/mod.rs), with each sub-command implementing an async `run` function returning `anyhow::Result`.
- **Local mode** (`src/local/`) operates entirely offline using [`src/store.rs`](https://github.com/alphaXiv/OpenResearch/blob/main/src/store.rs) for SQLite persistence and [`src/local/mod.rs`](https://github.com/alphaXiv/OpenResearch/blob/main/src/local/mod.rs) for backend resolution.
- **Remote functionality** is isolated in [`src/client.rs`](https://github.com/alphaXiv/OpenResearch/blob/main/src/client.rs) and `src/remote/`, keeping the local mode free of API dependencies.
- **Job runners** in `src/jobs/` provide backend-agnostic compute dispatch through modular implementations.
- **Agent harness** (`src/local/harness/`) enforces security through the `plan-gate` permission system.

## Frequently Asked Questions

### What file handles the CLI argument parsing in the OpenResearch CLI?

The **[`src/main.rs`](https://github.com/alphaXiv/OpenResearch/blob/main/src/main.rs)** file defines the `Cli` struct using the **clap** derive macro, along with the `Command` enum that enumerates all available sub-commands. This file contains the top-level match statement that dispatches parsed arguments to the appropriate command handler.

### How does `orx` handle offline operations without API calls?

The **`src/local/`** module contains **no references** to [`src/client.rs`](https://github.com/alphaXiv/OpenResearch/blob/main/src/client.rs), ensuring complete isolation from remote APIs. It operates against the local SQLite store in **[`src/store.rs`](https://github.com/alphaXiv/OpenResearch/blob/main/src/store.rs)** and the filesystem, making commands like `orx up` fully functional without internet connectivity.

### What is the purpose of the `plan-gate` command in the alphaXiv/OpenResearch codebase?

The **`plan-gate`** command is a hidden utility in **[`src/local/harness/plan_gate.rs`](https://github.com/alphaXiv/OpenResearch/blob/main/src/local/harness/plan_gate.rs)** that implements a permission bridge for coding agents. It reads a JSON payload from stdin, validates whether the requested operation is read-only, and prints "allow" or "deny" to stdout, preventing agents from executing destructive commands without authorization.

### Which module manages the SQLite database for local projects?

The **[`src/store.rs`](https://github.com/alphaXiv/OpenResearch/blob/main/src/store.rs)** module provides the primary SQLite abstraction layer, handling persistence for projects, experiments, and run histories. This module is used exclusively by the local mode architecture in **`src/local/`** to maintain state without requiring remote API calls.