Paperclip AI Deployment Guide on Oracle Cloud Linux VPS (ARM) via Coolify

A developer published a step-by-step guide for self-hosting the open-source Paperclip agent orchestration platform on an Oracle Cloud Infrastructure ARM64 VPS, using Coolify, Docker Compose, Traefik, Let's Encrypt, PostgreSQL 17, and OpenRouter. The walkthrough covers DNS A-record setup, OCI security-list ingress rules for ports 80 and 443, host-level iptables persistence, generating a 32-byte BETTER_AUTH_SECRET, and a Docker Compose stack running the ghcr.io/paperclipai/paperclip image behind Traefik on port 3100.

A complete step-by-step guide to deploy and host the open-source Paperclip agent orchestration platform on an Oracle Cloud Infrastructure OCI ARM64 VPS using Coolify, Docker Compose, Traefik, Let's Encrypt SSL, PostgreSQL, and OpenRouter . Security note: Replace all example passwords, secrets, API keys, and domain names with your own values. Never commit secrets or API keys to Git. The deployment consists of the following components: | Component | Technology | |---|---| | Host | Oracle Cloud Infrastructure OCI Ampere A1 ARM64 VPS | | Operating System | Ubuntu | | Deployment/Orchestration | Coolify | | Container Runtime | Docker | | Reverse Proxy | Traefik | | SSL | Let's Encrypt | | Database | PostgreSQL 17 Alpine | | Application | ghcr.io/paperclipai/paperclip:latest | | Domain | https://paperclip.arpann8n.qzz.io | | AI Gateway | OpenRouter API | | Agent Runtime | OpenCode | User Browser | | HTTPS :443 v Oracle Cloud VPS | v Coolify / Traefik | | HTTPS termination + routing v Paperclip :3100 | +--------------------+ | | v v PostgreSQL 17 OpenRouter API | | v v Persistent Data AI Model Provider Before starting, make sure you have: Open your DNS provider dashboard and create an A record . | Setting | Value | |---|---| | Name / Host | paperclip | | Type | A | | Target / Value | Your Oracle Cloud VPS public IPv4 address | | TTL | Automatic or 300 seconds | The resulting hostname should resolve to your VPS, for example: paperclip.example.com This guide uses: https://yourDomain.com From your local machine: nslookup yourDomain.com or: dig yourDomain.com The returned IP should match your Oracle Cloud VPS public IPv4 address. Log in to the Oracle Cloud Console. Navigate to: Networking → Virtual Cloud Networks → Your VCN → Security Lists → Default Security List Under Ingress Rules , click Add Ingress Rules . Create an inbound rule with: | Field | Value | |---|---| | Source CIDR | 0.0.0.0/0 | | Protocol | TCP | | Destination Port Range | 80,443 | | Description | Allow HTTP and HTTPS web traffic | Save the rule. Some Oracle Ubuntu images may have host-level firewall rules that prevent incoming HTTP/HTTPS traffic. Allow ports 80 and 443: Allow HTTPS 443 at the top of the INPUT chain sudo iptables -I INPUT 1 -p tcp --dport 443 -j ACCEPT Allow HTTP 80 at the top of the INPUT chain sudo iptables -I INPUT 1 -p tcp --dport 80 -j ACCEPT Install persistent firewall-rule support: sudo apt-get update sudo apt-get install -y iptables-persistent netfilter-persistent Save the rules: sudo netfilter-persistent save Verify: sudo iptables -L INPUT -n --line-numbers You should see ports 80 and 443 with target ACCEPT , preferably before any broad REJECT or DROP rule. Important: Firewall configuration can differ between Ubuntu images and OCI networking setups. Review existing rules before changing them. Generate a secure 32-byte hexadecimal secret on the VPS: openssl rand -hex 32 Example output: 9b7c0f...64-character-secret...e21a Save the complete 64-character value securely. This value will be used as: BETTER AUTH SECRET Do not publish it or commit it to Git. Open your Coolify Dashboard . Project → + New → Docker Compose Paste the following Docker Compose configuration: version: '3.8' services: db: image: postgres:17-alpine restart: unless-stopped environment: POSTGRES DB: paperclip POSTGRES USER: paperclip POSTGRES PASSWORD: ${POSTGRES PASSWORD:-postgresSecurePass123} volumes: - pgdata:/var/lib/postgresql/data healthcheck: test: "CMD-SHELL", "pg isready -U paperclip -d paperclip" interval: 5s timeout: 5s retries: 5 paperclip: image: ghcr.io/paperclipai/paperclip:latest restart: unless-stopped depends on: db: condition: service healthy environment: NODE ENV: production PORT: "3100" SERVE UI: "true" HOST: "0.0.0.0" PAPERCLIP DEPLOYMENT MODE: "authenticated" PAPERCLIP DEPLOYMENT EXPOSURE: "public" PAPERCLIP PUBLIC URL: "https://yourDomain.com" BETTER AUTH SECRET: "${BETTER AUTH SECRET}" DATABASE URL: "postgres://paperclip:${POSTGRES PASSWORD:-postgresSecurePass123}@db:5432/paperclip" PAPERCLIP SECRETS MASTER KEY FILE: "/paperclip/instances/default/secrets/master.key" OPENROUTER API KEY: "${OPENROUTER API KEY}" volumes: - paperclip-data:/paperclip volumes: pgdata: paperclip-data: If you use a different domain, update: PAPERCLIP PUBLIC URL: "https://yourDomain.com" to your actual public URL. For example: PAPERCLIP PUBLIC URL: "https://yourDomain.com" In Coolify, open the stack's Environment Variables section. Add: POSTGRES PASSWORD=<A-STRONG-RANDOM-PASSWORD BETTER AUTH SECRET=<OUTPUT-FROM-openssl-rand-hex-32 OPENROUTER API KEY=sk-or-v1-xxxxxxxxxxxxxxxxxxxx You can generate one with: openssl rand -base64 32 Use the generated value for: POSTGRES PASSWORD Do not copy these example values into production: POSTGRES PASSWORD=replace-with-your-own-password BETTER AUTH SECRET=replace-with-your-own-secret OPENROUTER API KEY=sk-or-v1-replace-with-your-own-key Open the Domains tab in the Coolify service view. Click: + Add Domain Configure: | Setting | Value | |---|---| | Service | paperclip | | Image | ghcr.io/paperclipai/paperclip:latest | | Protocol | https | | Domain | paperclip.arpann8n.qzz.io | | Port | 3100 | | Path | Leave empty | Click Save . Coolify/Traefik will use this configuration to route HTTPS traffic to Paperclip's internal port 3100 . Click Deploy in the top-right corner of Coolify. Coolify should: After deployment, visit: https://yourDomain.com Because the instance is configured with authenticated public deployment mode, browser-based self-registration is disabled. A one-time bootstrap link must be generated from inside the Paperclip container. In Coolify: Observe & troubleshoot → Terminal Select the: paperclip container. Run: chown -R node:node /paperclip chmod -R 700 /paperclip/instances/default/secrets Then generate the CEO bootstrap URL: su -s /bin/sh node -c "pnpm paperclipai auth bootstrap-ceo" The command should output a single-use URL similar to: https://yourDomain.com/auth/claim?token=... Open that URL in your browser. Complete the administrator registration: Treat the bootstrap URL as a credential. Do not post it publicly or commit it to source control. During the Paperclip onboarding wizard, you may see a screen asking you to connect a model with Claude and OpenAI buttons. Those fields may perform provider-specific API validation against Anthropic/OpenAI endpoints. An OpenRouter key is not necessarily valid for those direct-provider checks. Instead: Use subscription or skip that step if the UI provides a skip option. Continue through the remaining onboarding steps until you reach the main Paperclip workspace dashboard. Headless container environments may not provide the terminal capabilities required by some CLI-based agent runtimes. For this deployment, configure the CEO agent to use an API-based OpenCode runtime through OpenRouter. From the Paperclip workspace: Company name → Company Settings Alternatively, navigate to: /company/settings/secrets + New secret | Field | Value | |---|---| | Who provides the value? | Organization | | Type | Managed value | | Name | OPENROUTER API KEY | | Value | Your OpenRouter API key | | Key | OPENROUTER API KEY | Your API key will normally look similar to: sk-or-v1-... In the left navigation: Agents → CEO → Secrets & variables Under: API ACCESS NO ENV VAR add: OPENROUTER API KEY Save changes Open the CEO agent settings. Harness / Runtime | Setting | Value | |---|---| | Adapter type | OpenCode | | Model | Your desired OpenRouter model slug | Examples: openai/gpt-4o-mini anthropic/claude-3.5-sonnet or another model supported by your OpenRouter account and current Paperclip/OpenCode integration. Model availability, names, pricing, and provider support can change. Use a currently supported model slug from OpenRouter/Paperclip rather than assuming an older model name will remain available. Test again Verify You should receive a successful connection result. Then click: Save changes If the CEO agent still shows an old failure banner: Overview → Clear error This clears the previous runtime error state after the configuration has been corrected. Tasks → Paperclip onboarding SKO-1 Send a test message such as: Hello, please proceed with the onboarding plan. The CEO agent should process the request through the configured OpenCode runtime and OpenRouter API. A successful flow should look like: Paperclip Task | v CEO Agent | v OpenCode Adapter | v OpenRouter API | v Selected AI Model | v Response | v Paperclip Task Check DNS: nslookup paperclip.arpann8n.qzz.io Confirm that it resolves to the correct OCI public IP. Then verify OCI ingress rules allow: TCP 80 TCP 443 Also inspect the Ubuntu firewall: sudo iptables -L INPUT -n --line-numbers Check all of the following: HTTP port 80 can be particularly important when using HTTP-01 certificate validation. Check the PostgreSQL container: docker ps Inspect logs through Coolify or Docker: docker logs <postgres-container The PostgreSQL health check is: pg isready -U paperclip -d paperclip Make sure the application and database use the same: POSTGRES PASSWORD Inside the Paperclip container, check the volume permissions: ls -la /paperclip ls -la /paperclip/instances/default ls -la /paperclip/instances/default/secrets Then run: chown -R node:node /paperclip chmod -R 700 /paperclip/instances/default/secrets Retry: su -s /bin/sh node -c "pnpm paperclipai auth bootstrap-ceo" If the agent reports a terminal or ACP access failure, verify that the CEO agent is not configured to use a CLI runtime that requires an interactive terminal. Check: Agents → CEO → Harness / Runtime Use: Adapter type: OpenCode and ensure: OPENROUTER API KEY is available to the agent. Verify the secret exists at the company level: Company Settings → Secrets Confirm the key is: OPENROUTER API KEY Then verify it is bound to: CEO → Secrets & variables Do not confuse: OPENROUTER API KEY with provider-specific credentials such as: ANTHROPIC API KEY OPENAI API KEY Before exposing the deployment to the public internet, review the following. POSTGRES PASSWORD is strong and unique. BETTER AUTH SECRET was generated randomly. 5432 is 3100 is openssl rand -hex 32 openssl rand -base64 32 nslookup paperclip.arpann8n.qzz.io sudo iptables -L INPUT -n --line-numbers sudo iptables -I INPUT 1 -p tcp --dport 80 -j ACCEPT sudo iptables -I INPUT 1 -p tcp --dport 443 -j ACCEPT sudo netfilter-persistent save sudo ss -tulpn The complete deployment process is: 1. Create OCI ARM64 Ubuntu VPS ↓ 2. Point DNS A record to VPS ↓ 3. Allow TCP 80/443 in OCI VCN ↓ 4. Allow TCP 80/443 on Ubuntu firewall ↓ 5. Generate BETTER AUTH SECRET ↓ 6. Create Docker Compose stack in Coolify ↓ 7. Configure PostgreSQL + Paperclip ↓ 8. Add Coolify environment variables ↓ 9. Configure Paperclip domain → port 3100 ↓ 10. Deploy stack ↓ 11. Generate CEO bootstrap URL ↓ 12. Create administrator account ↓ 13. Complete onboarding ↓ 14. Create OPENROUTER API KEY secret ↓ 15. Bind secret to CEO agent ↓ 16. Configure OpenCode runtime ↓ 17. Select OpenRouter model ↓ 18. Verify connection ↓ 19. Send test task ↓ 20. Paperclip agent responds through OpenRouter After completing the guide, the deployment should provide: This guide is based on the configuration described in the deployment procedure. Paperclip, Coolify, OpenRouter, Docker images, model availability, and their configuration interfaces can change over time. Before production use, verify the current Paperclip and OpenRouter documentation for: Never expose database credentials, authentication secrets, bootstrap URLs, or API keys in public repositories, screenshots, logs, or issue trackers.