You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
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.
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.
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, peer-to-peer, end-to-end encrypted (QUIC, with automatic discovery on your LAN and an optional self-hosted relay across networks). No server ever sees plaintext.
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. Acting as an agent for other tools (git, VS Code Remote) is on the v1.0 roadmap.
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.
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. 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, as of 0.9. A per-host protocol selector adds Telnet (full RFC option negotiation, honest cleartext warning) and serial (COM / /dev/tty* with configurable line parameters) for switches, PDUs and console cables. ZMODEM transfers (sz / rz) are auto-detected over all three transports. And a remote desktop host (RDP / VNC) launches your OS-native client, optionally through an auto-provisioned SSH tunnel.
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.
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.9 bumped the sync protocol (new wire cipher), so all paired devices need to be on 0.9 or newer to keep syncing; an older peer is rejected cleanly, nothing is overwritten.
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
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.
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.
Is Oryxis really free?
Yes. Free and open source forever, licensed AGPL-3.0-or-later. No accounts, no telemetry, no paid tier.
reacted with thumbs up emoji reacted with thumbs down emoji reacted with laugh emoji reacted with hooray emoji reacted with confused emoji reacted with heart emoji reacted with rocket emoji reacted with eyes emoji
Uh oh!
There was an error while loading. Please reload this page.
Uh oh!
There was an error while loading. Please reload this page.
-
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.
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:
.oryxisfile 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.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. Acting as an agent for other tools (git, VS Code Remote) is on the v1.0 roadmap.
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/configimport?ProxyCommandmaps directly.ProxyJumpis 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.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. 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, as of 0.9. A per-host protocol selector adds Telnet (full RFC option negotiation, honest cleartext warning) and serial (COM /
/dev/tty*with configurable line parameters) for switches, PDUs and console cables. ZMODEM transfers (sz/rz) are auto-detected over all three transports. And a remote desktop host (RDP / VNC) launches your OS-native client, optionally through an auto-provisioned SSH tunnel.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.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.9 bumped the sync protocol (new wire cipher), so all paired devices need to be on 0.9 or newer to keep syncing; an older peer is rejected cleanly, nothing is overwritten.
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-mcpso 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
gcloudCLI), Azure (VMs plus AKS clusters, driven byaz), and Kubernetes (kubeconfig auth, workloads imported as dynamic groups that resolve to live pods viakubectl). Providers run as out-of-process plugins: Ed25519-signed binaries, verified before execution, downloaded on demand so the core app stays lean.Platforms & troubleshooting
Which platforms are supported?
Windows (x64 and ARM64), macOS, and Linux (.deb, AppImage, tarball, AUR
oryxis-bin, winget, Scoopextras/oryxis). Everything is native Rust; there's no Electron involved.Windows: system or per-user installer?
oryxis-setup-*.exe): Program Files, needs UAC, whatwinget installtargets. Pick it for shared machines.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.
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.logwhile 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/peakrows 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.cacheis the share of frames served from the geometry cache,busythe share of active time spent drawing, andslowcounts 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
netrow shows round-trip current / average / peak and jitter, measured with transport keepalive probes, pluslost Nfor 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 redTor a growingslowcount means the renderer is struggling; an amber or redrttmeans the wire, not the app, is why the session feels slow.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 加速），通常无需任何配置。如果你的网络环境特殊，可以在 设置 > 高级 > 下载镜像 中选择"自定义镜像"，填入任何 ghproxy 前缀代理（例如https://gh-proxy.com或https://ghfast.top），再用"测试"按钮验证。所有下载都经过 SHA-256 或 Ed25519 签名校验，镜像本身无需被信任。连接老旧设备出现乱码？
在主机编辑器的终端设置中，可以按主机选择字符编码：GBK、GB18030、Big5 等。这适用于不支持 UTF-8 的旧交换机、路由器和遗留系统。
支持中文输入法吗？
支持。终端内可以直接使用 IME 输入中文（含候选窗口定位），Windows、macOS 和 Linux 均可用。
阿里云、腾讯云什么时候支持？
在路线图上（见路线图讨论）：阿里云 ECS 和腾讯云 CVM 的资源发现将作为签名插件提供，与现有的 AWS / GCP / Azure / Kubernetes 插件同一机制。东亚字符宽度选项和终端背景图也在计划中。
Beta Was this translation helpful? Give feedback.
All reactions