### Build OxideTerm from Source

Source: https://oxideterm.app/docs/installation

Clone the repository, install Linux dependencies, and build the desktop application.

```bash
git clone https://github.com/AnalyseDeCircuit/oxideterm.git
cd oxideterm


# Linux only: install the repository's native desktop dependencies.
./scripts/install-linux-deps.sh


cargo build --release -p oxideterm-gpui-app
```

--------------------------------

### Import an .oxide bundle

Source: https://oxideterm.app/docs/plugin-development

Example of a host call to import an .oxide bundle with specified configuration.

```json
{
  "type": "callHostApi",
  "requestId": "host-6",
  "namespace": "sync",
  "method": "importOxide",
  "args": {
    "fileData": [1, 2, 3],
    "password": "user-entered-password",
    "conflictStrategy": "rename",
    "importAppSettings": true,
    "importPluginSettings": true
  }
}
```

--------------------------------

### Read a plugin setting

Source: https://oxideterm.app/docs/plugin-development

Example of a host call to retrieve a specific setting key.

```json
{
  "type": "callHostApi",
  "requestId": "host-2",
  "namespace": "settings",
  "method": "get",
  "args": {
    "key": "message"
  }
}
```

--------------------------------

### Install Openbox for App Mode

Source: https://oxideterm.app/docs/features/graphics

Install the Openbox minimal window manager to support single-application mode.

```bash
sudo apt install openbox -y
```

--------------------------------

### Install VNC and Desktop Environment Packages

Source: https://oxideterm.app/docs/features/graphics

Required packages for VNC server, D-Bus, and desktop environments. Choose one desktop environment to install.

```bash
# VNC server + D-Bus
sudo apt install tigervnc-standalone-server dbus-x11 -y


# Desktop environment — choose one:
sudo apt install xfce4 -y                    # XFCE (lightweight)
sudo apt install ubuntu-desktop -y           # GNOME (full Ubuntu)
sudo apt install kde-plasma-desktop -y       # KDE Plasma
```

--------------------------------

### Install Debian Package

Source: https://oxideterm.app/docs/installation

Use the system package manager to install the OxideTerm Debian package on Linux.

```bash
sudo apt install ./OxideTerm_x.x.x_linux_x64.deb
```

--------------------------------

### Multi-Terminal Tab Examples

Source: https://oxideterm.app/docs/features/local-terminal

Demonstrates running different shell processes in separate working directories simultaneously.

```text
Terminal 1: PowerShell  (C:\Users\alice)
Terminal 2: Git Bash    (C:\projects\app)
Terminal 3: WSL Ubuntu  (/home/alice)
```

--------------------------------

### Install RPM Package

Source: https://oxideterm.app/docs/installation

Use the dnf package manager to install the OxideTerm RPM package on Linux.

```bash
sudo dnf install ./OxideTerm_x.x.x_linux_x64.rpm
```

--------------------------------

### Read the active terminal target

Source: https://oxideterm.app/docs/plugin-development

Example of a host call to get the active terminal target.

```json
{
  "type": "callHostApi",
  "requestId": "host-3",
  "namespace": "terminal",
  "method": "getActiveTarget",
  "args": {}
}
```

--------------------------------

### Initialize Oh My Posh in PowerShell

Source: https://oxideterm.app/docs/features/local-terminal

Automatically injects Oh My Posh initialization into PowerShell sessions. Requires Oh My Posh installation, a Nerd Font, and the font selected in OxideTerm settings.

```powershell
oh-my-posh init pwsh --config '<your-theme-path>' | Invoke-Expression
```

--------------------------------

### Generate Shell Completion for Zsh

Source: https://oxideterm.app/docs/features/cli

Commands to generate Zsh completion files. Use 'completion install' to install, optionally with '--force' when replacing an existing file.

```shell
oxideterm completion zsh > ~/.zfunc/_oxideterm
oxideterm completion path zsh
oxideterm completion install zsh

```

--------------------------------

### Minimal Manifest-Only Plugin JSON

Source: https://oxideterm.app/docs/plugin-development

An example of a plugin.json manifest for a manifest-only plugin that provides static metadata, settings, and AI tool definitions without executing code.

