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 * DNS Configuration * OCI VCN Security Rules * Ubuntu Host Firewall 4. Generate Application Secrets 5. Coolify Service Configuration * Create Docker Compose Resource * Environment Variables * Domain & Port Mapping * Deploy 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 # 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 This guide uses: https://yourDomain.com ### Verify DNS From your local machine: nslookup yourDomain.com or: dig yourDomain.com 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 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 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. # 2. Generate Application Secrets 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. # 3. Coolify Service Configuration ## A. Create Docker Compose Resource Open your **Coolify Dashboard**. Navigate to: 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: ### Important 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" ## 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 ### Generate a strong PostgreSQL password You can generate one with: openssl rand -base64 32 Use the generated value for: POSTGRES_PASSWORD ### 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 ## C. Configure Domain & Port Mapping 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`. ## 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 # 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 Select the: paperclip container. ## Fix Internal Volume Permissions 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: * 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 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 Alternatively, navigate to: /company/settings/secrets Click: + New secret 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-... Click **Save**. ## B. Bind the Secret to the CEO Agent In the left navigation: Agents → CEO → Secrets & variables Under: API ACCESS (NO ENV VAR) add: OPENROUTER_API_KEY Click: Save changes ## C. Set Runtime to OpenCode Open the CEO agent settings. Navigate to: Harness / Runtime Configure: Setting | Value ---|--- Adapter type | `OpenCode` Model | Your desired OpenRouter model slug Examples: openai/gpt-4o-mini or: 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. Click: Test again or: Verify You should receive a successful connection result. Then click: Save changes ## Clear Any Existing Error Banner 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. # 7. Verification Navigate to: 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 # Troubleshooting ## 1. Domain does not open 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 ## 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 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 ## 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 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" ## 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 Use: Adapter type: OpenCode and ensure: OPENROUTER_API_KEY is available to the agent. ## 6. OpenRouter authentication fails 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 # 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 ## Generate a database password openssl rand -base64 32 ## Check DNS nslookup paperclip.arpann8n.qzz.io ## Check firewall rules sudo iptables -L INPUT -n --line-numbers ## Allow HTTP sudo iptables -I INPUT 1 -p tcp --dport 80 -j ACCEPT ## Allow HTTPS sudo iptables -I INPUT 1 -p tcp --dport 443 -j ACCEPT ## Save firewall rules sudo netfilter-persistent save ## Check listening ports sudo ss -tulpn # 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 # 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.

Details a pre-auth format string vulnerability in tac_plus, a popular daemon implementing TACACS+ for network device management, and the shared secret oracle that makes it a practical RCE chain.

Vulnerability in the Oracle Hyperion Financial Management product of Oracle Hyperion (component: Security). The supported version that is affected is 11.2.26.0.000. Easily exploitable vulnerability allows low privileged attacker with network access via HTTP to compromise Oracle Hyperion Financial

Details a pre-auth format string vulnerability in tac_plus, a popular daemon implementing TACACS+ for network device management, and the shared secret oracle that makes it a practical RCE chain.

Vulnerability in the Oracle Access Manager product of Oracle Fusion Middleware (component: Authentication Engine). Supported versions that are affected are 12.2.1.4.0 and 14.1.2.0.0. Difficult to exploit vulnerability allows unauthenticated attacker with network access via HTTP to compromise Oracl

Vulnerability in the Oracle WebCenter Portal product of Oracle Fusion Middleware (component: Portlet Services). Supported versions that are affected are 12.2.1.4.0 and 14.1.2.0.0. Difficult to exploit vulnerability allows unauthenticated attacker with network access via HTTP to compromise Oracle W

Vulnerability in the Oracle WebCenter Enterprise Capture product of Oracle Fusion Middleware (component: Client Bundle). Supported versions that are affected are 12.2.1.4.0 and 14.1.2.0.0. Easily exploitable vulnerability allows high privileged attacker with network access via HTTP to compromise O

Vulnerability in the PeopleSoft Enterprise PeopleTools product of Oracle PeopleSoft (component: SQR). Supported versions that are affected are 8.61-8.63. Easily exploitable vulnerability allows low privileged attacker with network access via HTTP to compromise PeopleSoft Enterprise PeopleTools. Su

