# Standalone Server

Polyscope can run as a standalone, headless server on any Linux machine. This lets you run coding agents on a remote server — a VPS, a dev box, or a CI machine — and connect to it from your browser or phone using Polyscope's remote access.

## Prerequisites

- **Linux** — x86_64 or aarch64
- **Polyscope Pro** — Required on the account you use to connect to this server. The standalone server itself is free to run; the connecting client needs Pro.
- **Git** — Required for repository management and workspace cloning
- **Claude CLI** — Required if using Claude as your coding agent ([install instructions](https://docs.anthropic.com/en/docs/claude-code))
- **Codex CLI** — Required if using OpenAI Codex as your coding agent
- **Cursor CLI** — Required if using Cursor as your coding agent ([install instructions](https://cursor.com/cli))
- **GitHub CLI** (`gh`) — Required for creating pull requests and working with GitHub issues

## Install

Run the install script to download the latest `polyscope-server` binary:

```bash
curl -fsSL https://getpolyscope.com/install/server | bash
```

This auto-detects your architecture and installs `polyscope-server` to `~/.local/bin/`. You can override the install location with the `POLYSCOPE_INSTALL_DIR` environment variable:

```bash
POLYSCOPE_INSTALL_DIR=/opt/polyscope curl -fsSL https://getpolyscope.com/install/server | bash
```

## Authenticate

Before starting the server, authenticate with your Polyscope account:

```bash
polyscope-server login
```

This starts a device code flow — you'll see a URL and a code. Open the URL in your browser on any device, sign in to your Polyscope account, and enter the code to authorize the server.

Once authenticated, your credentials are stored locally and persist across restarts.

## Start the Server

```bash
polyscope-server
```

The server registers with the Polyscope relay and appears in your [Servers](/servers) list. You can then connect to it from the Polyscope desktop app, your browser, or your phone.
Only Pro accounts can connect to standalone servers from the Servers list.

## Running in the Background

For production use, you'll want to keep `polyscope-server` running permanently using a process manager.

### Set the PATH

`polyscope-server` launches the agent binaries (`claude`, `codex`, `cursor`) and `gh` by name, so they need to be on the server's `PATH`. From your interactive shell that just works — but a background service starts with a minimal `PATH` (typically `/usr/bin:/bin`), so you have to tell it where those binaries live.

Look up the directories first:

```bash
which claude
which codex
which gh
```

Then include each one in the service's `PATH` — the examples below use `~/.local/bin`, so adjust to match your output. Run the service as the **same user** that installed and authenticated the agents, so it picks up their credentials and config.

### Using systemd

Create a systemd service file:

```bash
sudo tee /etc/systemd/system/polyscope-server.service > /dev/null <<EOF
[Unit]
Description=Polyscope Server
After=network.target

[Service]
Type=simple
User=$USER
ExecStart=$HOME/.local/bin/polyscope-server
Restart=always
RestartSec=5
Environment=HOME=$HOME
Environment=PATH=$HOME/.local/bin:/usr/local/bin:/usr/bin:/bin

[Install]
WantedBy=multi-user.target
EOF
```

Then enable and start the service:

```bash
sudo systemctl daemon-reload
sudo systemctl enable polyscope-server
sudo systemctl start polyscope-server
```

Check status with:

```bash
sudo systemctl status polyscope-server
```

### Using supervisord

Add a configuration block to your `supervisord.conf` (usually at `/etc/supervisor/conf.d/polyscope-server.conf`):

```ini
[program:polyscope-server]
command=/home/youruser/.local/bin/polyscope-server
user=youruser
autostart=true
autorestart=true
stderr_logfile=/var/log/polyscope-server.err.log
stdout_logfile=/var/log/polyscope-server.out.log
environment=HOME="/home/youruser",PATH="/home/youruser/.local/bin:/usr/local/bin:/usr/bin:/bin"
```

Then reload and start:

```bash
sudo supervisorctl reread
sudo supervisorctl update
sudo supervisorctl start polyscope-server
```

## Running Multiple Instances

You can run multiple `polyscope-server` instances on the same machine by specifying different ports and data directories:

```bash
polyscope-server --port 3100 --data-dir ~/.polyscope-project-a
polyscope-server --port 3200 --data-dir ~/.polyscope-project-b
```

- **`--port`** — The port the server listens on (defaults to the standard port)
- **`--data-dir`** — The directory where Polyscope stores its data (workspace clones, configuration, etc.)

Each instance appears as a separate server in your [Servers](/servers) list.

## Other Commands

```bash
polyscope-server status    # Check authentication and server status
polyscope-server update    # Update to the latest version
polyscope-server logout    # Remove stored credentials
```

## Updating

To update `polyscope-server` to the latest version, run:

```bash
polyscope-server update
```

Then restart the server (or the systemd/supervisor service).

## Troubleshooting

### Connected, but no agents or models appear

If the server connects and you can browse folders, but no agents show up and prompts go nowhere, the running service has a `PATH` that doesn't include the agent binaries (see [Set the PATH](#set-the-path)). Compare the service's live `PATH` against where the binaries actually live — get the PID from `systemctl status polyscope-server`, then:

```bash
# Replace 623 with your service's PID
cat /proc/623/environ | tr '\0' '\n' | grep '^PATH='
which claude
```

Add any missing directories to the service's `PATH`, then reload and restart:

```bash
sudo systemctl daemon-reload
sudo systemctl restart polyscope-server
```

### Polyscope shows an outdated Claude or Codex version

Polyscope doesn't bundle the agents — it launches whatever `claude` or `codex` binary is on the service's `PATH`. If a new agent version shipped but Polyscope still reports an old one, the binaries on the **server** are stale. Updating the desktop app or running `polyscope-server update` won't help; those update Polyscope, not the agents.

Update the agent CLIs on the server, however you installed them:

```bash
claude update                      # Claude CLI
npm install -g @openai/codex       # Codex CLI (adjust for your install method)
```

Confirm the new versions are picked up:

```bash
which claude && claude --version
which codex && codex --version
```

Then restart `polyscope-server` so new sessions launch the updated binaries:

```bash
sudo systemctl restart polyscope-server
# or, with supervisord:
sudo supervisorctl restart polyscope-server
```