FAQ
General
Section titled “General”What is OxideTerm?
Section titled “What is OxideTerm?”OxideTerm is a local-first SSH workspace built with Tauri 2.0 (Rust) and React 19 (TypeScript). It combines SSH terminal, local shell, SFTP, IDE mode, port forwarding, trzsz transfers, BYOK AI assistance, plugins, themes, and 11 languages into a single native application.
Is OxideTerm free?
Section titled “Is OxideTerm free?”OxideTerm is licensed under GPL-3.0 (GNU General Public License v3.0):
- Everyone: free — personal, educational, research, and commercial use
- Derivative works: must be distributed under the same GPL-3.0 license
- Source code: must be made available when distributing modified versions
OxideTerm previously used PolyForm Noncommercial and moved to GPL-3.0 to avoid source-available traps, noncommercial ambiguity, and no-competition riders.
Public code is not automatically open source. If a license adds “no redistribution”, “no repackaging”, “no competing products”, or platform approval clauses on top of a familiar open-source name, it is source-available branding, not open-source freedom. OxideTerm does not add those riders: GPL-3.0 is the whole license.
If you’re unsure whether your use qualifies, open an issue.
What platforms are supported?
Section titled “What platforms are supported?”macOS (Apple Silicon & Intel), Windows (x64 & ARM64), and Linux (x64 & ARM64).
How is OxideTerm different from Electron-based terminals?
Section titled “How is OxideTerm different from Electron-based terminals?”OxideTerm uses Tauri 2.0, which leverages the system’s native webview instead of bundling Chromium:
| Comparison | Electron | Tauri (OxideTerm) |
|---|---|---|
| Binary size | ~150 MB | 25–40 MB |
| Memory usage | ~300 MB | ~50 MB |
| Security model | Chromium | Rust memory safety + sandbox |
| SSH implementation | Node.js binding (ssh2) | Pure Rust (russh) |
How big is the codebase?
Section titled “How big is the codebase?”271,000+ lines of Rust & TypeScript.
Connections
Section titled “Connections”How are passwords stored?
Section titled “How are passwords stored?”Passwords are stored in your operating system’s native keychain (Keychain Access on macOS, Windows Credential Manager, Secret Service on Linux). They are never stored in plaintext configuration files.
Saved connection metadata is also encrypted at rest locally. OxideTerm keeps secrets in the OS keychain and seals the on-disk connection config with a local encryption key stored in that same keychain layer.
Can I import connections from other SSH clients?
Section titled “Can I import connections from other SSH clients?”OxideTerm supports:
- Importing from its own
.oxideencrypted format - SSH config import — auto-parse
~/.ssh/configto import existing hosts, jump hosts, key paths, and other settings - Manual creation via the connection wizard
Does OxideTerm support jump hosts (ProxyJump)?
Section titled “Does OxideTerm support jump hosts (ProxyJump)?”Yes. OxideTerm supports unlimited ProxyJump hops with a network topology graph:
- Configure jump chains in the connection wizard
- Auto-parse ProxyJump from
~/.ssh/config - Dijkstra pathfinding calculates optimal routes
- Visual topology graph shows all nodes and connections
- Each hop can use a different authentication method (password, key, agent, certificate)
- Keyboard-interactive / 2FA is supported on direct connections; explicit KeyboardInteractive auth over proxy chains is still limited today
- Jump nodes are reusable as independent sessions
What SSH key types are supported?
Section titled “What SSH key types are supported?”- Ed25519 (recommended — fastest, smallest keys)
- ECDSA (P-256, P-384)
- RSA (2048-bit minimum)
- SSH Certificates — full certificate-based authentication
- Keys with passphrases are supported (passphrase stored in OS keychain)
Does OxideTerm support SSH Agent?
Section titled “Does OxideTerm support SSH Agent?”Yes. OxideTerm integrates with the system SSH Agent:
- macOS/Linux: via
SSH_AUTH_SOCK - Windows: via
\\.\pipe\openssh-ssh-agent - Agent auth is replayed automatically on reconnect
- Each ProxyJump hop can independently use Agent auth
- Optional Agent Forwarding is available per connection when remote tools need to reach your local agent
What happens when my connection drops?
Section titled “What happens when my connection drops?”OxideTerm includes a Grace Period Reconnect system:
- Detects disconnect via WebSocket heartbeat (300s timeout, tuned for macOS App Nap)
- Probes the old connection for 30 seconds — if the SSH TCP stream recovers (e.g., Wi-Fi switch), your running TUI apps (vim, htop, yazi) survive completely
- If recovery fails → new SSH connection → automatic restore of port forwards, SFTP transfers, and IDE files
The reconnect orchestrator handles this end-to-end without user intervention.
Can multiple features share one SSH connection?
Section titled “Can multiple features share one SSH connection?”Yes. OxideTerm uses a reference-counted connection pool. Terminal, SFTP, port forwarding, and IDE mode all share a single physical SSH connection — no redundant TCP handshakes or authentication prompts.
What are the idle timeout options?
Section titled “What are the idle timeout options?”Configurable: 5 minutes, 15 minutes, 30 minutes (default), 1 hour, or never. Connections with no active consumers (no terminal tabs, no SFTP panel, no port forwards) auto-disconnect after the timeout.
Features
Section titled “Features”Can I use my own AI provider?
Section titled “Can I use my own AI provider?”Yes. OxideSens uses a BYOK (Bring Your Own Key) model. You provide your own API key for OpenAI, Anthropic, Google, DeepSeek, Ollama, or any OpenAI-compatible endpoint. Keys are stored securely in your OS keychain. OxideTerm does not require an app subscription for the core SSH workspace; AI provider costs belong to the provider you choose.
Does the AI feature send my terminal data to the cloud?
Section titled “Does the AI feature send my terminal data to the cloud?”Only when you explicitly request it. Terminal buffer data is sent to your configured AI provider only when you ask OxideSens to use that context. No automatic data collection occurs. For fully offline AI, use Ollama with local models.
Can I use OxideTerm without an internet connection?
Section titled “Can I use OxideTerm without an internet connection?”Yes. SSH/SFTP/port forwarding/local shell workflows work without an OxideTerm account or subscription. Internet access is only needed for remote network targets, update checks, optional Cloud Sync, or cloud AI providers. AI features can work offline with Ollama local models.
What is the Remote Agent?
Section titled “What is the Remote Agent?”An optional ~1 MB Rust binary that deploys to remote Linux servers to enhance IDE mode:
- Faster file tree operations and symbol search
- Real-time file watching
- 43 JSON-RPC methods
- Auto-deploys on x86_64/aarch64 Linux; other architectures must build the agent from source and upload it manually
- IDE mode works completely without it
What is the CLI companion (oxt)?
Section titled “What is the CLI companion (oxt)?”A ~1 MB binary for controlling OxideTerm from the command line. It uses JSON-RPC 2.0 over Unix Socket (macOS/Linux) or Named Pipe (Windows). Commands include status, list, and ping, with human-readable or JSON output.
Can I record terminal sessions?
Section titled “Can I record terminal sessions?”Yes. OxideTerm records sessions in asciicast v2 format with precise timestamps. Playback supports variable speed (0.5×–8×). Recordings can be exported for sharing.
How does broadcast input work?
Section titled “How does broadcast input work?”Toggle broadcast mode from the toolbar to send identical keystrokes to all selected split panes simultaneously. Useful for managing clusters or running the same command across multiple servers.
Plugins
Section titled “Plugins”Are there official plugins?
Section titled “Are there official plugins?”Yes. OxideTerm currently ships an official plugin lineup focused on optional workflows rather than mandatory accounts:
- Cloud Sync — encrypted self-hosted sync for
.oxidesnapshots via WebDAV, HTTP JSON, Dropbox, Git, or S3 - Telnet Client — native Telnet client for routers, switches, and legacy devices
Plugins are opt-in. The core app remains local-first and works without any cloud account.
Where are plugins installed?
Section titled “Where are plugins installed?”Plugins are stored in ~/.oxideterm/plugins/{plugin-id}/. Each plugin has a plugin.json manifest and an ESM entry point.
Are plugins sandboxed?
Section titled “Are plugins sandboxed?”Yes. Plugins run with multiple security layers:
- Frozen API surface (
Object.freeze) - Proxy-based permission ACL
- IPC command whitelist
- Circuit breaker with auto-disable on repeated errors
- React error boundaries for UI isolation
Can plugins access the file system?
Section titled “Can plugins access the file system?”Not directly. Plugins access files through the sftp and storage namespaces of the PluginContext API. Direct file system access is not available.
Troubleshooting
Section titled “Troubleshooting”The app won’t start on macOS
Section titled “The app won’t start on macOS”On first launch, macOS Gatekeeper may block the app. Right-click the app → Open, or go to System Settings → Privacy & Security → Allow.
Connection drops frequently
Section titled “Connection drops frequently”- Check your network stability
- OxideTerm’s Grace Period Reconnect attempts automatic recovery for 30 seconds before reconnecting
- Adjust keepalive settings in the connection configuration
- The SSH keepalive interval is 15 seconds by default
Terminal rendering is slow
Section titled “Terminal rendering is slow”- Ensure WebGL is enabled in your system
- Try reducing the terminal font size
- Check if your GPU drivers are up to date
- OxideTerm uses adaptive rendering — heavy output triggers 120 Hz+ Boost mode automatically
Chinese/Japanese/Korean input issues on Windows
Section titled “Chinese/Japanese/Korean input issues on Windows”Windows IME integration may have issues in some configurations. Ensure you’re using the latest version of OxideTerm, which includes ConPTY improvements for CJK input.
Where are configuration files stored?
Section titled “Where are configuration files stored?”| Platform | Path |
|---|---|
| macOS | ~/Library/Application Support/com.oxideterm.app/ |
| Windows | %APPDATA%\com.oxideterm.app\ |
| Linux | ~/.config/com.oxideterm.app/ |
Data is stored in a local redb embedded key-value database within this directory.
How do I completely uninstall OxideTerm?
Section titled “How do I completely uninstall OxideTerm?”- Remove the application (drag to Trash / uninstall / delete AppImage)
- Delete the configuration directory (see paths above)
- Remove keychain entries: search for
com.oxidetermin your OS keychain manager - (Optional) Remove plugins: delete
~/.oxideterm/