FAQ: quick answers to common questions

[wilsonglasser]

Quick answers to the questions that come up most, including a few behaviors that are deliberate design decisions but easy to miss. If yours isn't here, ask in Q&A. Everything below describes the latest stable release.

中文用户：本页底部有中文板块，也可以直接用中文提问。

Vault, data & security

Where is my data stored?

Everything lives in a single encrypted SQLite vault at ~/.oryxis/vault.db (same path on Windows, under your user profile): hosts, keys, identities, snippets, settings, and session logs. Secrets (passwords, private keys) are encrypted per-field with a key derived from your master password (Argon2id + ChaCha20-Poly1305, per-field salt and nonce). There is no cloud account and nothing leaves your machine unless you explicitly enable sync.

Do I have to set a master password?

No. Out of the box the vault opens instantly with no password, so you can evaluate the app without friction. Enable a master password in Settings when you start storing real credentials; changing it later re-encrypts every secret with the new key. Once one is set you can also opt in to biometric unlock (Windows Hello / Touch ID / the Linux keyring) and an idle auto-lock that zeroizes the key and shows the lock screen while your live SSH sessions survive to the next unlock. As of 0.17 a session recording keeps recording under that lock: what arrives meanwhile is spooled to disk sealed under a key that lives in the process alone, and lands in the vault at unlock.

I forgot my master password. Can I recover the vault?

No, and that's by design. The master password is the encryption key's only source; there is no backdoor, reset, or recovery. The lock screen offers a Vault reset, which starts you over with an empty vault. Keep a portable export somewhere safe if you're worried about losing it.

How do I back up or move my data to another machine?

Two options:

• Portable export: export a password-protected .oryxis file and import it on the other side. You choose whether SSH private keys are included or only host configs. Import merges by UUID and keeps the newer record, so re-importing an old export won't clobber recent edits.
• Sync: opt-in and end-to-end encrypted, with five transports carrying the same sealed snapshot: peer-to-peer (QUIC, LAN discovery, optional self-hosted relay), an SFTP host, a plain folder (which covers OneDrive / Google Drive / Dropbox / iCloud through their own clients, plus network shares and Syncthing), a Git remote (the one that keeps history), or a WebDAV server (Nextcloud / ownCloud / Synology). No server ever sees plaintext, whichever you pick.

Does Oryxis phone home?

No telemetry, no analytics, no accounts. The only network calls the app makes on its own behalf are the update check against GitHub releases and plugin downloads you explicitly trigger.

What does Privacy Mode do?

A global toggle (with a per-host override) that masks hostnames, IPs and usernames on screen, for screen sharing and screenshots. It's display-only: the underlying session, logs and exports still carry the real data, so it's a presentation shield, not redaction at rest.

Connections, proxies & keys

How does authentication work?

By default Oryxis tries, in order: your configured key, a running SSH agent, the stored password, then keyboard-interactive. On Windows it discovers both the OpenSSH agent and PuTTY's Pageant (it finds the live Pageant pipe automatically). Agent forwarding is per-host opt-in. As of 0.12, servers that demand several factors in sequence (sshd AuthenticationMethods, Bitvise compound auth) are followed through the whole chain instead of stopping at the first accepted factor. As of 0.10, Oryxis also acts as an ssh-agent for other tools (git, VS Code Remote, WSL): your vault keys are served read-only and decrypted per signature, filtered by a per-key "Expose via agent" flag, and it can optionally accept keys pushed in by tools like KeePassXC (memory-only, swept on lock). Configured in Settings > SSH agent.

Will Oryxis use the key sitting in my ~/.ssh?

If you ask it to, per host (0.15). It is opt-in rather than automatic, because offering a credential you never named changes who you are to that server. The vault always wins: the disk only fills a slot your host left empty, and only for the auth methods that offer a key at all. A passphrase-protected file is reported as exactly that in the host editor instead of being silently skipped, which is what used to leave people watching ssh authenticate while Oryxis fell through to a password prompt with nothing on screen saying why.

How are host keys verified?

Trust-on-first-use: the first connection pins the server's key in the vault, and any later mismatch is flagged instead of silently accepted.

A host has both an inline proxy and a linked Proxy Identity. Which wins?

The Proxy Identity wins. And deleting a Proxy Identity never breaks the hosts that referenced it: they simply connect without a proxy (with a warning) rather than failing, so removing one shared proxy can't lock you out of your fleet.

How do proxies interact with jump-host chains?

Only the first hop dials through the proxy; every later hop already travels inside the SSH tunnel, so per-jump proxy settings beyond the first don't apply. A jump host behind a SOCKS/HTTP proxy "just works" on that first dial.

