Deutsch
Teams experimenting with multi-agent control planes
Use a VPS when multiple agents, task state, and scheduled wakeups need a shared runtime boundary.
How to Self-Host Paperclip on a VPS
This guide explains how to self-host Paperclip on a VPS so the runtime can live in a persistent remote environment instead of depending on a local machine. Virtarix provides the VPS infrastructure: NVMe storage, full root access, global locations, and an always-on server environment. You bring your own Paperclip setup, provider access, API keys, repositories, tools, and configuration.
Who This Guide Is For
This page is for users who want Paperclip experiments to run from a central VPS environment with observable agents, adapters, heartbeats, tasks, and logs.
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 supplies self-managed VPS infrastructure; you install, configure, monitor, secure, and limit Paperclip yourself.
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.
A Linux VPS, such as Ubuntu or Debian, suitable for the selected Paperclip quickstart or source-development path.
SSH access to the server.
Root or sudo access.
Basic terminal knowledge.
Git and the package managers required by Paperclip.
Docker only if your chosen deployment design explicitly uses containers; the basic quickstart and source-development paths do not require Docker by default.
Node.js and pnpm versions required by the selected Paperclip quickstart or source path, plus any extra runtimes required by the agents you connect to Paperclip.
Your own API keys, provider accounts, model access, repositories, and configuration.
A domain name and firewall rules if you expose a web interface or webhook endpoint.
Backups or snapshots before production use or major upgrades.
Choose the Paperclip Runtime Path
Before running commands, decide how Paperclip should be installed, updated, restarted, and recovered on the VPS. Use current upstream documentation as the authority for exact versions and flags.
Recommended VPS Requirements
Minimum starting point for a test environment:
Recommended Architecture
The VPS is the runtime layer. You connect over SSH, configure Paperclip, keep logs and runtime state on the server, and control API or model provider access yourself. For sizing context, return to Paperclip VPS hosting before moving from test to production use.
User
Operator or developer controlling the workflow.
SSH
Secure access into the server.
Virtarix VPS
Runtime, storage, network, and package layer.
Paperclip runtime
Paperclip server, UI, agent registry, heartbeats, budgets, tasks, and adapter boundary for the workflow.
API/model provider
External model access and provider credentials.
Repositories, tools, and integrations
Code, automation tools, messaging gateways, and webhooks.
Step-by-Step Setup Flow
Follow this sequence as a practical deployment checklist, but confirm Paperclip-specific versions, installer flags, 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 -yLog back in as the non-root user before continuing if your security policy requires it.
adduser deployusermod -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 gnupgPaperclip documents an npx onboard quickstart plus a repository development path with Node.js 20+ and pnpm 9.15+. Choose the path that matches your deployment model.
# Paperclip quickstart path from current public READMEnpx paperclipai onboard --yesnpx paperclipai run# Source development path onlygit clone https://github.com/paperclipai/paperclip.gitcd paperclippnpm installpnpm devFor 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. For source checkouts, use the repository-documented development commands for secrets and strict-mode settings.
# Quickstart path after onboardingnpx paperclipai configure# Source checkout path documented for development secrets configurationpnpm paperclipai configure --section secretsStart Paperclip with the same path you used for setup. The quickstart path should continue with the Paperclip CLI run command; the repository development path should use the documented development command for development validation only.
# Quickstart pathnpx paperclipai run# Source development path only; do not treat this as a production service wrapperpnpm 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 npx paperclipai run, then place that command behind a service manager only after config, bind mode, authentication, and secret storage are understood. For a source checkout, keep pnpm dev clearly labeled as development-only and separated from any production service wrapper.
npx paperclipai run# or, from a development-only source checkoutpnpm 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.
Why Paperclip Benefits from a VPS
Paperclip benefits from a VPS because server, UI, adapters, heartbeats, tasks, and logs should be reachable in one place when multiple agents or scheduled wakeups are involved.
Central multi-agent runtime
Keep the Paperclip server, UI, agent state, adapters, 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, 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.
Paperclip AI use-case article
Read the Paperclip AI article for feature context, practical workloads, and VPS-hosting fit before you choose the setup path.
More AI VPS use-case articles
Compare adjacent AI agent frameworks when you want broader context before choosing a VPS runtime or setup guide.
Security Basics for Paperclip on a VPS
Treat the Paperclip server as a privileged runtime. Security should be part of the setup, not a later cleanup task.
Use SSH keys where possible.
Keep root login limited.
Use a non-root user where practical.
Restrict ports.
Store secrets in environment variables or a secret manager.
Avoid committing .env files.
Review Paperclip app logs, UI/API access, agent heartbeat history, adapter activity, budget changes, and server authentication logs.
Keep packages updated.
Snapshot before major Paperclip changes.
Monitor failed login attempts.
Rotate exposed keys.
Keep experiments separate from production systems.
Privileged runtime
The server can contain agent adapters, heartbeats, company state, UI/API services, credentials, and run logs. Harden it before production use.
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 npx 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.
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.
Ready to run Paperclip on an always-on VPS?
Deploy a Paperclip VPS and use this guide as your review checklist while you prepare the setup.
FAQ
Can I run Paperclip on a VPS?
Yes, if the Paperclip release supports the Linux distribution and runtime path you choose. 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 Paperclip 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 Paperclip with the recommended Virtarix Cloud VPS S for a practical first deployment, then scale after measuring CPU, RAM, storage, and process count for agent adapters, heartbeats, companies, UI/API services, and run logs.
Can Paperclip keep running without my local machine?
Yes, if Paperclip is run as a server-side process using a documented service or process-management method. The VPS keeps agent adapters, heartbeats, companies, UI/API services, and run logs separate from your local desktop session.
Can I use Docker for this setup?
Use Docker only when your chosen Paperclip deployment design explicitly uses containers. The basic quickstart and source-development paths should stay on their documented commands unless you deliberately build and secure a containerized wrapper.
Is Virtarix operating Paperclip for me?
No. Virtarix supplies self-managed VPS infrastructure. You install, configure, update, monitor, and secure Paperclip yourself.