Loading...
logo Portacode
Android App Log In Get Started

Pair Device

Use a short-lived pairing code to connect an existing Linux/Python-capable device to your Portacode account.

If you only want the fastest first run, you can start with One-Click Deployment Templates (no pairing required).

1. Prepare the Device

Install Python, pip, and virtual environment support:

# Debian / Ubuntu (including Proxmox/Debian hosts)
# Proxmox note: run as root or add sudo; if enterprise repos are disabled, `apt update`
# may warn/fail for those entries until repos are adjusted.
sudo apt update && sudo apt install -y python3 python3-pip python3-venv

# Fedora / RHEL / Rocky / Alma
sudo dnf install -y python3 python3-pip

# Arch
sudo pacman -Sy --needed python python-pip

# Alpine
sudo apk add python3 py3-pip py3-virtualenv

# openSUSE
sudo zypper install -y python3 python3-pip python3-virtualenv

Create a dedicated Portacode virtual environment and install the CLI:

python3 -m venv /opt/portacode-venv
/opt/portacode-venv/bin/python -m pip install --upgrade pip
/opt/portacode-venv/bin/python -m pip install --upgrade portacode

Modern Linux distros often block system-level pip install (PEP 668 / externally-managed Python). Installing Portacode in a venv avoids that issue.

If you want portacode to be available directly in shell PATH:

echo 'export PATH=/opt/portacode-venv/bin:$PATH' | sudo tee /etc/profile.d/portacode_path.sh >/dev/null
export PATH=/opt/portacode-venv/bin:$PATH

2. Generate a Pairing Code

  1. Log in to https://portacode.com and click Pair Device on the dashboard.

Pair Device button

  1. A four-digit code appears (valid for 15 minutes).

3. Connect the Device

Run portacode connect on the device using the pairing code from your dashboard. You do not need to activate the venv when using the full binary path:

/opt/portacode-venv/bin/portacode connect \
  --pairing-code 8232 \
  --device-name "My Linux Device" \
  --project-path /srv/project-one \
  --project-path /srv/project-two

4. Approve the Pairing Request

  1. A pairing request appears in your dashboard:

Pairing request card

  1. Click Approve to complete pairing.

What Next?