Daniel Kim
af8eed1724
* orx up remote banner: make the SSH commands the readable part The remote-access banner dimmed the very things you need to read and copy: the whole `ssh -N -L …` command was faint gray, and the `<ssh-alias>` placeholder in both commands was dimmed too — so the prose asides and the commands were nearly the same weight, and the one line you'd paste was the hardest to see. Invert the emphasis. Both commands are now bold with a `$` prompt so they read as "type this", the `<ssh-alias>` fill-in-the-blank is cyan (legible, obviously a placeholder) instead of dimmed, and only the prose (intro, the alias note, the trailing `# then open …` comment) is dim. Reworded the intro/option headings so the two paths scan as 1) and 2). Plain-text output (pipes/CI/NO_COLOR) is unchanged in spirit and still carries no escape codes. * orx up remote banner: adapt to boxes with no ~/.ssh/config alias The banner assumed a `~/.ssh/config` alias existed and told the user to type `<ssh-alias>`. On a fresh RunPod / openresearch dev node you connect with a raw `root@<ip> -p <port>` and have no alias at all, so the primary instruction was a dead end. Make the connection target adaptive: - Anchor on `<user@host>` — the one thing every reader has, alias or not — with a concrete example, and say plainly no config alias is needed. - When `SSH_CONNECTION` gives a usable *public* server IP, splice it straight into both commands so they're nearly copy-paste. - Custom SSH ports can't be recovered here (`SSH_CONNECTION` carries sshd's listen port, not the client-dialed one — e.g. RunPod maps :38455 onto sshd :22), and `orx up --remote` has no `-p` flag. So the `[-p PORT]` slot goes only on the manual `ssh` line (which accepts it), and a caveat tells the reader to use option 2 on a non-default port. Tests cover both branches (placeholder vs inlined public IP) and assert the port slot never leaks onto the `orx up --remote` line. * up --remote: security-aware host-key policy + IPv6/port hardening Addresses multi-agent review of the custom-port support: - HostKeyPolicy enum (jobs/ssh.rs) centralizes host-key handling behind SshTarget::host_port, so the '-p'/'-o' opt vector and its rationale live in one place. openresearch_ssh_target now uses it (Ephemeral), replacing its inline vec — behavior byte-identical (guarded by an exact-vector test). - Don't silently disable host-key verification for a user-typed HOSTNAME with a port: a name may be one the user has pinned. Only a raw IP (the freshly-provisioned-box signal) gets accept-new TOFU against the real known_hosts; a hostname gets '-p' only (UserConfig). Neither uses /dev/null — that stays reserved for provider-managed boxes. - Fix raw-IPv6 mis-parse: '2001:db8::5' was split into host + '-p 5'. And fix 'user@[::1]:2222' silently dropping its port (the bracket check now looks past the user@ prefix). Reject port 0. - Be honest in the banner/help/errors: 'orx up --remote' reconstructs only user@host + port, so a custom key / jump host must come from ~/.ssh/config; the reachability error now hints at ssh-keygen -R for a reused-IP key clash. Tests cover the policy dispatch, IPv6 (raw/bracketed/user-prefixed), port 0, >u16, host_is_ip_literal forms, and the exact Ephemeral opt vector. * chore: bump version to 0.1.58 Ships the orx up --remote custom-port support + readable/honest SSH banner.
OpenResearch CLI (orx)
A small command-line interface for OpenResearch. Log in via the browser, then query your projects from the terminal.
Requirements
-
Rust (stable) with Cargo. Install via rustup:
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
Build & run
# Build (debug):
cargo build
# Run during development:
cargo run -- login
cargo run -- projects
# Build an optimized release binary at target/release/orx:
cargo build --release
./target/release/orx login
# Or install `orx` onto your PATH (~/.cargo/bin):
cargo install --path .
orx login
orx projects
Run the tests with cargo test.
Commands
| Command | Description |
|---|---|
orx login [--api-url <url>] |
Opens your browser, authenticates, and stores a personal access token. |
orx logout |
Removes the stored token. |
orx install-skills [--agent claude|codex|opencode|cursor|all] |
Installs the orx skill shim into local coding agents (Claude Code, Codex, OpenCode, Cursor) so they auto-discover the CLI (orx login also offers this). |
orx projects [--all] |
Lists your projects, grouped by organization. --all includes archived. |
orx compute [--gpu <id>] [--count <n>] [--provider <name>] | --cpu] |
Lists the GPU compute catalog across all providers and regions, or CPU-only offers with --cpu, sorted by price. |
orx instance create <orgId> (--gpu <id> [--count <n>] [--disk <gb>] [--provider <name>] | --cpu <flavor> [--vcpus <n>]) |
Spins up a standalone instance in an organization (not tied to an experiment), like the dashboard's "Spin up". |
orx exp status <expId> |
Shows an experiment's status, branch, parent, run command, and latest run, plus a local git diff recipe for what the run changed. |
orx exp cmd <expId> [--set <command>] |
Views or sets the experiment's run command. |
orx exp run <expId> (--gpu <id> [--count <n>] [--disk <gb>] [--provider <name>] | --cpu <flavor> [--vcpus <n>] | --sandbox <id>) |
Launches a run on new GPU, new CPU-only, or existing compute. |
orx exp cancel <expId> |
Cancels the in-flight run. |
orx lit "<query>" [--limit <n>] [--json] |
Full-text search alphaXiv's paper corpus (no login required). |
orx paper <id|url> [--full] |
Fetch a paper's machine-readable report, or its full text with --full. |
orx version [--check] [--json] |
Prints the CLI version; --check compares it to the latest release. |
orx update [--dry-run] [--force] |
Updates orx by re-running the release installer (installer installs only). |
Updating
orx update only manages binaries installed by the release installer script
(it checks the cargo-dist install receipt at
${XDG_CONFIG_HOME:-~/.config}/openresearch-cli/). If you installed with
cargo install, update the same way instead. In interactive terminals orx
also checks for new releases in the background at most once a day and prints
a one-line notice to stderr; set ORX_NO_UPDATE_CHECK=1 (or
OPENRESEARCH_CLI_DISABLE_UPDATE=1) to turn that off. Agents, scripts, pipes,
and CI never see the notice.
Configuration
-
API URL resolves from
--api-url→OPENRESEARCH_API_URL→ the built-in default (http://localhost:4000). Point it at the production API host for real use:export OPENRESEARCH_API_URL=https://api.openresearch.sh -
Credentials are stored at
${XDG_CONFIG_HOME:-~/.config}/openresearch/credentials.json(mode0600).
How login works
orx login starts a temporary HTTP listener on a random 127.0.0.1 port, opens
{api}/auth/cli/login in your browser, and waits for the API to redirect back
with a freshly minted personal access token after you authenticate. The token is
sent as Authorization: Bearer … on every subsequent request.
Usage analytics
orx sends anonymous usage analytics to help us understand which features
are used and prioritize accordingly. This is opt-out; the orx up dashboard
surfaces the choice as a step in first-run onboarding.
What is collected — the command name that was run, a random per-install UUID,
the CLI version, your OS/architecture, whether the run is in CI, and a small set
of coarse labels for key events (e.g. an experiment was created or a run was
launched, and a broad compute target like modal/k8s/local).
What is never collected — no code, prompt text, file contents, file paths, project/experiment ids or names, repo names, tokens, emails, or any other personal or identifying data. The install UUID is random and not tied to your account.
How to opt out — either:
orx telemetry off # persistent, per-machine
orx telemetry status # see current state + the anonymous install id
orx <cmd> --no-telemetry # per-run
Events are sent fire-and-forget on a background task with a short timeout, so
they never meaningfully block or fail a command (at most a brief flush window on
exit). Every event carries a ci property, so automated runs can be filtered in
analytics without being dropped up front.