DEV Community

Arpan Dhara
Arpan Dhara

Posted on

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

#ai #cloud #devops #docker

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.

Table of Contents

  1. Architecture Overview
  2. Prerequisites
  3. Network & Firewall Configuration
  4. Generate Application Secrets
  5. Coolify Service Configuration
  6. Bootstrap the First Admin Account
  7. Complete Initial Onboarding
  8. Configure OpenRouter
  9. Verification
  10. Troubleshooting
  11. Security & Production Checklist

Architecture Overview

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

Request flow 

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
Enter fullscreen mode Exit fullscreen mode

Prerequisites

Before starting, make sure you have:

  • An Oracle Cloud account.
  • An OCI Ampere A1 ARM64 VPS.
  • Ubuntu installed on the VPS.
  • Coolify installed and accessible.
  • A domain/subdomain you control.
  • DNS access for that domain.
  • An OpenRouter account and API key.
  • SSH access to the VPS.
  • Ports 80 and 443 available for web traffic.

1. Network & Firewall Configuration

A. DNS Configuration

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
Enter fullscreen mode Exit fullscreen mode

This guide uses:

https://yourDomain.com
Enter fullscreen mode Exit fullscreen mode

Verify DNS

From your local machine:

nslookup yourDomain.com
Enter fullscreen mode Exit fullscreen mode

or:

dig yourDomain.com
Enter fullscreen mode Exit fullscreen mode

The returned IP should match your Oracle Cloud VPS public IPv4 address.

B. Oracle Cloud VCN Security Rules

Log in to the Oracle Cloud Console.

Navigate to:

Networking
  → Virtual Cloud Networks
    → Your VCN
      → Security Lists
        → Default Security List
Enter fullscreen mode Exit fullscreen mode

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.

Why both ports?

  • 80/tcp is commonly used by Let's Encrypt HTTP-01 validation and HTTP-to-HTTPS redirects.
  • 443/tcp is used for HTTPS traffic.

C. Host Firewall (Ubuntu IPTables)

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
Enter fullscreen mode Exit fullscreen mode

Install persistent firewall-rule support:

sudo apt-get update
sudo apt-get install -y iptables-persistent netfilter-persistent
Enter fullscreen mode Exit fullscreen mode

Save the rules:

sudo netfilter-persistent save
Enter fullscreen mode Exit fullscreen mode

Verify:

sudo iptables -L INPUT -n --line-numbers
Enter fullscreen mode Exit fullscreen mode

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.

2. Generate Application Secrets

Generate a secure 32-byte hexadecimal secret on the VPS:

openssl rand -hex 32
Enter fullscreen mode Exit fullscreen mode

Example output:

9b7c0f...64-character-secret...e21a
Enter fullscreen mode Exit fullscreen mode

Save the complete 64-character value securely.

This value will be used as:

BETTER_AUTH_SECRET
Enter fullscreen mode Exit fullscreen mode

Do not publish it or commit it to Git.

3. Coolify Service Configuration

A. Create Docker Compose Resource

Open your Coolify Dashboard.

Navigate to:

Project
  → + New
    → Docker Compose
Enter fullscreen mode Exit fullscreen mode

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:
Enter fullscreen mode Exit fullscreen mode

Important

If you use a different domain, update:

PAPERCLIP_PUBLIC_URL: "https://yourDomain.com"
Enter fullscreen mode Exit fullscreen mode

to your actual public URL.

For example:

PAPERCLIP_PUBLIC_URL: "https://yourDomain.com"
Enter fullscreen mode Exit fullscreen mode

B. Add Environment Variables

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
Enter fullscreen mode Exit fullscreen mode

Generate a strong PostgreSQL password

You can generate one with:

openssl rand -base64 32
Enter fullscreen mode Exit fullscreen mode

Use the generated value for:

POSTGRES_PASSWORD
Enter fullscreen mode Exit fullscreen mode

Environment-variable example

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
Enter fullscreen mode Exit fullscreen mode

C. Configure Domain & Port Mapping

Open the Domains tab in the Coolify service view.

Click:

+ Add Domain
Enter fullscreen mode Exit fullscreen mode

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.

D. Deploy the Stack

Click Deploy in the top-right corner of Coolify.

Coolify should:

  1. Pull the required container images.
  2. Start PostgreSQL.
  3. Wait for the PostgreSQL health check.
  4. Start Paperclip.
  5. Apply the application's database setup/migrations as required by the image.
  6. Configure Traefik routing.
  7. Request/provision a Let's Encrypt certificate.
  8. Serve Paperclip over HTTPS.

After deployment, visit:

https://yourDomain.com
Enter fullscreen mode Exit fullscreen mode

4. Bootstrapping First Admin (CEO) Account

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.

Open the Container Terminal

In Coolify:

Observe & troubleshoot
  → Terminal
Enter fullscreen mode Exit fullscreen mode

