Where Are orx Run Logs Stored? Log File Paths in OpenResearch

orx run logs are stored as plain-text .log files in a run-logs subdirectory within the OpenResearch data directory, with file paths generated by the log_path helper function in src/store.rs.

When using the orx CLI from the alphaXiv/OpenResearch repository to execute research runs, understanding where orx run logs are stored is essential for debugging and audit trails. The application writes terminal output to append-only log files using a deterministic path resolution system that prioritizes environment variables and user configuration.

Log File Location and Path Construction

The storage location for orx run logs is determined by the log_path function defined in src/store.rs (lines 89-96). This helper constructs a PathBuf by combining the base data directory with a sanitized run identifier.

The log_path Implementation

According to the source code in src/store.rs, the function sanitizes the run ID to prevent directory traversal attacks before constructing the final path:

pub fn log_path(run_id: &str) -> PathBuf {
    // Sanitize the id so malformed local data cannot escape the log directory.
    let safe: String = run_id
        .chars()
        .filter(|c| c.is_ascii_alphanumeric() || *c == '-' || *c == '_')
        .collect();
    data_dir().join("run-logs").join(format!("{safe}.log"))
}

This implementation ensures that each run ID translates to exactly one log file named {run-id}.log containing only alphanumeric characters, hyphens, and underscores.

Directory Structure

The logs reside in a run-logs subdirectory inside the OpenResearch data folder. For a run with ID r123, the full path typically resolves to:

$HOME/.local/share/openresearch/run-logs/r123.log

Data Directory Resolution Priority

The base data directory—used by log_path as the starting point—is resolved by the data_dir() function in src/store.rs (lines 20-37) following a strict precedence order:

• $ORX_DATA_DIR – Environment variable override
• User settings – Path stored in settings.json under the config source
• $XDG_DATA_HOME/openresearch – XDG Base Directory specification
• ~/.local/share/openresearch – Default fallback location

If you set ORX_DATA_DIR=/my/custom/path, logs for run r456 would be stored at /my/custom/path/run-logs/r456.log.

Accessing orx Run Logs

You can retrieve these logs either through the CLI interface or programmatically via the Rust API.

Using the orx logs Command

The CLI command orx logs <run-id> reads the stored log file directly. This command is implemented in src/commands/logs.rs and utilizes the log_path function internally via src/plane/local_plane.rs (lines 55-60) to locate the correct file.

Programmatic Access

To access log paths in your own Rust code using the OpenResearch crate:

use crate::store::log_path;

// Retrieve the filesystem path for a specific run
let run_id = "r42";
let path = log_path(run_id);
println!("Run log is stored at: {}", path.display());
// Output: Run log is stored at: /home/user/.local/share/openresearch/run-logs/r42.log

For reading log contents, open the file using standard Rust I/O:

use std::fs::File;
use std::io::{BufRead, BufReader};

fn tail_log(run_id: &str) -> std::io::Result<()> {
    let path = log_path(run_id);
    let file = File::open(path)?;
    let reader = BufReader::new(file);
    
    for line in reader.lines() {
        println!("{}", line?);
    }
    Ok(())
}

Summary

• orx run logs are stored as append-only plain-text files in {data_dir}/run-logs/{run-id}.log
• The log_path function in src/store.rs sanitizes run IDs to allow only alphanumeric characters, hyphens, and underscores
• Data directory resolution follows a four-tier priority: $ORX_DATA_DIR, settings.json, $XDG_DATA_HOME/openresearch, and ~/.local/share/openresearch
• Access logs via orx logs <run-id> or programmatically using the log_path helper

Frequently Asked Questions

What is the default path for orx run logs?

By default, orx run logs are stored in ~/.local/share/openresearch/run-logs/ on Linux systems, or the equivalent path following the XDG Base Directory specification. Each run gets its own file named {run-id}.log where the run ID has been sanitized to remove special characters.

Can I change where orx stores run logs?

Yes. Set the ORX_DATA_DIR environment variable to your preferred base directory, and orx will create a run-logs subdirectory there instead. Alternatively, configure the data directory in your settings.json file, which takes precedence over the XDG defaults but yields to the environment variable.

How does orx handle special characters in run IDs?

The log_path function filters the run ID to retain only ASCII alphanumeric characters, hyphens, and underscores. This sanitization prevents path traversal attacks and ensures malformed IDs cannot escape the designated log directory. Characters outside this set are simply removed from the filename.

Are orx run logs deleted automatically?

The source analysis does not indicate automatic deletion behavior. The logs are append-only plain-text files stored persistently in the data directory until manually removed or cleaned by external tools. The orx CLI provides read access via orx logs <run-id> but does not implement automatic log rotation according to the current implementation in src/commands/logs.rs.

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