Vulnerability in the PeopleSoft Enterprise PeopleTools product of Oracle PeopleSoft (component: Cube Manager). Supported versions that are affected are 8.61-8.63. Easily exploitable vulnerability allows low privileged attacker with network access via HTTP to compromise PeopleSoft Enterprise PeopleT

Vulnerability in the Oracle Coherence product of Oracle Fusion Middleware (component: Core). Supported versions that are affected are 12.2.1.4.0, 14.1.1.0.0, 14.1.2.0.0 and 15.1.1.0.0. Easily exploitable vulnerability allows low privileged attacker with network access via TCP to compromise Oracle

Vulnerability in the Oracle Identity Manager product of Oracle Fusion Middleware (component: OIM Legacy UI). Supported versions that are affected are 12.2.1.4.0 and 14.1.2.1.0. Easily exploitable vulnerability allows unauthenticated attacker with network access via HTTP to compromise Oracle Identi

Vulnerability in the Oracle Product Hub product of Oracle E-Business Suite (component: Internal Operations). Supported versions that are affected are 12.2.3-12.2.15. Easily exploitable vulnerability allows low privileged attacker with network access via HTTP to compromise Oracle Product Hub. Succe

Vulnerability in the Oracle Product Hub product of Oracle E-Business Suite (component: Internal Operations). Supported versions that are affected are 12.2.3-12.2.15. Easily exploitable vulnerability allows low privileged attacker with network access via HTTP to compromise Oracle Product Hub. Succe

Vulnerability in the Oracle Purchasing product of Oracle E-Business Suite (component: G-Invoicing). Supported versions that are affected are 12.2.10-12.2.15. Easily exploitable vulnerability allows low privileged attacker with network access via HTTP to compromise Oracle Purchasing. Successful att

Vulnerability in the Oracle Purchasing product of Oracle E-Business Suite (component: G-Invoicing). Supported versions that are affected are 12.2.11-12.2.15. Easily exploitable vulnerability allows low privileged attacker with network access via HTTP to compromise Oracle Purchasing. Successful att

Vulnerability in the Oracle Purchasing product of Oracle E-Business Suite (component: Other issue). Supported versions that are affected are 12.2.3-12.2.15. Easily exploitable vulnerability allows low privileged attacker with network access via HTTP to compromise Oracle Purchasing. Successful atta

Vulnerability in the Oracle Hyperion Financial Management product of Oracle Hyperion (component: Security). The supported version that is affected is 11.2.26.0.000. Easily exploitable vulnerability allows low privileged attacker with network access via HTTP to compromise Oracle Hyperion Financial

Vulnerability in the Oracle Hyperion Financial Management product of Oracle Hyperion (component: Security). The supported version that is affected is 11.2.26.0.000. Difficult to exploit vulnerability allows unauthenticated attacker with network access via HTTP to compromise Oracle Hyperion Financi

Vulnerability in the Oracle Purchasing product of Oracle E-Business Suite (component: Other issue). Supported versions that are affected are 12.2.3-12.2.15. Easily exploitable vulnerability allows low privileged attacker with network access via HTTP to compromise Oracle Purchasing. Successful atta

Details a pre-auth format string vulnerability in tac_plus, a popular daemon implementing TACACS+ for network device management, and the shared secret oracle that makes it a practical RCE chain.

Vulnerability in the Oracle WebCenter Portal product of Oracle Fusion Middleware (component: Runtime Tools). Supported versions that are affected are 12.2.1.4.0 and 14.1.2.0.0. Easily exploitable vulnerability allows unauthenticated attacker with network access via HTTP to compromise Oracle WebCen

Vulnerability in the Siebel CRM Cloud Applications product of Oracle Siebel CRM (component: Siebel Cloud Manager). Supported versions that are affected are 22.3-26.7. Easily exploitable vulnerability allows unauthenticated attacker with network access via HTTP to compromise Siebel CRM Cloud Applica

Vulnerability in the Oracle Hyperion Financial Management product of Oracle Hyperion (component: Security). The supported version that is affected is 11.2.26.0.000. Easily exploitable vulnerability allows unauthenticated attacker with network access via TCP to compromise Oracle Hyperion Financial

Vulnerability in the Oracle Hyperion Financial Management product of Oracle Hyperion (component: Security). The supported version that is affected is 11.2.26.0.000. Easily exploitable vulnerability allows unauthenticated attacker with network access via HTTP to compromise Oracle Hyperion Financial