What are the rules for ~/.ssh/config import?

ProxyCommand maps directly. ProxyJump is resolved by alias in a second pass after all hosts get their IDs, so ordering in your config file doesn't matter. Anything that can't be resolved (an alias pointing at a host that wasn't imported) is recorded in the host's notes instead of failing the import; an import never dies halfway.

Which clients can I import sessions from?

OpenSSH ~/.ssh/config, PuTTY and KiTTY (a registry .reg export), WinSCP (.ini or registry), mRemoteNG (confCons.xml, including fully-encrypted files, which prompt for their password), MobaXterm (MobaXterm.ini bookmarks), Xshell / SecureCRT / FinalShell (point "Choose folder" at the sessions directory), Termius (its CSV export), and any CSV of hosts through header matching. One Import button detects the format from the file's content. Passwords come along where the storing scheme is reversible (WinSCP, mRemoteNG, CSV password columns) and land in the vault's encrypted columns; clients that encrypt with a per-install key (Xshell, SecureCRT, FinalShell, MobaXterm) import the host and say so in its notes instead of guessing.

Can I import passphrase-protected keys?

Yes. Encrypted keys (including PPK) are decrypted once at import time with their passphrase, and from then on the vault's master password protects them at rest.

Can the vault answer 2FA verification codes?

Yes. Give a host a TOTP secret (a bare base32 string or a full otpauth:// URI); it's encrypted like every other credential, and when the server's keyboard-interactive auth asks for a verification code, Oryxis computes the RFC 6238 code and answers automatically, once per attempt, falling back to the manual prompt if the server rejects it. This includes servers that take the password and the code as separate auth factors (RFC 4252 partial success): the chain continues and the stored secret answers the code round. If you'd rather store no password at all, the "Password prompt" auth method asks at every connection and never writes to the vault.

Does Oryxis speak anything besides SSH?

Yes. One per-host picker covers Telnet (full RFC option negotiation, an honest cleartext warning, and optional TLS for telnets), raw TCP (a bare line for console servers, opened in silence so no unasked-for negotiation reaches whatever device is on the far end), serial (COM / /dev/tty* with configurable line parameters), a local shell on your own machine, and a remote desktop host (RDP / VNC) that launches your OS-native client, optionally through an auto-provisioned SSH tunnel. ZMODEM transfers (sz / rz) are auto-detected over SSH, Telnet and serial alike. Quick connect speaks the same list: type telnet://, raw://, telnets://, or a bare /dev/ttyUSB0 or COM3, and the protocol is decided from what you wrote.

Can a session survive sleep and changing networks?

Yes, as of 0.15, by switching mosh on for a host. The shell rides out suspend, a change of Wi-Fi and a change of IP, and the interface says how long the link has been out of touch rather than showing a green dot over an outage. It is an option on an SSH host rather than a protocol of its own, because mosh-server does not exist until an SSH session starts it: the credentials, jump chain, proxy and host-key policy are the ones the SSH side already resolved. The host needs the mosh package and a reachable UDP port; nothing extra is installed on your machine, since the client is native Rust. A host reached through a jump chain is the one case that cannot work, because UDP does not travel down an SSH tunnel (upstream mosh has the same limit).

My mosh session has no Ubuntu welcome message. Is that broken?

No, and the rule is the server's rather than ours. Ubuntu prints that banner from two places. pam_motd runs inside sshd's own PAM stack and fires on every SSH login, which is why it is always there on an SSH tab. A mosh shell is started by mosh-server rather than by sshd, so that path never runs for it. What is left is /etc/profile.d/update-motd.sh, which any login shell runs, and which stamps ~/.motd_shown and then stays quiet for the rest of the day. So the first mosh session of the day carries a banner and the ones after it do not. Delete that stamp to see it again. Upstream mosh behaves identically, for the same reason.

Can I run remote GUI applications?

Yes, as of 0.11: X11 forwarding, per-host opt-in in the host editor (right under "Forward SSH Agent"), also picked up from ForwardX11 in your ~/.ssh/config. Your real X authority cookie never leaves your machine, the remote only ever sees a fake one that Oryxis mints per session and swaps back before any byte reaches your X server, so a shared server can't read a forwarded cookie and take over your desktop. This is trusted forwarding (OpenSSH's -Y); untrusted -X relies on the X SECURITY extension, which denies the pointer and keyboard grabs Java and Swing toolkits need, so the enterprise GUIs people actually forward would fail to start under it.

Linux and macOS (XQuartz) work out of the box. Windows has no native X server, so you need a third-party one running (VcXsrv, Xming or MobaXterm); with no DISPLAY set Oryxis targets the TCP endpoint those serve by default. Displays running with access control off (WSLg, VcXsrv -ac) are handled too.

Can I see a server's CPU and memory without installing anything?

Yes, as of 0.11. A Monitor tab in the terminal sidebar reads CPU, memory, swap, disk and network over the SSH connection you already have, so there is no agent to install or keep updated on the server. It also lists the host's listening ports and turns any of them into a local port forward in one click.

It is opt-in twice over: the whole feature sits behind a Features & Plugins toggle, and then per host, so no connection starts probing behind your back. "Enable for all hosts" flips it wholesale when you do want it everywhere. As of 0.17, Only hosts with a live session (Settings > Monitoring) keeps the dashboard to the machines a terminal tab is already logged in to, so it never opens a connection of its own.

Do I need a separate SFTP session to browse files?

Not anymore. Every SSH tab has a Files tab in its sidebar, a browser multiplexed over the same live connection that follows your shell's working directory as you cd. From there, one click promotes the tab into the full dual-pane SFTP manager at that directory, and back. Standalone SFTP tabs still exist for server-to-server copying between two different hosts.

As of 0.16 there is a third way, for people who would rather type than drag: an SFTP console with the sftp(1) command set (get, put, mget, reget, globs, Tab completion on both sides of the link, a command history), which opens as a pane of the session already in front of you and usually costs no extra handshake. Ctrl+Shift+S (Cmd+Shift+S on macOS) moves a tab between the shell, the console and the file manager. 0.17 completes the command set (df, ln, cp, chown, chgrp, lumask, the -r / -p / -f / -h flags) and shows owners by name in ls -l.

Can I get a session log as a plain file while the session runs?

As of 0.17, yes. Session recordings live in the vault, encrypted, and History exports them afterwards; Settings > Security & Privacy > Also write a plain text file adds a file that grows while the session runs, one per recording, in ~/.oryxis/session-logs/ or a folder you pick, for tailing from another window or handing to someone without the vault. Off by default. It is a mirror of the recording rather than a second capture: a host set never to record produces no file either, and the same secret redaction applies. The file is not encrypted, and its header says so.

Ctrl+click on a link asks me before opening it. Why?

Because a link in a remote pane is text the remote host chose, and an OSC 8 label can say anything about where it points. As of 0.17 a Ctrl+click on a remote pane shows the host that printed it and the full target before your browser opens; local shells open straight away, and Settings > Terminal turns the warning off. The one case that always asks is a link that would open a port here: a CLI login (aws sso login and every other OAuth client) prints a callback to 127.0.0.1 on the remote machine, and agreeing forwards that port over the session's existing SSH connection so the login finishes in your browser. The port is given back once the callback lands, or five minutes later if none does.

One pane of a split tab disconnected. What now?

As of 0.17 the pane keeps its scrollback and shows a card offering to restart it in place or close it, without touching its live siblings; Settings > Terminal > Split panes > When a pane's session ends picks what happens by default, and Reconnect (Ctrl+Shift+R) on a split tab restarts the focused pane only. The same page has Title bar on each pane (off by default): a bar per pane with its label, connection state, restart and close, which is also the handle for dragging a pane onto a sibling to swap places, onto a grid edge to move it, or onto another tab's chip to join that tab. Ctrl+Alt+P (or the pane menu) breaks a pane out into a tab of its own, session and all.

Can Oryxis ask before I close a tab with a live session, and bring my tabs back after a restart?

Both as of 0.17, both off by default. Settings > Terminal > Ask before closing a tab or the app with a live session gates the tab's X, Ctrl+W, "Close other tabs", the window close and the tray's Quit; Enter on that dialog no longer confirms, because a stray Enter on a popup nobody has read is the misclick with a different finger. Settings > Interface > Restore last session's tabs brings back the tabs that were open as placeholders that connect when selected, so a launch never dials on its own; pinned tabs come back either way, and the + popover and the tab strip's right-click menu list your five most recent hosts.

The host editor has no Save button. Where did it go?

Nowhere: closing the drawer IS the save, for a host that already exists. Press Esc, click the X, click away to another view, or focus a terminal tab, and the edit is written. Creating a NEW host still has the explicit Save / Connect pair, because a half-typed host must never enter the vault on its own.

This replaced an earlier revision that saved on a timer while you typed, which sounds friendlier and was not: the host list is sorted by label, so every mid-typing save re-sorted it under whatever was pointing into it, and a menu, a connect or a delete could act on the row that had just moved. One write per editing session removes that whole class instead of guarding each place it could bite. If a write ever fails, you get an error rather than silence.

Sync

Does sync share my passwords?

Not unless you ask it to. Password sync is a separate opt-in toggle, off by default; with it off, password fields are simply omitted from the wire. Everything that does sync is end-to-end encrypted (X25519 + XChaCha20-Poly1305) between your paired devices.

What syncs, and how are conflicts resolved?

Connections (Telnet / serial / remote-desktop hosts included), SSH keys, identities, proxy identities, groups, snippets, port forwarding rules and known hosts. Command history and session logs never sync, by design. Conflicts are last-write-wins per record. Deletes propagate as tombstones with a 30-day TTL, gated so a device that was offline for a while still catches up before cleanup. Note that 0.10 bumped the sync protocol (protocol v7, for the new certificate and security-key record types), so all paired devices must run 0.10.0 and re-pair to keep syncing; an older peer is rejected cleanly, nothing is overwritten. Your existing SFTP-snapshot blobs keep working (a 0.10 device still reads the old snapshot format).

I use the self-hosted relay. What can it see?

Ciphertext only. The relay and signaling server exist to get packets across NATs; they never hold keys and can't decrypt anything. Both are self-hostable (oryxis-relay, or a Cloudflare Worker for signaling).

Integrations

How does the MCP server work?

It exposes your hosts to MCP clients (Claude Desktop, Claude Code, Cursor, ...) through five tools: list_hosts, get_host, ssh_execute, list_groups, list_keys. It's disabled by default (Settings > Security), each host must be individually toggled as MCP-visible, and the server binary is a signed plugin downloaded on first enable, with a stable launcher path at ~/.oryxis/bin/oryxis-mcp so your client config never breaks across updates.

Is it safe to let the AI assistant run commands?

It runs them in your terminal, so it's gated three ways: a deterministic floor always force-prompts catastrophic commands, an independent LLM judge vets everything else before auto-execution, and the "always run" allow-list refuses chained, piped or substituted variations so a trusted command name can't smuggle a destructive payload. The assistant is bring-your-own-key (Anthropic, OpenAI, Gemini, or any OpenAI-compatible endpoint) and your API key is stored encrypted like any other secret.

Which cloud providers are supported?

AWS (named profiles, static keys, or IAM Identity Center; EC2 discovery, ECS Exec, SSM sessions and EC2 Instance Connect), Google Cloud (Compute Engine discovery plus GKE clusters added as Kubernetes accounts, driven by your gcloud CLI), Azure (VMs plus AKS clusters, driven by az), and Kubernetes (kubeconfig auth, workloads imported as dynamic groups that resolve to live pods via kubectl). Providers run as out-of-process plugins: Ed25519-signed binaries, verified before execution, downloaded on demand so the core app stays lean.

Platforms & troubleshooting

My keyboard shortcuts stopped working after updating to 0.11

That is deliberate, and only affects defaults you never customised. Several actions used to sit on bare Ctrl+letter chords that a terminal application can legitimately want, so they moved onto Ctrl+Shift:

Action	Was	Now
New-tab picker	Ctrl+K	Ctrl+Shift+T
Quick connect	Ctrl+K	Ctrl+Shift+G
Jump to tab	Ctrl+J	Ctrl+Shift+J
Local shell	Ctrl+L	Ctrl+Shift+L

A bare Ctrl+J is the line feed byte (emacs and readline bind it to accept-line), Ctrl+L clears the screen, and Ctrl+K kills to end of line, so all three now reach your shell instead of being swallowed. Bindings you set yourself are untouched, and everything stays rebindable in Settings > Shortcuts.

Which platforms are supported?

Windows (x64 and ARM64), macOS, and Linux (.deb, AppImage, tarball, AUR oryxis-bin, winget, Scoop extras/oryxis). Everything is native Rust; there's no Electron involved.

Windows: system or per-user installer?

• System (oryxis-setup-*.exe): Program Files, needs UAC, what winget install targets. Pick it for shared machines.
• Per-user (oryxis-user-setup-*.exe): installs under your profile, no admin rights ever, including updates. Pick it on locked-down machines.

The auto-updater knows which flavor you installed and fetches the matching artifact.

A host will not connect. Can Oryxis tell me what is wrong?

As of 0.16, without leaving the app: a network tools panel in its own tab does DNS lookups (A / AAAA / MX / TXT / SPF / CNAME / NS / SOA / PTR), ping, traceroute, a TCP port test that reports open, refused and filtered as three different answers, HTTP and TLS certificate checks, WHOIS, and eight public blocklists. Ping and traceroute need nothing installed on Linux, or on Windows for IPv4. It is off by default, like every optional feature here: Settings > Features turns it on.

Something is broken. How do I get useful logs?

Settings > Advanced: use Copy env info to grab version/OS/GPU details, and enable debug logging to write ~/.oryxis/oryxis-debug.log while you reproduce the problem. Redact hostnames and usernames before posting, then open a bug report.

What is the performance HUD, and how do I read it?

Settings > Advanced > Terminal performance HUD draws a small overlay in the top-right corner of every terminal, for diagnosing rendering slowness (attach a screenshot of it to performance bug reports). The curr / avg / peak rows show per-frame draw cost in milliseconds: T is the frame's total cost, L the time holding the terminal state lock (it contends with incoming output, so it's the typing-lag signal), C the cell/glyph geometry build, and H the URL/IP/keyword highlight scan. Click the panel to expand the letters into full names. cache is the share of frames served from the geometry cache, busy the share of active time spent drawing, and slow counts frames that blew the 16.7 ms frame budget (60 Hz); values past their thresholds tint amber, then red. The sparkline plots frame cost over the last ~120 frames, and a guide line marks the budget once anything gets near it.

