VXO is a file viewer for macOS. It opens documents, spreadsheets, code, logs of any size, archives and images in milliseconds, keeps them current as they change on disk, and never modifies a file or runs anything inside one.
This page is written for people and for AI agents alike. The same text is at /docs.md as plain Markdown, and /llms.txt lists every resource.
- Version: 0.5.0 · macOS 12 or later · Apple silicon
- Free for personal use. Commercial use needs a license (pricing).
Install
One command
curl -fsSL https://vxo.fiftyseven.is/install.sh | sh
The script downloads VXO, checks its SHA-256, copies VXO.app to /Applications (or ~/Applications when /Applications is not writable), and links the vxo command into ~/.local/bin. Read it first if you like: /install.sh.
By hand
- Download VXO-0.5.0.zip and unzip it.
- Drag
VXO.appto Applications and open it once. - This build is not notarized by Apple yet. macOS will say it cannot check VXO: open System Settings, Privacy & Security, and click Open Anyway. Or, in Terminal:
xattr -dr com.apple.quarantine /Applications/VXO.app. - Optional, for the
vxocommand:ln -s /Applications/VXO.app/Contents/MacOS/vxo-cli ~/.local/bin/vxo.
From source
With Rust installed from rustup.rs: make install puts VXO in Applications and vxo in ~/.local/bin. make default makes VXO the default app for every format it reads.
Open files
- Double-click a file in Finder (after
make default, or Open With > VXO), or drop files on a VXO window. - From Terminal,
vxo FILEopens the file as a new tab in the VXO window you already have, or starts VXO. It returns at once. - A folder opens with a sidebar. Arrow keys in the sidebar preview each file; Enter opens it.
- Opening a file that already has a tab switches to that tab.
- VXO keeps running when you close its last window, like Preview, so the next open is instant. Quit with ⌘Q; ⌥⌘Q quits and brings your windows back next time.
Pipe output into VXO
Anything a command prints can stream into a VXO tab:
kubectl logs -f api | vxo npm test 2>&1 | vxo git log -p | vxo curl -s https://api.example.com/items | vxo
The tab opens as soon as the first bytes arrive and follows the end while the command runs. Output that starts with { or [ is shown as JSON, and a diff as a diff, with colour. vxo - reads stdin explicitly. The stream is kept in $TMPDIR/vxo-stdin/ and removed after a day. Ctrl-C stops the stream; the tab keeps what arrived.
Command line
| Command | What it does |
|---|---|
vxo FILE... | Open each file as a tab in the front window (starts VXO if needed) |
vxo --new FILE | Open in a new window |
vxo | A new window on the current folder |
CMD | vxo, vxo - | Stream stdin into a tab |
vxo --serve [--port N] PATH | Headless: print VXO ready URL and serve the full viewer to any browser on this Mac |
vxo --report [DAYS] | Summarise the local usage log (default 30 days) |
vxo --version, vxo --help | Version, usage |
--serve binds to 127.0.0.1 only, and the URL carries a random token that every request must present.
Keys
| Key | Action |
|---|---|
| ⇧⌘O | Open Quickly: fuzzy search under the folder, recent files first |
| ⌘O | Open panel |
[ ] | Previous, next file in the folder |
| ⌘T, ⌘W, ⇧⌘T | New tab, close tab, reopen the closed tab |
| ⌃⇥, ⇧⌘] ⇧⌘[ | Next, previous tab |
⌘F or /, then ⌘G or n | Find as you type, then next |
⌘L or : | Go to line |
| ⇧⌘L, ⌥Z | Outline, wrap long lines |
| ⌘C | Copy the selection; cells as TSV; an image as an image |
| ⌘P | |
| ⇧⌘E | Extract an archive with Archive Utility |
| ⌥⌘R, ⌥⌘C | Show in Finder, copy the path |
| ⌘R | Reload from disk |
j k, d u, space, g G | Scroll, half page, page, top, bottom |
x | Any file as hex |
t | Next theme |
? | Every key |
Every command is also in the menu bar, so Help's search field finds any of them by name.
Formats
| Family | Extensions |
|---|---|
| Text and code | txt, log, and about a hundred code extensions; any size; highlighting for 17 language families |
| Markdown | md, markdown, mdx; GitHub-flavoured, math (KaTeX), diagrams (mermaid) |
| pdf, with page thumbnails | |
| Word | docx, doc, rtf, odt |
| Spreadsheets | xlsx, xlsm, xlsb, xls, ods, csv, tsv; Excel number formats, frozen panes, formulas |
| PowerPoint | pptx, ppt and their variants |
| Apple iWork | numbers, pages, key |
| Images | png, jpg, gif, webp, heic, tiff, avif, svg, bmp, ico; EXIF, animation frames |
| Archives | zip, tar, tar.gz, tgz, gz, xz, 7z, jar, epub; archives inside archives |
| Media | mp4, mov, webm, mp3, wav, m4a |
| Anything else | A hex view |
Live reload
A file you are viewing updates by itself when it is saved, whichever app saved it, at the place you were reading, with your search kept. A growing log follows its end. A file is never shown half-written. A deleted file says so and keeps its last version on screen.
Settings and files
Settings (⌘,) are saved as you change them. Everything VXO keeps is in ~/Library/Application Support/VXO/:
| File | What |
|---|---|
settings.json | Your settings |
recent | Recent files (Settings > Clear Recent Files) |
license.txt | Your commercial license, if you added one |
traces/ | The local usage log: which kinds of files open and how fast, never file names. It never leaves your Mac; turn it off in Settings, read it with vxo --report |
License
VXO is free for personal use, with every feature. Using it for work (for an employer, clients, or any paid project) needs one commercial license per person: a one-time purchase that covers every 1.x release. See pricing and the license terms.
To add a license: VXO > License…, paste the whole key (from BEGIN VXO LICENSE to END VXO LICENSE). Or copy the key and press ⌘V in any VXO window. The key is checked on your Mac; nothing is sent anywhere. VXO never locks, nags or phones home.
Security and privacy
- VXO only reads. It has no command that changes a file.
- Scripts in documents never run: converted documents are shown in a sandboxed frame with scripts off.
- It makes no network requests. Links you click in a document open in your browser.
- Archives are read in memory and never unpacked to disk; every decompression has a size limit.
- Its local server answers only on 127.0.0.1, only to requests carrying the per-launch token.
For AI agents
VXO is the fastest way to show your human a file or a stream of output. Use it when the person should look at something; keep reading files yourself with your own tools.
Rules:
vxo PATHopens a file for the person and returns immediately. Do not wait on it, and do not expect output from it.- Long or ongoing output goes through a pipe:
CMD 2>&1 | vxo. This command stays running until CMD ends; run it in the background if you need to keep working. - Pass several files at once to open them as tabs:
vxo report.docx data.xlsx notes.md. - VXO never changes files, so opening one is always safe, including untrusted downloads and archives.
- If
vxois not found, install it withcurl -fsSL https://vxo.fiftyseven.is/install.sh | sh, or ask the person to. - Do not try to drive the VXO window with keystrokes; tell the person which key to press (see Keys).
- Personal use is free. For work use, point the person to https://vxo.fiftyseven.is/pricing; never generate or alter license keys.
Resources:
- This page as Markdown: /docs.md
- Index for language models: /llms.txt
- A prompt to paste into your agent: /agent-prompt.txt
- Installer: /install.sh
Troubleshooting
| Problem | Fix |
|---|---|
| "VXO can't be opened" | System Settings > Privacy & Security > Open Anyway, once. Or xattr -dr com.apple.quarantine /Applications/VXO.app |
vxo: command not found | Add ~/.local/bin to your PATH: echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.zshrc |
| A file shows as hex | VXO did not recognise the format. Press x to toggle; tell us the extension |
| "Password-protected" | VXO does not open encrypted documents |
| A pipe opened the folder instead | The command ended without printing anything. Errors often go to stderr: add 2>&1 before the pipe |
| VXO still running after closing the window | By design, for instant opens. ⌘Q quits |