Get up and running in minutes

Quick Start

Clone the repo, configure your environment, and start the server. That's it.

# Clone and install
git clone https://github.com/backv/workspace
cd workspace && npm install

# Configure
cp .env.example .env
# Edit .env with your settings (see Configuration below)

# Start
node server/index.js

# Open http://localhost:5300

Requirements

Workspace runs on any modern Linux server. You don't need anything exotic.

• Node.js 20+ The server is plain Node — no containerization required
• Postgres 14+ Stores projects, tabs, agents, and events — a local instance or managed DB both work
• tmux Used for persistent terminal sessions (`apt install tmux`)
• Linux Any distro — Ubuntu 22.04+ recommended
• A domain or local network access Accessed via browser, so you need to be able to reach the server

Optional but recommended: a private mesh tunnel (NetBird, Tailscale, ZeroTier) so you can reach the server from any device without exposing any ports.

Installation

Install dependencies, then copy and configure the environment file.

1. Clone the repository

git clone https://github.com/backv/workspace
cd workspace

2. Install Node dependencies

npm install

3. Install tmux (if not already installed)

# Ubuntu / Debian
sudo apt install tmux

# Arch
sudo pacman -S tmux

4. Set up Postgres

Workspace stores projects, tabs, agents, and events in a Postgres database. You'll need a running Postgres instance and a dedicated database.

# Create the database (run as the postgres user)
createdb workspace

# Or using Docker
docker run -d --name workspace-db \
  -e POSTGRES_DB=workspace \
  -e POSTGRES_PASSWORD=yourpassword \
  -p 5432:5432 postgres:16

5. Start the server

node server/index.js

# Or with pm2 for persistence
npm install -g pm2
pm2 start server/index.js --name workspace
pm2 save && pm2 startup

Configuration

All configuration is done through environment variables. Workspace has no built-in username/password — access is controlled at the network level by your private mesh or firewall. If the server is reachable, you're in.

# Server
WORKSPACE_HOST=127.0.0.1
WORKSPACE_PORT=5301

# Postgres — required
WORKSPACE_DATABASE_URL=postgresql://user:password@localhost:5432/workspace

# Where your project directories live
WORKSPACE_PROJECT_ROOTS=/home/user/projects

# Where terminals open by default
WORKSPACE_TERM_CWD=/home/user

# Data dir for tab state and clipboard images
WORKSPACE_DATA_DIR=/home/user/.workspace/data

Connecting from other devices

Once the server is running, you can reach it from any device on the same network at http://<server-ip>:5300.

Using a private mesh tunnel (recommended)

Tools like Tailscale, NetBird, or ZeroTier create an encrypted private network between your devices so you can reach the server from your phone or tablet without exposing any ports to the internet.

# Example: Tailscale
curl -fsSL https://tailscale.com/install.sh | sh
tailscale up

# Install Tailscale (or NetBird / ZeroTier) on your phone
# Sign in with the same account
# Access Workspace at http://<tunnel-ip>:5300

Using a reverse proxy

You can also put Nginx or Caddy in front of the server and expose it on a domain with HTTPS. Caddy makes this especially easy:

# Caddyfile
workspace.yourdomain.com {
    reverse_proxy localhost:5300
}

Projects

A project in Workspace maps to a directory on your server. Add a project by clicking "+ Add project" in the left sidebar and providing the path.

Projects group all your work: terminals, VS Code, git, plans, and MCP tools are all scoped to the active project. Switching projects switches context — your tabs and sessions are saved and restored automatically.

PROJECTS_ROOT/
  my-api/          ← one project
  my-frontend/     ← another project
  docs-site/       ← another project

Plans & Tickets

Each project has a built-in ticket board. Tickets are markdown files stored in the project directory under .workspace/tickets/ — no external service required.

Use the "Plan with Claude" button to have the AI analyse the codebase and generate a prioritised backlog. Tickets can be assigned to agents (Claude Code instances) which implement them automatically in the background.

• Kanban board view: To Do → Working → Needs You → Done
• Epics group related tickets with a shared progress bar
• Each ticket tracks which model and agent role implemented it
• Open a PR directly from the ticket with one click