Deutsch
VPS plan
Starter VPS Includes 3 CPU cores, 6 GB RAM, 50 GB NVMe storage, Unlimited bandwidth, subject to plan terms, 1 free snapshot, 1 backup included, IPv4 + IPv6.
How to Self-Host Paperclip on a VPS
This guide shows how to self-host Paperclip on a self-managed VPS so the server, UI, adapters, heartbeats, tasks, and logs can run from a persistent remote environment instead of a workstation. Virtarix provides the VPS infrastructure. You install, configure, secure, update, and operate the software you run on it. Each VPS/VDS plan includes 1 free snapshot and 1 backup. You bring Paperclip, provider accounts, API keys, repositories, model access, monitoring, updates, and security configuration, and you should verify exact Paperclip commands against the current upstream docs before production changes.
20% welcome offer
$4.40/mo for first 3 months (then $5.50)
Paperclip Control Panel
Server Online
root@paperclip-vps:~$ paperclipai run --server --heartbeat
> ✓ Paperclip server online. Heartbeats active.
Paperclip Ready
Paperclip Server UI and adapters
Task Runtime Agent work queue
Heartbeat Checks Runtime status
Provider Access Model accounts
Protected Config API keys
Persistent Logs Task evidence
Snapshots + Backups Rollback point
Firewall Rules Only needed ports
Recommended Quick Setup
Use this path when you want the shortest practical route from VPS order to a usable Paperclip server workspace. It keeps the first deployment private by default, then lets you choose LAN, tailnet, reverse-proxy, or authenticated access deliberately. The full checklist below expands each step.
Who This Guide Is For
This page is for users who want Paperclip experiments or team workflows to run from a central VPS environment with observable agents, adapters, heartbeats, tasks, and logs.
Teams experimenting with multi-agent control planes
Use a VPS when multiple agents, task state, and scheduled wakeups need a shared runtime boundary.
Operators coordinating adapters and heartbeats
Keep adapters, heartbeat schedules, process managers, and service logs in one server-side control point.
Builders who need a central dashboard and server logs
Use the VPS as the place to inspect UI state, background processes, run output, and troubleshooting evidence.
Developers who want AI agent company experiments isolated from a workstation
Virtarix provides the VPS infrastructure. You install, configure, secure, update, and operate the software you run on it.
What You Need Before You Start
Before selecting a plan or installing Paperclip, confirm the server access, runtime path, credentials, firewall exposure, and recovery routine needed for the deployment.
Use a Linux VPS suitable for the selected Paperclip quickstart, source-development, or container path, with SSH access and root or sudo access ready.
Have basic terminal knowledge plus Git, package managers, or Docker tooling required by the selected Paperclip setup path.
Install Node.js 20+ and pnpm 9.15+ for NPX or manual source paths, or use Docker for the container path. Add extra runtimes only when connected agents require them.
Use Docker or Docker Compose only when you choose Paperclip's container path; the NPX and manual source paths use Node.js and pnpm instead.
Prepare your own API keys, provider accounts, model access, repositories, configuration, domain, DNS or firewall rules, TLS or private-network plan, and a backup/restore routine before production changes.
Choose the Paperclip Runtime Path
Before running commands, decide how Paperclip should be installed, updated, restarted, and recovered on the VPS. Paperclip currently documents NPX Onboard, manual Git clone, and Docker installation paths; use current upstream documentation as the authority for exact versions and flags.
Recommended VPS Requirements
Minimum starting point for a test environment. Confirm current Paperclip prerequisites before production use:
Recommended Architecture
The VPS is the runtime layer. You connect over SSH, configure Paperclip, and control logs, state, and access. For production use, plan authenticated or private networking before exposing it to other users.
You (Operator)
You connect over SSH and control the full workflow, configuration, security, and updates.
Virtarix VPS
Provides the persistent server with storage, networking, root access, snapshots, and backups.
Paperclip Runtime
Paperclip server, UI, agents, heartbeats, tasks, database, and adapter layer running on the VPS.
External Services
API and model providers, repositories, tools, and integrations that you connect and manage.
Step-by-Step Setup Flow
Follow this sequence as a practical deployment checklist for an Ubuntu-style VPS, but confirm Paperclip-specific versions, installer flags, deployment modes, Docker files, and service commands against current official documentation before production use.
Prepare the VPS, connect over SSH, and create a clean workspace before installing Paperclip-specific dependencies.
ssh root@YOUR_SERVER_IPsudo apt update && sudo apt upgrade -yCreate a dedicated non-root deployment user for day-to-day project work, then verify that user can connect by SSH and run sudo before disabling root or password login. Reconnect as the deployment user before installing or configuring the agent when your selected runtime path stores user-scoped configuration.
# Create a dedicated non-root user for day-to-day project work
adduser deploy
usermod -aG sudo deployCreate one directory tree for Paperclip config examples, working files, logs, and backups. Keep secrets out of shell history and commit only templates, not real keys.
APP_HOME="$HOME/self-host-paperclip-on-vps-runtime"
mkdir -p "$APP_HOME/config" "$APP_HOME/workspace" "$APP_HOME/logs" "$APP_HOME/backups"
chmod 700 "$APP_HOME/config"
printf '%s\n' "# add real provider keys privately" > "$APP_HOME/config/env.example"
chmod 600 "$APP_HOME/config/env.example"Install base packages, follow the current upstream install path, and configure runtime/environment settings.
sudo apt install -y git curl wget unzip ca-certificates gnupg ufwPaperclip public materials identify a Node.js server and React UI, with agents driven through adapters and heartbeat-style execution. For NPX or manual source paths, confirm Node.js 20+ and pnpm 9.15+ before relying on the server setup; install Docker separately if you choose the container path, and review Paperclip's Docker notes for API key wiring, persistence, host binding, and public URL handling.
Paperclip documents an NPX Onboard quickstart, a manual Git clone path, and Docker deployment. Choose one path for the first test so you do not run multiple Paperclip processes on the same port. Keep the default loopback/private setup until authentication, public URL, host binding, and firewall exposure are reviewed.
# Choose ONE path for the first test; do not paste this whole block as one script.
# Option 1: NPX quickstart path from current public docs
npx paperclipai onboard --yes
paperclipai run
# Option 2: Manual Git clone path for contributors or advanced customization
git clone https://github.com/paperclipai/paperclip.git
cd paperclip
pnpm install
pnpm dev
# Option 3: Docker path from the Paperclip repository
git clone https://github.com/paperclipai/paperclip.git
cd paperclip
docker compose -f docker/docker-compose.quickstart.yml up --buildFor Paperclip, use the configuration command for the setup path you already selected. The quickstart onboarding command creates the initial configuration; do not rerun onboarding during the normal configuration step unless you are intentionally resetting or changing the bind preset. Review server exposure, bind mode, deployment mode, database, storage, public URL, allowed hosts, and provider secret handling before opening remote access.
# Inspect current config-derived environment
paperclipai env
# Reconfigure only the sections you need
paperclipai configure --section server
paperclipai configure --section database
paperclipai configure --section storage
# If the Paperclip binary is not on PATH, use npx paperclipai ... instead.Start Paperclip with the same path you used for setup. The quickstart path should continue with the Paperclip CLI run command printed by onboarding; the repository development path should use the documented development command for development validation only.
# Choose the command that matches your setup.
# NPX/onboard path after setup
paperclipai run
# If needed:
npx paperclipai run
# Use a custom config only if you created and reviewed one
paperclipai run --config /path/to/config.json
# Source development path only; do not treat this as a production service wrapper
pnpm devKeep the selected Paperclip server path observable, lock down access, test the setup, and plan ongoing maintenance.
Use the process-management path that matches the deployment you selected. For the quickstart path, first verify the Paperclip run command printed by onboarding, then place that reviewed command behind a service manager only after config, bind mode, authentication, public URL, database/storage, and secret storage are understood. For a source checkout, keep pnpm dev clearly labeled as development-only and separated from any production service wrapper.
# Choose the command that matches your setup.
paperclipai run
# If needed:
npx paperclipai run
# Or, from a development-only source checkout:
pnpm devUse SSH keys where possible, restrict password login if appropriate, enable a firewall, expose only the ports Paperclip actually needs, protect Paperclip instance config, local encryption keys, provider credentials, and database backups, keep packages updated, and use backups or snapshots before major changes. Do not open port 3100 publicly until authenticated mode, allowed hosts, public URL, private networking, or a TLS reverse proxy has been reviewed.
sudo ufw allow OpenSSH
sudo ufw enable
sudo ufw status verboseWhy Paperclip Benefits from a VPS
Paperclip benefits from a VPS because the server, UI, adapters, heartbeats, tasks, budgets, and logs should be reachable in one controlled place when multiple agents or scheduled wakeups are involved.
Central multi-agent runtime
Keep the Paperclip server, UI, agent state, adapters, database/storage path, and background services together in an always-on environment.
Observable heartbeats and tasks
Track wakeups, recurring work, process output, failures, and retries from a single server-side log trail.
Clear adapter and credential boundaries
Document adapters, credentials, allowed actions, network access, cost limits, and storage paths before connecting real work.
Controlled scaling path
Map the company structure, agents, adapters, credentials, run frequency, and storage needs before opening the system to real work. Multi-agent orchestration should be observed with logs and budgets before scaling.
Security Basics for Paperclip on a VPS
Use SSH keys where possible.
Disable password login or root login only after a working sudo user and SSH key are verified.
Use a non-root user where practical.
Restrict ports; do not expose local_trusted Paperclip mode or port 3100 publicly without reviewed authentication, allowed hosts, public URL, and TLS or private-network controls.
Store secrets in Paperclip config, environment variables, or a secret manager with restricted file permissions.
Avoid committing .env files, config files, local encryption keys, logs, or database backups.
Review Paperclip app logs, UI/API access, agent heartbeat history, adapter activity, budget changes, provider errors, and server authentication logs.
Keep packages updated.
Snapshot before major Paperclip changes and test restore steps.
Monitor failed login attempts.
Rotate exposed or stale provider keys.
Keep experiments separate from production systems and real customer data.
Privileged runtime
The server can contain agent adapters, heartbeats, company state, UI/API services, credentials, local encryption keys, database files, and run logs. Harden it before production use, and use authenticated mode or private networking before remote users connect.
Troubleshooting
Common setup problems to check before blaming the VPS or framework.
Server firewall, wrong IP, or SSH service unavailable Confirm the VPS is running, check the IP, and verify port 22 or your configured SSH port.
Wrong key, wrong user, or disabled login method
Check ~/.ssh/authorized_keys, user permissions, and your SSH config.
Base packages or runtime packages were not installed Re-run the dependency step and compare runtime versions with official Paperclip docs.
The selected Paperclip path expects a different Node.js or pnpm version Use the version manager or package source recommended by upstream docs.
Docker daemon stopped or not installed This only applies if your Paperclip deployment path uses Docker; otherwise inspect the Paperclip CLI or Node process logs instead.
Paperclip was started from an interactive shell
Verify paperclipai run or the source command first, then run that reviewed command through a service manager if you need it to survive logout.
A selected Paperclip service, dashboard, API, webhook, or supporting tool is bound to a port already used by another process
Run ss -tulpn and move one service to a different port.
A required Paperclip service, dashboard, API, webhook, or supporting tool port is not open Open only the required port, and keep all other ports restricted. Do not expose Paperclip publicly until authenticated mode, private networking, or a TLS reverse proxy is in place.
Configuration is absent or incomplete Compare the generated configuration with the selected deployment path and add only the secrets and paths required.
Key is wrong, expired, or lacks access Rotate the key through the provider and update the server configuration.
Logs, caches, repositories, or embedded database files grew over time
Check df -h, rotate logs, clean caches, back up required data, and scale storage if needed.
Too many agents, adapters, heartbeats, or background jobs Reduce concurrency, inspect process memory, and scale the VPS if the workload is valid.
When This Setup Is Not Necessary
Local testing is enough
You may not need a VPS if you are only testing Paperclip locally, working from one private machine, reviewing a small repository, or experimenting without persistent SSH access.
Server management may be unnecessary
This setup is not ideal if you do not want to manage Linux updates, SSH access, firewall rules, disk usage, credentials, or repository permissions yourself.
Use a VPS for persistent remote state
Use a VPS when the workspace, company state, logs, tools, and multi-agent workflow should stay available in a controlled remote environment.
Ready to run Paperclip on an always-on VPS?
Deploy a Paperclip VPS, keep the first setup private, and use this guide with the official Paperclip docs as your review checklist while you prepare the runtime, access controls, backups, and logs.
FAQ
Can I run Paperclip on a VPS?
Yes, if the Paperclip release supports the Linux distribution and runtime path you choose, and the deployment mode is configured safely. Use this guide together with the current official documentation.
Do I need a GPU VPS for Paperclip?
Not for the VPS runtime pattern described here. This guide focuses on the Paperclip server, React UI, adapters, heartbeats, provider access, company state, and run logs. Verify separate hardware needs if you plan local model inference.
Does Virtarix provide API keys or model access?
No. Bring your own provider accounts, credentials, API keys, model access, repositories, and framework configuration.
What VPS size should I use for Paperclip?
Start a practical test with the recommended Virtarix Starter VPS, then scale after measuring CPU, RAM, storage, and process count for agent adapters, heartbeats, companies, UI/API services, database/storage growth, and run logs.
Can Paperclip keep running without my local machine?
Yes, if Paperclip is run as a server-side process using the documented Paperclip run command and a reviewed service or process-management method. The VPS keeps agent adapters, heartbeats, companies, UI/API services, and run logs separate from your local desktop session; public access still needs reviewed authentication, allowed hosts, and network controls.
Can I use Docker for this setup?
Yes. Paperclip documents Docker as an installation method; use it when you want a containerized deployment and can manage the documented compose file, volumes, ports, secrets, public URL, updates, and backups deliberately.
Is Virtarix operating Paperclip for me?
No. Virtarix provides the VPS infrastructure. You install, configure, secure, update, and operate the software you run on it.