# 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
- **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.

## Running in the Background

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

### 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

[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"
```

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).