RawPair™

RawPair™ is a self-hosted, real-time collaborative development environment. It enables you to spin up isolated containers with a shared terminal and code editor for effective pair (or mob) programming.

Built for fast, focused collaboration on your own infrastructure, RawPair also supports use cases like remote development, penetration testing, and red teaming, as long as it's done ethically and with proper authorization.

https://github.com/user-attachments/assets/fdbabd96-1bdf-4269-a408-7b6c11948443

Features

Collaborative code editing and shared terminal session in the browser
One container per session, fully isolated from others
Licensed under MPL v2.0

Tech Stack

RawPair is built on a modern, production-grade foundation:

Phoenix (Elixir) - handles real-time collaboration and session management
Monaco + Yjs - collaborative code editing in the browser
ttyd + tmux - shared terminal sessions
docker - isolated containers per user session
Nginx - reverse proxy and traffic routing for ttyd
PostgreSQL - workspace metadata persistence
Vector + Loki + Grafana - observability for logs and metrics
Portainer CE - (optional) convenient docker management

Supported Tech Stacks

See rawpair/stacks for all supported dev environments.

System Requirements

To run RawPair smoothly in a self-hosted environment, you'll need:

64-bit Linux host (Debian/Ubuntu recommended), works also on a Raspberry Pi and Mac OS Sequoia (Erlang and Elixir installed through Homebrew)
Docker (version 20.10+)
Docker Compose (v2+)
At least 2 CPU cores and 4 GB RAM (8 GB recommended for multiple sessions)
Persistent storage for PostgreSQL and logs
Optional (but recommended): Domain + TLS for secure public access (via Nginx or a reverse proxy)

Set up

Install Erlang and Elixir

Verify/install dependencies

Ubuntu / Debian

sudo apt update
sudo apt install -y autoconf build-essential libncurses-dev libssl-dev libgl1-mesa-dev libglu1-mesa-dev libpng-dev libssh-dev unixodbc-dev xsltproc fop libxml2-utils libncurses5-dev openjdk-17-jdk curl git

Install asdf

Follow the official instructions: https://asdf-vm.com/guide/getting-started.html

Proceed with the installation of Erlang and Elixir

asdf plugin add erlang
asdf install erlang 27.3.2
asdf set -u erlang 27.3.2

asdf plugin add elixir
asdf install elixir 1.18.3
asdf set -u elixir 1.18.3

A note on named volumes in containers

Any files saved in /home/devuser/app will persist in the associated named volume. Everything else will be discarded when the container stops.

Using the Docker images

The majority of the Docker images are available on https://hub.docker.com/u/rawpair

You need to run docker pull commands appropriately.

Quick Start (Development)

Download and customize docker-compose.yml

Basic setup, without Loki/Grafana:

networks:
  rawpair:
    name: rawpair

services:
  db:
    networks:
      - rawpair
    image: postgres:15
    container_name: rawpair_db
    restart: always
    environment:
      POSTGRES_USER: postgres
      POSTGRES_PASSWORD: postgres
      POSTGRES_DB: rawpair_dev
    volumes:
      - pgdata:/var/lib/postgresql/data
    ports:
      - "5432:5432"

  yjs:
    networks:
      - rawpair
    build:
      context: ./yjs-server
    container_name: rawpair_yjs
    environment:
      - HOST=0.0.0.0
      - PORT=1234
    ports:
      - "1234:1234"

  nginx:
    networks:
      - rawpair
    image: nginx:stable
    container_name: rawpair_nginx
    ports:
      - "8080:80"
    volumes:
      - ./nginx.conf:/etc/nginx/nginx.conf:ro

volumes:
  pgdata:

git clone https://github.com/rawpair/rawpair
cd rawpair
docker compose up -d
cd phoenix-app
mix deps.get
cd assets
npm i
cd ..
mkdir -p priv/static/assets
./dev.sh

Then open http://localhost:4000 to begin.

CLI Setup (Optional)

A prebuilt CLI tool is available in Releases. Either install via curl -sSf https://rawpair.dev/install.sh | sh or download the binary matching your platform manually.

Then run to ensure that you have Erlang and Elixir installed:

./rawpair ensureDeps

Or add flags for unsupervised installation of dependencies:

./rawpair ensureDeps --non-interactive --install-deps

Note: --install-deps requires root

Run this command, follow the instructions and at the end of the process you will have the opportunity to generate .env and .docker-compose.yml files.

./rawpair quickStart

This should get you up and running with minimal effort.

Use this if you don’t want to manually edit config files.

Tested on Ubuntu 24.04, Debian Bookwork, Fedora 42, Archlinux (20250430)

Quick Start (Production)

Set the required ENV variables, based on phoenix-app/.env.example.

Then run:

git clone https://github.com/rawpair/rawpair
cd rawpair
docker compose up -d
cd phoenix-app
./deploy.sh
./start.sh

Refer to deployment instructions/guidelines and Ansible playbooks

Important: You should generate your own SECRET_KEY_BASE

mix phx.gen.secret

Then open http://localhost:4000 to begin.

It is advisable to use a reverse proxy in production.

Environment Variables

RawPair is configured via the following environment variables. These should be defined in a .env file or passed directly into your runtime environment (e.g. Docker, systemd, or a mix phx.server session).

Core Configuration

| Variable | Description | Default | | ------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------ | ----------------- | | RAWPAIR_STACKS_VERSION | Version of stacks.json to load from the rawpair/stacks repository. Must match a Git tag or branch. | 0.1.8 | | RAWPAIR_DOCKER_PLATFORM | Target Docker platform (e.g. linux/amd64, linux/arm64). If unset, RawPair will detect the local platform using uname -m and log a warning. | (auto-detected) |

Database

| Variable | Description | Example | | -------------- | --------------------------- | ---------------------------------------------------- | | DATABASE_URL | Postgres connection string. | postgres://postgres:postgres@localhost/rawpair_dev |

Secrets & Security

| Variable | Description | Example | | ----------------- | ---------------------------------------------------------------------- | -------------------------------- | | SECRET_KEY_BASE | Phoenix secret key for session encryption. | (random 64-byte base64 string) | | CHECK_ORIGIN | Allowed CORS origins, comma-separated. Required for LiveView security. | //localhost:4000 |

Application Host

| Variable | Description | Example | | ----------------------- | ------------------------------------------------------------------------------------------ | ----------- | | PHX_HOST | Public hostname used by Phoenix. | localhost | | PORT | Port Phoenix listens on. | 4000 | | RAWPAIR_PROTOCOL | RawPair protocol (used for internal URL generation). | http | | RAWPAIR_HOST | RawPair hostname (used internally). | localhost | | RAWPAIR_PORT | RawPair application port. | 4000 | | RAWPAIR_BASE_PATH | Root path prefix for RawPair (e.g. /rawpair). Useful if reverse-proxied under a subpath. | / | | RAWPAIR_TERMINAL_HOST | Hostname of the terminal backend (e.g. ttyd). | localhost | | RAWPAIR_TERMINAL_PORT | Port of the terminal backend. | 8080 |

Grafana

| Variable | Description | Example | | ----------------------- | ------------------------------------------------------------ | ----------- | | RAWPAIR_GRAFANA_HOST | Hostname of Grafana (used for embedding metrics dashboards). | localhost | | `RAWPAIR_GRAFANA

Rawpair

Install / Use

README