```json
{
  "id": "com.example.audit",
  "name": "Audit Helper",
  "version": "0.1.0",
  "description": "Adds audit-related settings and tool metadata.",
  "author": "Example",
  "runtime": {
    "kind": "manifest-only",
    "entry": ""
  },
  "contributes": {
    "settings": [
      {
        "id": "scanDepth",
        "type": "number",
        "default": 3,
        "title": "Scan depth",
        "description": "Maximum audit depth."
      }
    ],
    "aiTools": [
      {
        "name": "audit_summarize",
        "description": "Summarize visible connection and terminal state.",
        "capabilities": ["state.list", "terminal.observe"],
        "risk": "read",
        "targetKinds": ["ssh-node", "terminal-session"]
      }
    ]
  }
}
```

--------------------------------

### asciicast v2 format example

Source: https://oxideterm.app/docs/features/recording

Shows the JSON Lines structure of a .cast file: a header line with version, dimensions, timestamp, and environment, followed by event lines with time offset, event type, and data.

```json
{"version": 2, "width": 220, "height": 55, "timestamp": 1711700000, "env": {"TERM": "xterm-256color"}}
[0.123, "o", "$ ls -la\r\n"]
[0.456, "o", "total 48\r\ndrwxr-xr-x  5 user group ..."]
```

--------------------------------

### Create hello-native plugin directory structure

Source: https://oxideterm.app/docs/plugin-development

Directory layout for a minimal process plugin. Create this inside the user plugin directory.

```text
hello-native/
  plugin.json
  bin/
    hello.js

```

--------------------------------

### sftp.init

Source: https://oxideterm.app/docs/plugin-development

Initializes an SFTP session for a node.

```APIDOC
## sftp.init

### Description
Initializes an SFTP session for a node.

### Method
HOST API

### Endpoint
sftp.init

### Parameters
#### Request Body
- **nodeId** (string) - Required - The node identifier.

### Response
#### Success Response
- **Session status** - The session status.

```

--------------------------------

### Manage connections

Source: https://oxideterm.app/docs/features/cli

Commands to list, search, create, and rename connections. Use --dry-run for creation and --yes for destructive operations like renaming.

```bash
oxideterm connections list
oxideterm connections search prod --json
oxideterm connections create --name prod --host example.internal --user deploy --port 22 --dry-run
oxideterm connections rename prod production --yes
oxideterm connections validate --strict
oxideterm connections export --format raw-safe --json
```

--------------------------------

### Write text to the active terminal

Source: https://oxideterm.app/docs/plugin-development

Example of a host call to write text to the active terminal.

```json
{
  "type": "callHostApi",
  "requestId": "host-4",
  "namespace": "terminal",
  "method": "writeToActive",
  "args": {
    "text": "pwd\n"
  }
}
```

--------------------------------

### Run AppImage

Source: https://oxideterm.app/docs/installation

Make the AppImage executable and run it directly on Linux.

```bash
chmod +x OxideTerm_x.x.x_linux_x64.AppImage
./OxideTerm_x.x.x_linux_x64.AppImage
```

--------------------------------

### Manage application settings

Source: https://oxideterm.app/docs/features/cli

Commands for validating, retrieving, and modifying configuration settings. Use --dry-run to preview changes before applying them with --yes.

```bash
oxideterm settings validate --strict
oxideterm settings sections --json
oxideterm settings get ai.providers --json
oxideterm settings set terminal.fontSize 14 --dry-run
oxideterm settings export --section appearance --json
oxideterm settings diff ./settings-snapshot.json --section appearance
```

--------------------------------

### Read a remote file through SFTP

Source: https://oxideterm.app/docs/plugin-development

Example of a host call to read a remote file, requiring the filesystem.read capability.

```json
{
  "type": "callHostApi",
  "requestId": "host-5",
  "namespace": "sftp",
  "method": "readFile",
  "args": {
    "nodeId": "node-1",
    "path": "/etc/hostname"
  }
}
```

--------------------------------

### Validate and Preview .oxide Bundle Import

Source: https://oxideterm.app/docs/security

Commands to validate a .oxide bundle and preview its import before applying. Passwords should be supplied via standard input or an environment variable to avoid shell history exposure.

```bash
oxideterm oxide validate ./profile.oxide
oxideterm oxide preview-import ./profile.oxide --password-stdin --json

```

--------------------------------

