XPipe

https://github.com/xpipe-io/docs
Admin
XPipe is a tool for managing and accessing remote systems and connections through an intuitive...
Tokens:46,870
Snippets:736
Trust Score:8.8
Update:4 months ago
Show doc for...
Tokens:
Raw
### Install XPipe with Zypper

Source: https://github.com/xpipe-io/docs/blob/master/content/guide/managed-installation.mdx

Installs XPipe using Zypper. Imports the GPG key, adds the repository, and installs the package.

```bash
sudo rpm --import https://xpipe.io/signatures/0xDD3E0AD0.asc
sudo zypper ar -f https://rpm.xpipe.io xpipe
sudo zypper install xpipe
```

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

### Add XPipe Apt Repository and Install

Source: https://github.com/xpipe-io/docs/blob/master/content/guide/managed-installation.mdx

Sets up the XPipe apt repository and installs XPipe on Debian-based systems.

```bash
sudo apt update
sudo apt install wget gpg
wget -qO- https://xpipe.io/signatures/0xDD3E0AD0.gpg > xpipe.gpg
sudo install -D -o root -g root -m 644 xpipe.gpg /etc/apt/keyrings/xpipe.gpg
rm xpipe.gpg
sudo sh -c 'echo "deb [signed-by=/etc/apt/keyrings/xpipe.gpg] https://apt.xpipe.io/ stable main" > /etc/apt/sources.list.d/xpipe.list'
sudo apt clean && sudo apt update && sudo apt install xpipe
```

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

### Install XPipe with DNF 5+

Source: https://github.com/xpipe-io/docs/blob/master/content/guide/managed-installation.mdx

Installs XPipe using DNF version 5 or later. Adds the repository from a URL and installs the package.

```bash
sudo dnf config-manager addrepo --from-repofile=https://rpm.xpipe.io/xpipe.repo
sudo dnf install xpipe
```

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

### Install XPipe with DNF 4

Source: https://github.com/xpipe-io/docs/blob/master/content/guide/managed-installation.mdx

Installs XPipe using DNF version 4. Imports the GPG key, adds the repository, and installs the package.

```bash
sudo rpm --import https://xpipe.io/signatures/0xDD3E0AD0.asc
sudo dnf config-manager --add-repo https://rpm.xpipe.io/xpipe.repo
sudo dnf install xpipe
```

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

### Install XPipe with Homebrew

Source: https://github.com/xpipe-io/docs/blob/master/content/guide/managed-installation.mdx

Installs XPipe using Homebrew cask. Requires Homebrew to be installed.

```bash
brew install --cask xpipe-io/tap/xpipe
```

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

### Verify CLI Setup

Source: https://github.com/xpipe-io/docs/blob/master/content/cli/index.mdx

Verify that the XPipe CLI is accessible from your system's PATH. This command should work if the CLI was installed correctly.

```bash
xpipe --help
```

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

### Install XPipe Python API

Source: https://github.com/xpipe-io/docs/blob/master/content/guide/python-api.mdx

Install the XPipe Python API using pip.

```bash
python3 -m pip install xpipe_api
```

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

### JSON Output Example 1

Source: https://github.com/xpipe-io/docs/blob/master/content/guide/password-manager.mdx

Example JSON output from a custom command, containing username and password fields.

```json
{
  "myusername": "root",
  "mypassword": "123"
}
```

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

### Add XPipe RPM Repository and Install with Yum

Source: https://github.com/xpipe-io/docs/blob/master/content/guide/managed-installation.mdx

Imports the GPG key, adds the XPipe RPM repository, and installs XPipe using Yum.

```bash
sudo rpm --import https://xpipe.io/signatures/0xDD3E0AD0.asc
sudo yum install yum-config-manager
sudo yum-config-manager --add-repo https://rpm.xpipe.io/xpipe.repo
sudo yum install xpipe --refresh
```

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

### SSH Connection Schema Example (In-Place Credentials)

Source: https://github.com/xpipe-io/docs/blob/master/content/guide/python-api.mdx

An example of an SSH connection schema with encrypted credentials configured in-place.