Select the:

paperclip
Enter fullscreen mode Exit fullscreen mode

container.

Fix Internal Volume Permissions

Run:

chown -R node:node /paperclip
chmod -R 700 /paperclip/instances/default/secrets
Enter fullscreen mode Exit fullscreen mode

Then generate the CEO bootstrap URL:

su -s /bin/sh node -c "pnpm paperclipai auth bootstrap-ceo"
Enter fullscreen mode Exit fullscreen mode

The command should output a single-use URL similar to:

https://yourDomain.com/auth/claim?token=...
Enter fullscreen mode Exit fullscreen mode

Open that URL in your browser.

Complete the administrator registration:

  • Name
  • Email
  • Password

Treat the bootstrap URL as a credential. Do not post it publicly or commit it to source control.

5. Completing Initial Onboarding

During the Paperclip onboarding wizard, you may see a screen asking you to connect a model with Claude and OpenAI buttons.

Do not enter the OpenRouter API key into those fields

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
Enter fullscreen mode Exit fullscreen mode

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.

6. OpenRouter Integration & Agent Configuration

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.

A. Store the OpenRouter API Key

From the Paperclip workspace:

Company name
  → Company Settings
Enter fullscreen mode Exit fullscreen mode

Alternatively, navigate to:

/company/settings/secrets
Enter fullscreen mode Exit fullscreen mode

Click:

+ New secret
Enter fullscreen mode Exit fullscreen mode

Configure:

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-...
Enter fullscreen mode Exit fullscreen mode

Click Save.

B. Bind the Secret to the CEO Agent

In the left navigation:

Agents
  → CEO
  → Secrets & variables
Enter fullscreen mode Exit fullscreen mode

Under:

API ACCESS (NO ENV VAR)
Enter fullscreen mode Exit fullscreen mode

add:

OPENROUTER_API_KEY
Enter fullscreen mode Exit fullscreen mode

Click:

Save changes
Enter fullscreen mode Exit fullscreen mode

C. Set Runtime to OpenCode

Open the CEO agent settings.

Navigate to:

Harness / Runtime
Enter fullscreen mode Exit fullscreen mode

Configure:

Setting Value
Adapter type OpenCode
Model Your desired OpenRouter model slug

Examples:

openai/gpt-4o-mini
Enter fullscreen mode Exit fullscreen mode

or:

anthropic/claude-3.5-sonnet
Enter fullscreen mode Exit fullscreen mode

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.

Click:

Test again
Enter fullscreen mode Exit fullscreen mode

or:

Verify
Enter fullscreen mode Exit fullscreen mode

You should receive a successful connection result.

Then click:

Save changes
Enter fullscreen mode Exit fullscreen mode

Clear Any Existing Error Banner

If the CEO agent still shows an old failure banner:

Overview
  → Clear error
Enter fullscreen mode Exit fullscreen mode

This clears the previous runtime error state after the configuration has been corrected.

7. Verification

Navigate to:

Tasks
  → Paperclip onboarding (SKO-1)
Enter fullscreen mode Exit fullscreen mode

Send a test message such as:

Hello, please proceed with the onboarding plan.
Enter fullscreen mode Exit fullscreen mode

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
Enter fullscreen mode Exit fullscreen mode

Troubleshooting

1. Domain does not open

Check DNS:

nslookup paperclip.arpann8n.qzz.io
Enter fullscreen mode Exit fullscreen mode

Confirm that it resolves to the correct OCI public IP.

Then verify OCI ingress rules allow:

TCP 80
TCP 443
Enter fullscreen mode Exit fullscreen mode

Also inspect the Ubuntu firewall:

sudo iptables -L INPUT -n --line-numbers
Enter fullscreen mode Exit fullscreen mode

2. Let's Encrypt certificate fails

Check all of the following:

  • DNS points to the correct public IP.
  • OCI VCN allows TCP 80 and 443.
  • Ubuntu firewall allows TCP 80 and 443.
  • No other service is blocking Traefik.
  • The domain is publicly resolvable.
  • The Coolify/Traefik domain configuration is correct.

HTTP port 80 can be particularly important when using HTTP-01 certificate validation.

3. Paperclip cannot connect to PostgreSQL

Check the PostgreSQL container:

docker ps
Enter fullscreen mode Exit fullscreen mode

Inspect logs through Coolify or Docker:

docker logs <postgres-container>
Enter fullscreen mode Exit fullscreen mode

The PostgreSQL health check is:

pg_isready -U paperclip -d paperclip
Enter fullscreen mode Exit fullscreen mode

Make sure the application and database use the same:

POSTGRES_PASSWORD
Enter fullscreen mode Exit fullscreen mode

4. CEO bootstrap command fails

Inside the Paperclip container, check the volume permissions:

