Bluehost Self-Managed VPS: Reimage Your Server for PaperClip Installation

Step 3: Access your Paperclip Dashboard

Now that the backend is configured, you can leave the terminal and head to your browser.

1. Open your browser and navigate to:

   http://your_server_ip:3100

2. Use the CEO credentials you generated in Step 3 to log in.

   
    

Quick Reference Guide

Now that you are up and running, use these quick reference commands to manage and maintain your platform.

Controlling the Service

Use standard system commands to control Paperclip directly from your SSH terminal:

• Check Status:

  systemctl status paperclip

• Stop Service:

  systemctl stop paperclip

• Start Service:

  systemctl start paperclip

• View Live Logs:

  journalctl -u paperclip -f

Connecting Your Code Editor

To connect your favorite IDE (VS Code, JetBrains, Neovim, etc.), point your editor's Paperclip extension directly to your server URL:

http://your-server-ip:3100

Updating to the Latest Version

Whenever you want to pull the latest features and updates from the official repository, run the following sequence:

cd /opt/paperclip/app
git pull
pnpm install
systemctl restart paperclip

Additional Information and Example Documentation Output

You can run cat /root/README.md to see more information and useful commands:

root@123456:~# cat /root/README.md
# Paperclip

## Description

Paperclip is an open-source AI orchestration platform that helps you
run teams of AI agents to automate complex tasks and workflows. It
organizes agents into structured roles with shared goals, allowing
them to collaborate and execute tasks turning individual AI tools into
a coordinated system that can manage projects and processes with
minimal manual effort.


## Services

Service       | Ports   | Purpose
--------------|---------|---------
Paperclip     | 3100    | Web UI and API
Paperclip     | 13100   | Paperclip Vite HMR
OpenSSH       | 22      | SSH

All other ports are blocked by UFW.


## What Gets Installed

| Component | Version | Notes |
|-----------|---------|-------|
| Node.js   | 20.x    | Installed via NodeSource |
| pnpm      | latest  | Global package manager |
| Paperclip | latest  | Cloned from `paperclipai/paperclip` |

Paperclip is installed to `/opt/paperclip/app` and runs as the dedicated `paperclip` system user.


## First Boot - How the VM Starts

When the VM is first booted after provisioning, a one-time cloud-init script runs automatically
(`/var/lib/cloud/scripts/per-instance/001_onboot`). It performs the following steps:

1. Detects the server's primary IP address.
2. Generates a random `BETTER_AUTH_SECRET` and writes it (along with `BETTER_AUTH_BASE_URL`) to
   a systemd drop-in at `/etc/systemd/system/paperclip.service.d/override.conf`.
3. Starts the Paperclip service and waits for it to become ready.
4. Runs the following configuration commands as the `paperclip` user:
   ```bash
   pnpm paperclipai allowed-hostname server-ip
   pnpm paperclipai context set --api-base http://server-ip:3100
   pnpm paperclipai onboard --yes
   ```
5. Restarts the service with the updated configuration.

After first boot completes, Paperclip is fully accessible from the server's external IP.

### On instance setup (run once after provisioning):

  1. Reload the service (this helps refreshing the env vars):
   ```bash
     systemctl restart paperclip
   ```

  2. Configure the server:
   ```bash
     sudo -u paperclip env HOME=/opt/paperclip bash -c \
       "cd /opt/paperclip/app && pnpm paperclipai configure"
   ```
     When prompted, use these settings:
       Section            : Server
       Reachability       : Custom
       Port               : 3100
       Auth mode          : Authenticated
       Exposure profile   : Public internet
       Bind host          : $myip
       Public base URL    : http://$myip:3100

  3. Bootstrap the CEO account:
   ```bash
     sudo -u paperclip env HOME=/opt/paperclip bash -c \
       "cd /opt/paperclip/app && pnpm paperclipai auth bootstrap-ceo"
   ```

The one-time script removes itself on completion so it does not re-run on subsequent boots.


## Message of the Day (MOTD)

On every SSH login, the MOTD displays the server IP, port, and useful commands. To remove it:

```bash
rm /etc/update-motd.d/99-paperclip
```


## Firewall

UFW is enabled with the following rules:

| Port | Protocol | Description |
|------|----------|-------------|
| 22   | TCP      | SSH (rate-limited) |
| 3100 | TCP      | Paperclip |


## How to Use

### Connect via SSH

```bash
ssh root@server-ip
```

---

### Access the Web UI

Open a browser and navigate to:

```
http://server-ip:3100
```

Create your admin account on first visit.

---

### Service Management

```bash
# Check service status
systemctl status paperclip

# Start the service
systemctl start paperclip

# Stop the service
systemctl stop paperclip

# Restart the service
systemctl restart paperclip

# Follow live logs
journalctl -u paperclip -f
```

---

### Connecting an Editor

Point your editor's Paperclip extension to the server address:

```
http://server-ip:3100
```

Refer to the [Paperclip documentation](https://github.com/paperclipai/paperclip) for
editor-specific configuration steps (VS Code, JetBrains, Neovim, etc.).

---


## File Locations

| Path | Description |
|------|-------------|
| `/opt/paperclip/app` | Paperclip application source |
| `/opt/paperclip` | Home directory for the `paperclip` system user |
| `/etc/systemd/system/paperclip.service` | Systemd service unit |
| `/etc/systemd/system/paperclip.service.d/override.conf` | Runtime env vars (IP, secrets) |
| `/etc/update-motd.d/99-paperclip` | Login message of the day |


## Updating Paperclip

To pull the latest version of Paperclip:

```bash
cd /opt/paperclip/app
git pull
pnpm install
systemctl restart paperclip
```

## Environment Variables

The service unit sets the following environment variables. Static variables are set in the service
file; runtime variables (IP-dependent or secret) are written to the drop-in override on first boot.

| Variable | Set At | Description |
|----------|--------|-------------|
| `NODE_ENV` | Build time | Node.js environment (`production`) |
| `PORT` | Build time | Port Paperclip listens on (`3100`) |
| `HOME` | Build time | Home directory for the service user (`/opt/paperclip`) |
| `HOST` | Build time | Bind address (`0.0.0.0` - all interfaces) |
| `BETTER_AUTH_SECRET` | First boot | Randomly generated authentication secret |
| `BETTER_AUTH_BASE_URL` | First boot | Server's primary IP address |

To override any variable after first boot:

```bash
systemctl edit paperclip
# Add or change Environment= lines in the [Service] section
systemctl restart paperclip
```

## Links

Documentation: [https://github.com/paperclipai/paperclip?tab=readme-ov-file#what-is-paperclip](https://github.com/paperclipai/paperclip?tab=readme-ov-file#what-is-paperclip)

Manage: [http://{server_ip}:3100](http://{server_ip}:3100)

Summary

A Paperclip application is useful when you want a simple way to handle file uploads, like images or documents, without having to build everything yourself. It manages storing and organizing files in the background, so things just work smoothly for the user.