### Inspect Application Paths

Source: https://oxideterm.app/docs/installation

Retrieve active paths for profiles and data directories in JSON format before uninstallation.

```bash
oxideterm paths --json
```

--------------------------------

### CLI commands for headless plugin state and settings checks

Source: https://oxideterm.app/docs/plugin-development

Use these commands during development to list plugins, enable a plugin with a dry run, and export settings. They are intended for headless state/settings checks.

```bash
oxideterm plugins list --json
oxideterm plugins enable com.example.native-dashboard --dry-run --json
oxideterm plugins settings export --json
```

--------------------------------

### Host API call JSON payload

Source: https://oxideterm.app/docs/plugin-development

Example of a host API call message. The payload type is callHostApi, with namespace connections and method getAll. The host rejects calls not allowed by the plugin permission set.

```json
{
  "protocolVersion": 1,
  "requestId": null,
  "payload": {
    "type": "callHostApi",
    "requestId": "host-1",
    "namespace": "connections",
    "method": "getAll",
    "args": {}
  }
}
```

--------------------------------

### sftp.mkdir

Source: https://oxideterm.app/docs/plugin-development

Creates a directory on the remote host.

```APIDOC
## sftp.mkdir

### Description
Creates a directory on the remote host.

### Method
HOST API

### Endpoint
sftp.mkdir

### Parameters
#### Request Body
- **nodeId** (string) - Required - The node identifier.
- **path** (string) - Required - The directory path to create.

### Response
#### Success Response
- **Directory result** - The directory result.

```

--------------------------------

### sftp.preview

Source: https://oxideterm.app/docs/plugin-development

Returns a preview payload for a file.

```APIDOC
## sftp.preview

### Description
Returns a preview payload for a file.

### Method
HOST API

### Endpoint
sftp.preview

### Parameters
#### Request Body
- **nodeId** (string) - Required - The node identifier.
- **path** (string) - Required - The file path.

### Response
#### Success Response
- **Preview payload** - The preview payload.

```

--------------------------------

### Build Standalone CLI

Source: https://oxideterm.app/docs/installation

Build the standalone CLI component from the source repository.

```bash
cargo build --release -p oxideterm-cli
```

--------------------------------

### Architecture diagram: GPUI render loop and domain services

Source: https://oxideterm.app/docs/getting-started

ASCII diagram showing the in-process architecture: GPUI render loop on top, domain services below, connected by in-process Rust calls. Terminal traffic and UI actions do not cross a serialization bridge.

```text
┌───────────────────────────────────────────────┐
│              GPUI render loop                │
│ Workspace · tabs · sidebars · native views  │
└──────────────────────┬────────────────────────┘
                       │ in-process Rust calls
┌──────────────────────▼────────────────────────┐
│               Domain services                │
│ NodeRouter · SSH registry · SFTP · forwards │
│ TerminalState · IDE · AI · plugins · sync   │
└───────────────────────────────────────────────┘
```

--------------------------------

### Perform backup and restore operations

Source: https://oxideterm.app/docs/features/cli

Commands to create, inspect, and restore application backups. Always review restore plans with --dry-run before confirming with --yes.

```bash
oxideterm backup create --output ./oxideterm-backup.json --json
oxideterm backup inspect ./oxideterm-backup.json --summary
oxideterm backup restore ./oxideterm-backup.json --section settings --dry-run --json
```

--------------------------------

### Configure CLI paths and profiles

Source: https://oxideterm.app/docs/features/cli

Specify a custom configuration directory or profile using command-line flags or environment variables.

```bash
oxideterm --config-dir <path> <command>
oxideterm --profile <name> <command>
OXIDETERM_CONFIG_DIR=<path> oxideterm <command>
```

--------------------------------

### Package directory structure for a native plugin

Source: https://oxideterm.app/docs/plugin-development

Shows the required layout for a plugin package: plugin.json at the root or in a single nested directory, with bin/ containing the runtime binary. Archive entries must not escape the plugin directory.

```text
com.example.native-dashboard/
  plugin.json
  bin/
    native-dashboard
  README.md
  LICENSE
```

--------------------------------

### Diagnose connection issues

Source: https://oxideterm.app/docs/faq

Run these commands to generate a redacted local snapshot for troubleshooting connection drops.

