FAQ

General

What is OxideTerm?

OxideTerm is an AI-native workspace for remote servers built in Rust with GPUI. It combines SSH terminal, local shell, SFTP, IDE mode, port forwarding, remote desktop, trzsz transfers, OxideSens AI, plugins, themes, and localized UI in one GPU-rendered native application.

Is OxideTerm free?

OxideTerm is licensed under GPL-3.0 (GNU General Public License v3.0):

• Personal, educational, research, and commercial use is allowed.
• Distributed derivative works must use 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 restrictions and noncommercial ambiguity. If you are unsure about a specific distribution scenario, open an issue.

What platforms are supported?

OxideTerm publishes packages for macOS, Windows, and Linux on both x64 and arm64. A GPU-capable desktop and working graphics driver are required.

How is OxideTerm different from browser-based desktop terminals?

OxideTerm uses GPUI to draw its interface directly on a GPU surface. The UI, terminal state, SSH services, and workspace logic are Rust code in the same native process.

Comparison	Browser-based desktop app	OxideTerm native
UI runtime	Bundled or system browser engine	GPUI GPU surface
Desktop package	Often includes a browser runtime	Approximately 50–70 MB, depending on target
Terminal path	Bytes cross a script/UI boundary	Rust input mutates TerminalState directly
SSH implementation	Varies	Pure Rust russh with ring
Headless management	Often depends on a running app	Standalone oxideterm CLI links to domain crates

Connections

How are passwords stored?

Passwords, private-key passphrases, and API keys are stored in the operating system keychain: Keychain Access on macOS, Windows Credential Manager on Windows, and a Secret Service provider on Linux. They are not stored as plaintext configuration values.

Saved connection metadata is protected separately. The local connection document is encrypted with a key held by the keychain layer.

Can I import connections from other SSH clients?

Yes. OxideTerm can import its encrypted .oxide format and parse OpenSSH configuration, including hosts, jump hosts, key paths, and related settings. You can also create connections manually in the app or through oxideterm connections.

Does OxideTerm support jump hosts?

Yes. OxideTerm supports multi-hop ProxyJump routes. Each hop can use its own supported authentication method, and the topology view shows the route and downstream state. Keyboard-interactive authentication is available for direct connections; explicit keyboard-interactive authentication across proxy chains remains limited.

What SSH key types are supported?

• Ed25519
• ECDSA P-256 and P-384
• RSA with a 2048-bit minimum
• SSH certificates
• Passphrase-protected private keys

Does OxideTerm support SSH Agent?

Yes. OxideTerm uses SSH_AUTH_SOCK on macOS/Linux and the OpenSSH agent named pipe on Windows. Agent authentication can be replayed after reconnect, and Agent Forwarding can be enabled per connection.

What happens when my connection drops?

OxideTerm’s Grace Period Reconnect pipeline works in Rust:

1. A keepalive task detects a degraded or lost SSH transport.
2. OxideTerm probes the old connection for 30 seconds. If the stream recovers, running TUI applications can continue on the original session.
3. If recovery fails, OxideTerm opens a new connection and restores dependent forwards, transfers, and IDE state where possible.

Can multiple features share one SSH connection?

Yes. Terminal, SFTP, port forwarding, and IDE consumers resolve through the node router and connection registry, allowing them to share one physical connection.

Features

Can I use my own AI provider?

Yes. OxideSens is BYOK. Configure OpenAI, Anthropic, Gemini, Ollama, or an OpenAI-compatible endpoint. Provider secrets stay in the OS keychain, and workspace actions require approval under the configured tool policy.

Does the AI feature send my terminal data to a provider?

Only when a request includes that context. OxideTerm redacts credentials before constructing provider context and does not collect terminal data as telemetry. Use Ollama for a local model workflow.

Can I use OxideTerm without internet access?

Local shells and local configuration work offline. SSH, SFTP, forwarding, and remote desktop need only network access to their targets. Update checks, cloud providers, Cloud Sync remotes, and hosted AI providers require their respective network connections.

What is the Remote Agent?

The optional lightweight Rust agent enhances IDE mode on remote Linux hosts:

• File watching and native Git status
• Atomic writes with hash-based conflict detection
• User-confirmed deployment on bundled x86_64 and arm64 Linux targets
• A line-oriented request channel carried inside the existing SSH connection, with no externally listening service
• Complete SFTP fallback when the agent is disabled or unavailable

What is the CLI companion (oxideterm)?

oxideterm is a standalone headless management CLI. It directly reads and updates OxideTerm state through Rust domain crates, so the desktop app does not need to be running. It covers settings, connections, SSH launch, forwards, Quick Commands, plugins, portable state, secrets, .oxide bundles, cloud sync, paths, diagnostics, health checks, backups, batch plans, reports, completions, and stable error codes.

Use --json or --format json where supported for automation. Most write commands provide --dry-run and require --yes before applying changes.

Can I record terminal sessions?

Yes. OxideTerm records asciicast v2 sessions with timestamps and provides variable-speed playback and export.

How does broadcast input work?

Select terminal panes as broadcast targets, then submit a command from the terminal command bar. The native workspace sends that command to the current pane and each selected target. Direct terminal typing is not mirrored key by key. Review destructive commands carefully because broadcast is immediate.

Plugins

How do native plugins work?

Plugins are discovered from the active configuration directory. Each package has a plugin.json manifest and a supported native entry, such as a WASM module or declared process entry. Unsupported legacy script entries are not loaded into the UI.

Are plugins sandboxed?

Native WASM plugins run under wasmtime and can call only the typed host capabilities declared in their manifest. The host validates permissions before filesystem, forwarding, SFTP, or other effects are executed. Invalid manifests are rejected.

Can plugins access files or the network?

Only through capabilities granted by the native host. Filesystem, SFTP, and forwarding operations are mediated by typed host APIs and permission checks; installing a plugin does not grant unrestricted access.

Troubleshooting

The app will not start on macOS

If Gatekeeper blocks an unsigned preview, use Open from the Finder context menu or review the message in System Settings → Privacy & Security. Only bypass quarantine for an official artifact whose checksum you verified.

Connection drops frequently

• Check network stability and the remote server’s SSH logs.
• Review keepalive and idle-timeout settings for the connection.
• Inspect reconnect and health state in Runtime.
• Run oxideterm diagnose --json and oxideterm doctor --strict for a redacted local snapshot.

Terminal rendering is slow or the app cannot open a window

• Update your GPU driver.
• Disable incompatible graphics overlays or injection layers.
• Try OXIDETERM_RENDER_PROFILE=compatibility when launching from a shell.
• Reduce expensive terminal background effects if they are enabled.

Where are configuration files stored?

Paths depend on the operating system, package mode, optional OXIDETERM_CONFIG_DIR, and named profile. Ask the CLI for the resolved locations:

oxideterm paths --json

How do I completely uninstall OxideTerm?

1. Remove the installed application or portable directory.
2. Run oxideterm paths --json before uninstalling and remove only the data directories you intend to discard.
3. Remove OxideTerm entries from your OS keychain if you also want to delete saved credentials.
4. Remove the active plugin directory reported by oxideterm paths if you do not want to keep installed plugins.