```json
{
  "type" : "ssh",
  "gateway" : "f0ec68aa-63f5-405c-b178-9a4454556d6b",
  "host" : "myip.eu-central-1.compute.amazonaws.com",
  "port" : 22,
  "identity" : {
    "type" : "inPlace",
    "identityStore" : {
      "type" : "localIdentity",
      "username" : "User",
      "password" : {
        "secret" : {
          "type" : "locked",
          "encryptedValue" : "PTSOUnuY4eNTakHvnhZdbPuxBwYLD3FtUl-V_AL_W0jVVrdGeJtTntcHjrXK8aXqv4_eRYE3HkBKSosBWFOrEkygWMbqTrjwUlFyG8O0htvnsuSJdkPqoYA8bEbOgcdk_PbeSWEWqlODHNnx9f-c3PSh4zas57AycebWoIYPZx1wgQdZ2HdBtlFhpn3HL25CbvL8woPH8S7FDqN1C0x7cdujMKlynMKIZ2qg"
        },
        "encryptedToken" : {
          "token" : "5wuy5IADZvzjAl0IKurM66C6SMZsOuhStsdX8nGZvg=="
        }
      },
      "sshIdentity" : {
        "secret" : {
          "type" : "locked",
          "encryptedValue" : "zPcMsYaHh9n0QcTdliQ94PQAV4mdAGnIz8N_OcVC58-f7F9shDUDIUTqL0PFSAoewpzM"
        },
        "encryptedToken" : {
          "token" : "5wuy5IADZvzjAl0IKurM66C6SMZsOuhStsdX8nGZvg=="
        }
      }
    }
  },
  "dontInteractWithSystem" : false,
  "forwardX11" : false,
  "jumpServer" : false,
  "additionalOptions" : null
}
```

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

### Install XPipe for All Users with Winget

Source: https://github.com/xpipe-io/docs/blob/master/content/guide/managed-installation.mdx

Installs XPipe for all users on the machine, requiring Administrator privileges.

```bash
winget install xpipe-io.xpipe --source winget --scope machine
```

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

### Install XPipe on Arch Linux using yay

Source: https://github.com/xpipe-io/docs/blob/master/content/guide/installation.mdx

This command uses the 'yay' AUR helper to install the XPipe package on Arch Linux. It's a convenient alternative to manual installation.

```bash
yay -S xpipe
```

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

### Install PowerShell on Windows

Source: https://github.com/xpipe-io/docs/blob/master/content/guide/file-browser.mdx

If you frequently transfer large files via Windows systems, installing pwsh can improve transfer speeds. Use winget to install it.

```bash
winget install -e --id Microsoft.PowerShell
```

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

### Run XPipe Development Server

Source: https://github.com/xpipe-io/docs/blob/master/README.md

Commands to start the development server for the XPipe documentation site using npm, pnpm, or yarn.

```bash
npm run dev
# or
pnpm dev
# or
yarn dev
```

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

### JSON Output Example 2

Source: https://github.com/xpipe-io/docs/blob/master/content/guide/password-manager.mdx

Example JSON output from a custom command, containing private and public SSH key fields.

```json
{
  "priv": "...",
  "pub": "..."
}
```

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

### Install XPipe for Current User with Winget

Source: https://github.com/xpipe-io/docs/blob/master/content/guide/managed-installation.mdx

Installs XPipe for the current user using the winget package manager.

```bash
winget install xpipe-io.xpipe --source winget
```

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

### Start and Execute Commands via XPipe Python API

Source: https://github.com/xpipe-io/docs/blob/master/content/guide/connection-launch.mdx

This Python script demonstrates how to use the XPipe client to start a non-interactive shell session, execute commands, and retrieve their output. It also shows how to extract information like SSH version.