```bash
oxideterm diagnose --json
oxideterm doctor --strict
```

--------------------------------

### plugin.json manifest for hello-native process plugin

Source: https://oxideterm.app/docs/plugin-development

Manifest for a minimal native process plugin. Declares a process runtime entry, a sidebar panel, a string setting with default, and an API command.

```json
{
  "id": "com.example.hello-native",
  "name": "Hello Native",
  "version": "0.1.0",
  "description": "Minimal native process plugin.",
  "runtime": {
    "kind": "process",
    "entry": "bin/hello.js"
  },
  "contributes": {
    "sidebarPanels": [
      {
        "id": "hello-panel",
        "title": "Hello",
        "icon": "panel-left",
        "position": "top"
      }
    ],
    "settings": [
      {
        "id": "message",
        "type": "string",
        "default": "Hello from a native plugin",
        "title": "Message"
      }
    ],
    "apiCommands": [
      "get_app_version"
    ]
  }
}

```

--------------------------------

### CLI Help Command

Source: https://oxideterm.app/docs/features/cli

Command to display help information for the CLI or specific subcommands.

```bash
oxideterm --help
oxideterm <command> --help
```

--------------------------------

### Native Adapter Commands

Source: https://oxideterm.app/docs/plugin-development

List of native adapter commands that can be invoked via the host API, mapping command names to their adapter functions.

```APIDOC
## Native Adapter Commands

### Description
These commands are available as native adapters and can be invoked through the host API. Each command maps to a specific adapter function.

### Commands
| Command | Adapter |
|---------|---------|
| `ssh_get_pool_stats` | SSH pool statistics |
| `list_connections` | Saved/known connection snapshots |
| `get_app_version` | Application version |
| `get_system_info` | Platform, architecture, OS, and family |
| `sftp_cancel_transfer` | Cancel transfer by `transferId` |
| `sftp_pause_transfer` | Pause transfer by `transferId` |
| `sftp_resume_transfer` | Resume transfer by `transferId` |
| `sftp_transfer_stats` | Transfer queue statistics |
| `node_sftp_init` | `sftp.init` adapter |
| `node_sftp_list_dir` | `sftp.listDir` adapter |
| `node_sftp_stat` | `sftp.stat` adapter |
| `node_sftp_preview` | `sftp.preview` adapter |
| `node_sftp_write` | `sftp.write` adapter |
| `node_sftp_download` | `sftp.download` adapter |
| `node_sftp_upload` | `sftp.upload` adapter |
| `node_sftp_mkdir` | `sftp.mkdir` adapter |
| `node_sftp_delete` | `sftp.delete` adapter |
| `node_sftp_delete_recursive` | `sftp.deleteRecursive` adapter |
| `node_sftp_rename` | `sftp.rename` adapter |
| `node_sftp_download_dir` | `sftp.downloadDir` adapter |
| `node_sftp_upload_dir` | `sftp.uploadDir` adapter |
| `node_sftp_tar_probe` | `sftp.tarProbe` adapter |
| `node_sftp_tar_upload` | `sftp.tarUpload` adapter |
| `node_sftp_tar_download` | `sftp.tarDownload` adapter |
| `list_port_forwards` | `forward.list` adapter |
| `create_port_forward` | `forward.create` adapter |
| `stop_port_forward` | `forward.stop` adapter |
| `delete_port_forward` | `forward.delete` adapter |
| `restart_port_forward` | `forward.restart` adapter |
| `update_port_forward` | `forward.update` adapter |
| `get_port_forward_stats` | `forward.getStats` adapter |
| `stop_all_forwards` | `forward.stopAll` adapter |
| `plugin_http_request` | HTTP/HTTPS request adapter with a 10 MiB body limit |

```

--------------------------------

### Set compatibility render profile

Source: https://oxideterm.app/docs/faq

Use this environment variable when launching from a shell to address slow rendering or window opening issues.

```bash
OXIDETERM_RENDER_PROFILE=compatibility
```

--------------------------------

### Batch Apply Commands

Source: https://oxideterm.app/docs/features/cli

Commands to apply batch plans from a JSON file. Use --dry-run to preview changes or --yes to bypass confirmation prompts.

```bash
oxideterm batch apply ./plan.json --dry-run
oxideterm batch apply ./plan.json --yes --json
```