ls -la /paperclip
ls -la /paperclip/instances/default
ls -la /paperclip/instances/default/secrets
Enter fullscreen mode Exit fullscreen mode

Then run:

chown -R node:node /paperclip
chmod -R 700 /paperclip/instances/default/secrets
Enter fullscreen mode Exit fullscreen mode

Retry:

su -s /bin/sh node -c "pnpm paperclipai auth bootstrap-ceo"
Enter fullscreen mode Exit fullscreen mode

5. Agent reports terminal/ACP failure

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
Enter fullscreen mode Exit fullscreen mode

Use:

Adapter type: OpenCode
Enter fullscreen mode Exit fullscreen mode

and ensure:

OPENROUTER_API_KEY
Enter fullscreen mode Exit fullscreen mode

is available to the agent.

6. OpenRouter authentication fails

Verify the secret exists at the company level:

Company Settings
  → Secrets
Enter fullscreen mode Exit fullscreen mode

Confirm the key is:

OPENROUTER_API_KEY
Enter fullscreen mode Exit fullscreen mode

Then verify it is bound to:

CEO
  → Secrets & variables
Enter fullscreen mode Exit fullscreen mode

Do not confuse:

OPENROUTER_API_KEY
Enter fullscreen mode Exit fullscreen mode

with provider-specific credentials such as:

ANTHROPIC_API_KEY
OPENAI_API_KEY
Enter fullscreen mode Exit fullscreen mode

Security & Production Checklist

Before exposing the deployment to the public internet, review the following.

Secrets

  • [ ] POSTGRES_PASSWORD is strong and unique.
  • [ ] BETTER_AUTH_SECRET was generated randomly.
  • [ ] OpenRouter API key is stored as a secret.
  • [ ] Secrets are not committed to Git.
  • [ ] Example secrets in documentation are clearly marked as placeholders.

Networking

  • [ ] OCI ingress allows only the ports actually required.
  • [ ] TCP 80 is available if required for certificate validation/redirects.
  • [ ] TCP 443 is available for HTTPS.
  • [ ] PostgreSQL port 5432 is not publicly exposed.
  • [ ] Paperclip port 3100 is not publicly exposed directly when Traefik is handling ingress.

Application

  • [ ] Paperclip uses authenticated deployment mode.
  • [ ] A strong administrator password is used.
  • [ ] The bootstrap URL is treated as single-use and confidential.
  • [ ] The correct public URL is configured.
  • [ ] Persistent volumes are enabled.

Database

  • [ ] PostgreSQL data is stored in a persistent Docker volume.
  • [ ] Database backups are configured separately.
  • [ ] Database credentials are not hard-coded in Git.
  • [ ] PostgreSQL is reachable only from the internal Docker network.

OpenRouter

  • [ ] API key is stored as a secret.
  • [ ] API spending/usage limits are configured according to your needs.
  • [ ] Only required agents receive access to the API secret.
  • [ ] The selected model is currently available and supported.

Useful Commands

Generate a secure auth secret 

openssl rand -hex 32
Enter fullscreen mode Exit fullscreen mode

Generate a database password 

openssl rand -base64 32
Enter fullscreen mode Exit fullscreen mode

Check DNS 

nslookup paperclip.arpann8n.qzz.io
Enter fullscreen mode Exit fullscreen mode

Check firewall rules 

sudo iptables -L INPUT -n --line-numbers
Enter fullscreen mode Exit fullscreen mode

Allow HTTP 

sudo iptables -I INPUT 1 -p tcp --dport 80 -j ACCEPT
Enter fullscreen mode Exit fullscreen mode

Allow HTTPS 

sudo iptables -I INPUT 1 -p tcp --dport 443 -j ACCEPT
Enter fullscreen mode Exit fullscreen mode

Save firewall rules 

sudo netfilter-persistent save
Enter fullscreen mode Exit fullscreen mode

Check listening ports 

sudo ss -tulpn
Enter fullscreen mode Exit fullscreen mode

Deployment Summary

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
Enter fullscreen mode Exit fullscreen mode

Final Result

After completing the guide, the deployment should provide:

  • Public HTTPS access to Paperclip.
  • Automatic TLS termination through Coolify/Traefik.
  • Persistent PostgreSQL storage.
  • Persistent Paperclip application data.
  • Authenticated Paperclip access.
  • A bootstrapped CEO/admin account.
  • OpenRouter-backed AI inference.
  • OpenCode-based agent execution.
  • An ARM64-compatible deployment suitable for an OCI Ampere A1 VPS.

Important Notes

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:

  • Current environment variables.
  • Supported runtimes/adapters.
  • Current model identifiers.
  • Authentication/bootstrap commands.
  • API requirements.
  • ARM64 image availability.
  • Backup and upgrade procedures.

Never expose database credentials, authentication secrets, bootstrap URLs, or API keys in public repositories, screenshots, logs, or issue trackers.

Top comments (1)