```python
from xpipe_api import Client
import re

client = Client()

connection = "f0ec68aa-63f5-405c-b178-9a4454556d6b"

# This will start a shell session for the connection
# Note that this session is non-interactive, meaning that password prompts are not supported
shell_info = client.shell_start(connection)

# The shell dialect of the shell. For example cmd, powershell, bash, etc.
dialect = shell_info["shellDialect"]
# The operating system type of the system. For example, windows, linux, macos, bsd, solaris
osType = shell_info["osType"]
# The display name of the operating system. For example Windows 10 Home 22H2
osName = shell_info["osName"]

# Prints {'exitCode': 0, 'stdout': 'hello world', 'stderr': ''}
print(client.shell_exec(connection, "echo hello world"))

# Prints {'exitCode': 0, 'stdout': '<user>', 'stderr': ''}
print(client.shell_exec(connection, "echo $USER"))

# Prints {'exitCode': 127, 'stdout': 'invalid: command not found', 'stderr': ''}
print(client.shell_exec(connection, "invalid"))

# Extract ssh version from system
version_format = re.compile(r'[0-9.]+')
ret = client.shell_exec(connection, "ssh -V")
ssh_version = version_format.findall(ret["stderr"])[0]

# Clean up after ourselves by stopping the shell session
client.shell_stop(connection)
```

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

### SSH Connection Schema Example (Reference)

Source: https://github.com/xpipe-io/docs/blob/master/content/guide/python-api.mdx

An example of an SSH connection schema that references an existing identity.

```json
{
  "type" : "ssh",
  "gateway" : "f0ec68aa-63f5-405c-b178-9a4454556d6b",
  "host" : "myip.eu-central-1.compute.amazonaws.com",
  "port" : 22,
  "identity" : {
    "type" : "ref",
    "ref" : "34c7ea9a-b00d-45e1-a324-78ef0750acc2"
  },
  "dontInteractWithSystem" : false,
  "forwardX11" : false,
  "jumpServer" : false,
  "additionalOptions" : null
}
```

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

### Start and Execute Shell Commands

Source: https://github.com/xpipe-io/docs/blob/master/content/guide/python-api.mdx

Starts a non-interactive shell session and executes a command. Retrieves shell dialect and OS information.

```python
shell_info = client.shell_start(connection)

# The shell dialect of the shell. For example cmd, powershell, bash, etc.
dialect = shell_info["shellDialect"]
# The operating system type of the system. For example, windows, linux, macos, bsd, solaris
osType = shell_info["osType"]
# The display name of the operating system. For example Windows 10 Home 22H2
osName = shell_info["osName"]

# Prints {'exitCode': 0, 'stdout': 'hello world', 'stderr': ''}
print(client.shell_exec(connection, "echo hello world"))

# Prints {'exitCode': 0, 'stdout': '<user>', 'stderr': ''}
print(client.shell_exec(connection, "echo $USER"))

# Prints {'exitCode': 127, 'stdout': 'invalid: command not found', 'stderr': ''}
print(client.shell_exec(connection, "invalid"))
```

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

### Install XPipe for All Users with Scoop

Source: https://github.com/xpipe-io/docs/blob/master/content/guide/managed-installation.mdx

Installs XPipe for all users on the machine using Scoop with the --global option, requiring Administrator privileges.

```bash
scoop install extras/xpipe --global
```

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

### Install XPipe for All Users with Chocolatey

Source: https://github.com/xpipe-io/docs/blob/master/content/guide/managed-installation.mdx

Installs XPipe for all users on the machine using Chocolatey, requiring Administrator privileges.

```bash
choco install xpipe --install-arguments="'ALLUSERS=1'"
```

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

### Install XPipe for Current User with Chocolatey

Source: https://github.com/xpipe-io/docs/blob/master/content/guide/managed-installation.mdx

Installs XPipe for the current user using the Chocolatey package manager.

```bash
choco install xpipe
```

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

### Example: Retrieve Username and Password from Hashicorp Vault

Source: https://github.com/xpipe-io/docs/blob/master/content/guide/password-manager.mdx

Example of retrieving username and password fields from a Hashicorp Vault secret. Assumes the secret is stored at '/secret/data/creds' with fields 'myusername' and 'mypassword'.

```text
/secret/data/creds?user=myusername&pass=mypassword
```

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

### Install XPipe on Linux using a script

