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

> Discover where orx run logs are stored in alphaXiv OpenResearch. Find log file paths generated by the log path helper function in src/store.rs.

- Repository: [alphaXiv/OpenResearch](https://github.com/alphaXiv/OpenResearch)
- Tags: how-to-guide
- Published: 2026-09-13

---

**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`](https://github.com/alphaXiv/OpenResearch/blob/main/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`](https://github.com/alphaXiv/OpenResearch/blob/main/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`](https://github.com/alphaXiv/OpenResearch/blob/main/src/store.rs), the function sanitizes the run ID to prevent directory traversal attacks before constructing the final path:

```rust
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`](https://github.com/alphaXiv/OpenResearch/blob/main/src/store.rs) (lines 20-37) following a strict precedence order:

- **`$ORX_DATA_DIR`** – Environment variable override
- **User settings** – Path stored in [`settings.json`](https://github.com/alphaXiv/OpenResearch/blob/main/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`](https://github.com/alphaXiv/OpenResearch/blob/main/src/commands/logs.rs) and utilizes the `log_path` function internally via [`src/plane/local_plane.rs`](https://github.com/alphaXiv/OpenResearch/blob/main/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:

```rust
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:

```rust
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`](https://github.com/alphaXiv/OpenResearch/blob/main/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`](https://github.com/alphaXiv/OpenResearch/blob/main/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`](https://github.com/alphaXiv/OpenResearch/blob/main/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`](https://github.com/alphaXiv/OpenResearch/blob/main/src/commands/logs.rs).