On SSH tabs a net row shows round-trip current / average / peak and jitter, measured with transport keepalive probes, plus lost N for unanswered probes and a red "no reply for Ns" banner while the server is silent. Packet loss is invisible above TCP (the kernel retransmits silently), so it surfaces as exactly those round-trip spikes and stalls. Rule of thumb: a red T or a growing slow count means the renderer is struggling; an amber or red rtt means the wire, not the app, is why the session feels slow.

Terminal text looks thinner here than in my other terminal

That is real, and it is now adjustable. Oryxis draws the glyph exactly as the font file describes it. macOS runs text through Core Graphics with font smoothing on, which in the words of the font crate alacritty uses "increases the stroke width", and Windows does its own thickening, so the same font at the same size genuinely lands lighter here than in a terminal that rasterizes through the OS.

Settings > Terminal has Text Thickness (default Medium), which widens every stroke a fraction of a pixel, and Terminal Font Weight, which picks a heavier face when the family ships one. The picker tells you when the family you chose has no face at that weight, instead of silently drawing the closest.

Is Oryxis really free?

Yes. Free and open source forever, licensed AGPL-3.0-or-later. No accounts, no telemetry, no paid tier.

中文

欢迎中文用户。可以直接用中文在 Q&A 提问或用中文提 issue，维护者会阅读并尽力回复。项目还提供中文 README。