Source: https://github.com/xpipe-io/docs/blob/master/content/guide/installation.mdx

This command downloads and executes a script to automatically install XPipe on Linux systems. It supports multiple package managers like apt, dnf, yum, zypper, rpm, and pacman.

```bash
bash <(curl -sL https://github.com/xpipe-io/xpipe/raw/master/get-xpipe.sh)
```

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

### Install XPipe for Current User with Scoop

Source: https://github.com/xpipe-io/docs/blob/master/content/guide/managed-installation.mdx

Installs XPipe for the current user using the Scoop package manager after enabling the 'extras' bucket.

```bash
scoop install extras/xpipe
```

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

### XPipe Daemon Startup Message

Source: https://github.com/xpipe-io/docs/blob/master/content/cli/index.mdx

This message appears when the XPipe daemon starts for the first time or when it needs to be initiated before executing a command. It indicates the daemon is starting and shows a progress indicator.

```bash
Starting XPipe daemon ...
[ - ] 1s
```

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

### Install XPipe on Arch Linux manually

Source: https://github.com/xpipe-io/docs/blob/master/content/guide/installation.mdx

This snippet shows how to manually install the XPipe AUR package on Arch Linux. It involves cloning the AUR repository, navigating into the directory, and running makepkg.

```bash
git clone https://aur.archlinux.org/packages/xpipe
cd xpipe
makepkg -sirc
```

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

### Example Action Schema

Source: https://github.com/xpipe-io/docs/blob/master/content/guide/actions.mdx

This JSON represents the schema for opening a local machine connection in a terminal. It includes a reference and an action ID.

```json
{
  "ref" : "f0ec68aa-63f5-405c-b178-9a4454556d6b",
  "id" : "open"
}
```

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

### Example: Retrieve SSH Keys from Hashicorp Vault

Source: https://github.com/xpipe-io/docs/blob/master/content/guide/password-manager.mdx

Example of retrieving SSH private and public keys from a Hashicorp Vault secret. Assumes the secret is stored at '/secret/data/creds' with fields 'priv' and 'pub'.

```text
/secret/data/creds?private-key=priv&public-key=pub
```

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

### Enable DRI3 GPU Acceleration

Source: https://github.com/xpipe-io/docs/blob/master/content/guide/webtop.mdx

Mount the DRI devices to the container to enable hardware acceleration for improved performance. This example mounts the /dev/dri directory.

```bash
--device /dev/dri:/dev/dri
```

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

### Proxmox VM Connection Error: Guest Agent Not Running

Source: https://github.com/xpipe-io/docs/blob/master/content/guide/proxmox.mdx

This error indicates that the QEMU guest agent is not running within the VM. Ensure the VM is fully started and the agent is installed and initialized.

```text
Process returned exit code 255:
QEMU guest agent is not running

Is the VM fully started up yet?
```

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

### Example MCP Prompt: List Files

Source: https://github.com/xpipe-io/docs/blob/master/content/guide/mcp.mdx

Use this prompt to test the MCP server by listing files on the local machine. The agent should automatically detect and use the XPipe MCP server's 'list_files' tool.

```plaintext
List files of directory C:\ on system local machine (if on Windows)
List files of directory / on system local machine (otherwise)
```

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

### Launch Connections with Windows Terminal Profiles

Source: https://github.com/xpipe-io/docs/blob/master/content/guide/connection-launch.mdx

Example of using Windows Terminal (`wt`) commands to launch multiple XPipe connections in a predefined split-pane layout. This allows for custom terminal configurations.

```bash
wt -w 1 sp xpipe launch "local machine"
wt -w 1 sp xpipe launch "archlinux"
wt -w 1 sp xpipe launch "ubuntu-24.04"
```

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

### Install XPipe Silently on macOS

Source: https://github.com/xpipe-io/docs/blob/master/content/guide/managed-installation.mdx

Downloads and installs the macOS package silently using the command line. Requires curl and the installer command.

