Get up and running in minutes

Quick Start

One command on a fresh Ubuntu or macOS box installs everything (git, Node, tmux, a Postgres container), writes your config, and walks you through the prompts.

# One-line install — only needs curl + sudo
curl -fsSL https://workspaceai.dev/install.sh | bash

# …then start it in two terminals:
node server/index.js   # API on :5301
npm run dev            # UI on :5300

# Open http://localhost:5300

Prefer to do it by hand? The manual steps are below.

Requirements

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

• Node.js 22+ and git Installed for you by the one-line installer if missing (Node via nvm, no sudo)
• Postgres 14+ Stores projects, tabs, agents, and events — the installer can run it in Docker
• tmux Persistent terminal sessions — installed for you if missing
• Ubuntu / macOS Also Amazon Linux, RHEL, Fedora, Arch, Alpine
• An agent CLI (optional) Claude Code, Gemini CLI, Aider, … on your PATH to drive agents

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/backvco/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 (named volume keeps data outside the container)
docker run -d --name workspace-db \
  -e POSTGRES_DB=workspace \
  -e POSTGRES_PASSWORD=workspace \
  -p 5432:5432 \
  -v workspace-db-data:/var/lib/postgresql/data postgres:16

5. Start the API and the UI

The API serves /api and the terminal websocket on :5301; the UI runs separately on :5300 and proxies to it in dev.

# Terminal 1 — API (creates the DB schema on first start)
node server/index.js

# Terminal 2 — UI, then open http://localhost:5300
npm run dev

Configuration

Configuration is through environment variables in .env. Required values have no defaults — the server refuses to start without them. Auth is optional: off by default (front the server with a private mesh or firewall), or turn on a username/password login from the in-app Settings tab.

# 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 (defaults to <app>/data)
WORKSPACE_DATA_DIR=/home/user/.workspace/data

# The agent CLI to drive (any CLI-based LLM)
WORKSPACE_CLAUDE_BIN=claude

# Only needed if you enable auth — sign session cookies (openssl rand -hex 32)
WORKSPACE_SESSION_KEY=

# Optional embedded VS Code (code-server) URL
VITE_CODE_SERVER_URL=

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 (a domain with HTTPS)

On a public domain, one command installs Caddy and serves HTTPS with automatic, auto-renewing Let's Encrypt certificates. This runs the production build, so Caddy routes /api + /ws to the API and everything else to the UI:

./bin/setup-tls workspace.yourdomain.com

Already running nginx? Use bin/print-proxy nginx <domain> to print a config to add (then certbot) instead — it won't fight your proxy for ports 80/443.

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 stored in Workspace's Postgres database — no external service required.

Use the planning chat to have the AI analyse the codebase and generate a prioritised backlog. Tickets can be assigned to agents (a CLI coding agent such as Claude Code) which implement them automatically in a git worktree 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