怎么把界面切换成中文？

设置 > 界面 > 语言，选择"简体中文"或"繁體中文"。默认的"Auto"会跟随操作系统的语言。首次切换时会自动下载 Noto Sans SC/TC 字体（约 12-17 MB）。

在中国大陆网络下，字体、插件或更新下载失败怎么办？

Oryxis 的下载默认先访问 GitHub，无法访问时自动回退到项目镜像 dl-cn.oryxis.app（腾讯 EdgeOne 加速），通常无需任何配置。如果你的网络完全无法访问 GitHub，可以在 设置 > 高级 > 下载镜像 中直接选择“项目镜像”，这样镜像就是第一顺位，而不只是回退；也可以选择“自定义镜像”，填入任何 ghproxy 前缀代理（例如 https://gh-proxy.com 或 https://ghfast.top），再用“测试”按钮验证。所有下载都经过 SHA-256 或 Ed25519 签名校验，镜像本身无需被信任。

连接老旧设备出现乱码？

在主机编辑器的终端设置中，可以按主机选择字符编码：GBK、GB18030、Big5 等。这适用于不支持 UTF-8 的旧交换机、路由器和遗留系统。

如果问题不是文字本身错乱，而是方框线、箭头或圈码把界面撑歪，那属于另一回事：东亚“歧义宽度”字符在中日韩环境下占两格、在西文环境下占一格。0.16 起可以按主机选择 自动 / 窄 / 宽（主机编辑器，或侧边栏的“主机配置”页），“自动”会根据该主机的字符编码判断。宽度是双方约定的，所以这个开关只能让我们去匹配一台自身设置已经一致的远程主机（例如 LANG=zh_CN.UTF-8 配 set ambiwidth=double）。

支持中文输入法吗？

支持。终端内可以直接使用 IME 输入中文（含候选窗口定位），Windows、macOS 和 Linux 均可用。

阿里云、腾讯云什么时候支持？

在路线图上（见路线图讨论）：阿里云 ECS 和腾讯云 CVM 的资源发现将作为签名插件提供，与现有的 AWS / GCP / Azure / Kubernetes 插件同一机制。