```bash
curl --output xpipe-installer-macos-arm64.pkg https://github.com/xpipe-io/xpipe/releases/latest/download/xpipe-installer-macos-arm64.pkg
sudo installer -verboseR -pkg xpipe-installer-macos-arm64.pkg -target /
```

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

### Initialize a Local Bare Git Repository

Source: https://github.com/xpipe-io/docs/blob/master/content/guide/sync.mdx

Use this command to initialize a bare Git repository on your local machine. The `--bare` option is crucial for pushing data to it.

```bash
cd <external repo dir>
git init --bare
```

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

### Build Xpipe Webtop Docker Image Locally

Source: https://github.com/xpipe-io/docs/blob/master/content/guide/webtop.mdx

Build the Xpipe Webtop Docker image locally using the cloned repository. Use --no-cache and --pull for a clean build.

```bash
docker build \
  --no-cache \
  --pull \
  .
```

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

### Connect to XPipe with Default Client

Source: https://github.com/xpipe-io/docs/blob/master/content/guide/python-api.mdx

Instantiate the synchronous XPipe client. By default, it reads credentials from 'xpipe_auth' and connects to localhost.

```python
from xpipe_api import Client

client = Client()
```

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

### Launch Ambiguous Connections from Terminal

Source: https://github.com/xpipe-io/docs/blob/master/content/guide/connection-launch.mdx

Demonstrates various ways to launch the 'ubuntu-24.04' WSL instance using partial names and glob patterns. Ensure the name is unambiguous to avoid launch failures.

```bash
xpipe launch "local machine/wsl distributions/ubuntu-24.04"
```

```bash
xpipe launch "*/wsl distributions/ubuntu-24.04"
```

```bash
xpipe launch "*/wsl*/ubuntu-24.04"
```

```bash
xpipe launch "*/*/ubuntu-24.04"
```

```bash
xpipe launch "**/ubuntu-24.04"
```

```bash
xpipe launch "ubuntu-24.04"
```

```bash
xpipe launch "ubuntu-*"
```

```bash
xpipe launch "ubuntu-"
```

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

### Quick Jump to File

Source: https://github.com/xpipe-io/docs/blob/master/content/guide/file-browser.mdx

Type the initial characters of a file name to quickly navigate to it. The jump becomes unambiguous as more characters are typed.

```text
Type the start of a file name to jump to it.
```

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

### Connect to XPipe with Async Client

Source: https://github.com/xpipe-io/docs/blob/master/content/guide/python-api.mdx

Instantiate the asynchronous XPipe client. All operations with this client are run asynchronously. Remember to run the async main function.

```python
import asyncio
from xpipe_api import AsyncClient

async def main():
    client = AsyncClient()

    # Do your stuff async

if __name__ == "__main__":
    asyncio.run(main())
```

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

### Launch Connection from Terminal

Source: https://github.com/xpipe-io/docs/blob/master/content/guide/connection-launch.mdx

Use the `xpipe launch` command to open a new shell session for a specified connection. You can use the full or partial connection name, and glob patterns are supported for flexibility.

```bash
xpipe launch <connection name>
```

```bash
xpipe launch <connection name> -- <arg1> ... <argn>
```

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

### Create and Execute Script

Source: https://github.com/xpipe-io/docs/blob/master/content/guide/python-api.mdx

Creates an executable script on the remote system from a blob and then executes it.

```python
# You can do the same with script files as well
# This will create an executable script in the system's temp directory
script_write_content = "echo hello\necho world"
blob_script_id = client.fs_blob(file_write_content)
script_path = client.fs_script(connection, blob_script_id)

# You can then use this script for your commands
# Prints {'exitCode': 0, 'stdout': 'hello\nworld', 'stderr': ''}
print(client.shell_exec(connection, "\"" + script_path + "\""))
```

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

### Quiet MSI Installation for All Users with PowerShell

Source: https://github.com/xpipe-io/docs/blob/master/content/guide/managed-installation.mdx

Installs the XPipe MSI package quietly for all users using PowerShell with Administrator privileges. Detects architecture automatically.

