Skip to main content

​
Overview

This guide covers installing Rexec manually without Docker Compose. This approach gives you more control and is useful for:
  • Development environments
  • Custom deployment setups
  • Environments where Docker Compose isn’t available
  • Integration with existing infrastructure

​
Prerequisites

1

Install Go 1.24+

# Check Go version
go version
Install from https://go.dev/dl/
2

Install Node.js 22+

Required for building the frontend:
node --version
npm --version
Install from https://nodejs.org/
3

Install Docker Engine

Rexec requires access to a Docker daemon:
docker --version
Install from https://docs.docker.com/engine/install/
4

Install PostgreSQL 16+

# Ubuntu/Debian
sudo apt install postgresql postgresql-contrib

# macOS
brew install postgresql@16
5

Install Redis 7+

# Ubuntu/Debian
sudo apt install redis-server

# macOS
brew install redis

​
Database Setup

1

Create PostgreSQL Database

# Start PostgreSQL service
sudo systemctl start postgresql  # Linux
brew services start postgresql@16  # macOS

# Create database and user
sudo -u postgres psql

CREATE DATABASE rexec;
CREATE USER rexec WITH PASSWORD 'your_secure_password';
GRANT ALL PRIVILEGES ON DATABASE rexec TO rexec;
\q
2

Start Redis

# Linux
sudo systemctl start redis

# macOS
brew services start redis

# Verify Redis is running
redis-cli ping
# Should return: PONG

​
Build Rexec

1

Clone Repository

git clone https://github.com/brimblehq/rexec.git
cd rexec
2

Setup Development Environment

Run the setup script to install dependencies and create required directories:
make setup
This command:
  • Downloads Go dependencies
  • Pulls base Docker images (ubuntu, debian, arch)
  • Creates /var/lib/rexec/volumes directory
  • Copies .env.example to .env
3

Build Frontend

Build the Svelte web UI:
make ui
Or manually:
cd frontend
npm install
npm run build
cd ..
The built frontend will be in the web/ directory.
4

Build Backend

Compile the Go binary:
make build
This creates bin/rexec with the main server binary.To build everything (frontend + backend + CLI tools):
make build-all
5

Build CLI Tools (Optional)

Build the CLI, TUI, and agent binaries:
make cli-all
This creates:
  • bin/rexec-cli - Command-line interface
  • bin/rexec-tui - Terminal UI dashboard
  • bin/rexec-agent - Agent for connecting remote machines
  • bin/rexec-ssh - SSH gateway

​
Configuration

1

Create Environment File

The setup script created .env from .env.example. Edit it:
nano .env
Minimum required configuration:
.env
# Server
PORT=8080
GIN_MODE=release
BASE_URL=http://localhost:8080
REXEC_APP_URL=http://localhost:8080
REXEC_WS_HOST=localhost:8080

# Security
JWT_SECRET=your-super-secret-jwt-key-change-this-in-production
REXEC_ENCRYPTION_KEY=your-32-character-encryption-key

# Database
DATABASE_URL=postgres://rexec:your_secure_password@localhost:5432/rexec?sslmode=disable

# Redis
REDIS_URL=redis://localhost:6379

# Docker
DOCKER_HOST=unix:///var/run/docker.sock
VOLUME_PATH=/var/lib/rexec/volumes
CONTAINER_NETWORK=rexec-network

# Storage
RECORDINGS_PATH=./data/recordings
SCRIPTS_DIR=./scripts
DOWNLOADS_DIR=./downloads
2

Generate Secure Keys

Production Security: Generate secure random keys for production:
# JWT Secret (any length)
openssl rand -base64 32

# Encryption Key (must be exactly 16, 24, or 32 bytes)
openssl rand -base64 32 | cut -c1-32
3

Create Required Directories

mkdir -p data/recordings
mkdir -p downloads
sudo mkdir -p /var/lib/rexec/volumes
sudo chown -R $USER:$USER /var/lib/rexec

​
Running Rexec

1

Start the Server

Using Make:
make run
Or directly:
./bin/rexec server
The server will start on port 8080 (or your configured PORT).
2

Verify Server is Running

Check the health endpoint:
curl http://localhost:8080/health
You should see a JSON response:
{"status": "ok"}
3

Access Web Interface

Open your browser to:
http://localhost:8080
Default credentials:
  • Username: admin
  • Password: admin

​
Development Mode

For development with hot-reloading:
1

Install Air (Hot Reload)

go install github.com/air-verse/air@latest
2

Run Backend in Dev Mode

make dev
This watches for Go file changes and automatically rebuilds.
3

Run Frontend in Dev Mode

In a separate terminal:
make ui-dev
Or manually:
cd frontend
npm run dev
The Vite dev server will start on port 5173.

​
Building for Distribution

To build binaries for multiple platforms: 
# Build agent for all platforms (linux/darwin amd64/arm64)
make agent-all

# Build CLI for all platforms
make cli-all-platforms

# Build TUI for all platforms
make tui-all-platforms

# Build SSH gateway for all platforms
make ssh-gateway-all

# Build everything for distribution
make dist
Binaries will be in the downloads/ directory: 
downloads/
├── rexec-agent-linux-amd64
├── rexec-agent-linux-arm64
├── rexec-agent-darwin-amd64
├── rexec-agent-darwin-arm64
├── rexec-cli-linux-amd64
├── rexec-cli-darwin-arm64
└── ...

​
Docker Image Build

To build the Docker image manually: 
make docker-build
Or using Docker directly: 
docker build -t rexec:latest .

​
Running as a System Service

​
Systemd Service (Linux)

Create /etc/systemd/system/rexec.service: 
[Unit]
Description=Rexec - Terminal as a Service
After=network.target postgresql.service redis.service docker.service

[Service]
Type=simple
User=rexec
WorkingDirectory=/opt/rexec
EnvironmentFile=/opt/rexec/.env
ExecStart=/opt/rexec/bin/rexec server
Restart=on-failure
RestartSec=5s

[Install]
WantedBy=multi-user.target
Enable and start: 
sudo systemctl daemon-reload
sudo systemctl enable rexec
sudo systemctl start rexec
sudo systemctl status rexec

​
Makefile Commands

The Makefile provides many helpful commands: 
make help          # Show all available commands
make build         # Build the Go server binary
make build-all     # Build UI + server + CLI tools
make run           # Build and run the application
make dev           # Run with hot reload
make test          # Run tests
make test-coverage # Run tests with coverage report
make lint          # Lint the code
make fmt           # Format the code
make clean         # Clean build artifacts
make deps          # Download Go dependencies

​
Troubleshooting

​
Docker Socket Permission Denied

Add your user to the docker group: 
sudo usermod -aG docker $USER
newgrp docker

​
Port Already in Use

Change the PORT variable in .env or stop the conflicting service: 
# Find process using port 8080
sudo lsof -i :8080

​
Database Connection Failed

Verify PostgreSQL is running and credentials are correct: 
psql -U rexec -d rexec -h localhost

​
Frontend Build Fails

Clear npm cache and reinstall: 
cd frontend
rm -rf node_modules package-lock.json
npm install
npm run build

​
Next Steps

Configuration

Learn about all environment variables and advanced configuration

Docker Compose

Deploy using Docker Compose for easier management

Build docs developers (and LLMs) love

Get started for freeTalk to us