```powershell
$RawArch = [System.Runtime.InteropServices.RuntimeInformation,mscorlib]::OSArchitecture.ToString().ToLower();
$Arch = If ($RawArch -eq "x64") {"x86_64"} Else {"arm64"}
Start-Process -Verb runAs -FilePath "msiexec.exe" -ArgumentList "/i \"https://github.com/xpipe-io/xpipe/releases/latest/download/xpipe-installer-windows-$($Arch).msi\" /qn ALLUSERS=1" -Wait -PassThru
```

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

### Quiet MSI Installation for Current User with PowerShell

Source: https://github.com/xpipe-io/docs/blob/master/content/guide/managed-installation.mdx

Installs the XPipe MSI package quietly for the current user using PowerShell. Detects architecture automatically.

```powershell
$RawArch = [System.Runtime.InteropServices.RuntimeInformation,mscorlib]::OSArchitecture.ToString().ToLower();
$Arch = If ($RawArch -eq "x64") {"x86_64"} Else {"arm64"}
Start-Process -FilePath "msiexec.exe" -ArgumentList "/i \"https://github.com/xpipe-io/xpipe/releases/latest/download/xpipe-installer-windows-$($Arch).msi\" /qn" -Wait -PassThru
```

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

### Docker CLI Command for XPipe Webtop

Source: https://github.com/xpipe-io/docs/blob/master/content/guide/webtop.mdx

This command deploys the XPipe Webtop container using the Docker CLI. It mirrors the settings found in the Docker Compose example, including detached mode, name, environment variables, capabilities, port mappings, volume mounts, restart policy, and image.

```bash
docker run -d \
  --name=xpipe-webtop \
  -e SUBFOLDER=/ `#optional, to run in a subfolder reverse proxy` \
  --cap-add=NET_ADMIN `#optional, to enable tailscale` \
  --privileged `#optional, to enable tailscale` \
  -p 127.0.0.1:3000:3000 \
  -p 127.0.0.1:3001:3001 \
  -v /path/to/data:/config \
  -v /var/run/docker.sock:/var/run/docker.sock `#optional, to access host containers` \
  --restart unless-stopped \
  ghcr.io/xpipe-io/xpipe-webtop:latest
```

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

### POST /shell/start

Source: https://github.com/xpipe-io/docs/blob/master/content/api/shell-start.mdx

Starts a new shell session for a connection. If an existing shell session is already running for that connection, this operation will do nothing. Note that there are a variety of possible errors that can occur here when establishing the shell connection. These errors will be returned with the HTTP return code 500.

```APIDOC
## POST /shell/start

### Description
Starts a new shell session for a connection. If an existing shell session is already running for that connection, this operation will do nothing.

Note that there are a variety of possible errors that can occur here when establishing the shell connection.

These errors will be returned with the HTTP return code 500.

### Method
POST

### Endpoint
/shell/start

### Response
#### Success Response (200)
This endpoint does not explicitly define a success response body in the provided documentation. However, a successful execution implies the shell session has been initiated or is already running.

#### Error Response (500)
- **error** (string) - Description of the error that occurred during shell connection establishment.
```

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

### Get Category Info

Source: https://github.com/xpipe-io/docs/blob/master/content/api/category-info.mdx

Queries detailed information about categories.

```APIDOC
## POST /category/info

### Description
Queries detailed information about categories.

### Method
POST

### Endpoint
/category/info

### Request Example
```json
{
  "example": "request body"
}
```

### Response
#### Success Response (200)
- **field1** (type) - Description

#### Response Example
```json
{
  "example": "response body"
}
```
```

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

### Retrieve Connection Schema

Source: https://github.com/xpipe-io/docs/blob/master/content/guide/python-api.mdx

Get the configuration schema for a specific connection. The schema is a JSON object.

```python
from xpipe_api import Client

client = Client()

# The connection reference to the connection you want to expect the schema of
# If you have the HTTP API setting enabled in XPipe, you can copy the API UUID of a connection in its context menu
connection = "f0ec68aa-63f5-405c-b178-9a4454556d6b"

# The schema is just a json object
schema = client.connection_info(connections)[0]["config"]
```
Tokens:
Raw