DEV Community: Arpan Dhara

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

Arpan Dhara — Mon, 28 Sep 2026 09:22:18 +0000

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.

Architecture Overview
Prerequisites
Network & Firewall Configuration
- DNS Configuration
- OCI VCN Security Rules
- Ubuntu Host Firewall
Generate Application Secrets
Coolify Service Configuration
- Create Docker Compose Resource
- Environment Variables
- Domain & Port Mapping
- Deploy
Bootstrap the First Admin Account
Complete Initial Onboarding
Configure OpenRouter
Verification
Troubleshooting
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

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:

Pull the required container images.
Start PostgreSQL.
Wait for the PostgreSQL health check.
Start Paperclip.
Apply the application's database setup/migrations as required by the image.
Configure Traefik routing.
Request/provision a Let's Encrypt certificate.
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.

🐧 WSL (Windows Subsystem for Linux) — Complete Setup & Command Guide

Arpan Dhara — Sat, 15 Aug 2026 06:56:24 +0000

🚀 A step-by-step guide to installing, configuring, and using Windows Subsystem for Linux (WSL) — including essential commands, Windows/Linux integration, and useful advanced features.

📚 Table of Contents

What is WSL?
Step 1 — Enable WSL Features
Step 2 — Check Your WSL Installation
Step 3 — Update WSL
Step 4 — List Installed Linux Distributions
Step 5 — See Available Distributions
Step 6 — Install a Linux Distribution
Step 7 — Uninstall a Distribution
Step 8 — Change the Default Distribution
Step 9 — Launch and Switch Between Linux Distributions
Step 10 — Exit and Shut Down WSL
Step 11 — Access Windows Drives from Linux
Step 12 — Use Windows Commands from Linux
Step 13 — Run Windows Applications from Linux
Step 14 — Use VS Code with WSL
Step 15 — Open the Current Linux Directory in Windows Explorer
Step 16 — Run Linux Commands from Windows
Step 17 — Kali Linux Tweaks
🧠 Command Cheat Sheet
📖 Official Documentation

🐧 What is WSL?

Windows Subsystem for Linux (WSL) allows you to run a Linux environment directly on Windows without needing to set up a traditional dual-boot system or a separate full virtual machine.

With WSL, you can:

🐧 Run Linux distributions such as Ubuntu or Kali Linux.
💻 Use Linux commands directly from Windows.
🪟 Run Windows commands and applications from Linux.
📁 Access Windows files from Linux.
🛠️ Use development tools such as VS Code with a Linux environment.
🔄 Move between Windows and Linux workflows easily.

This guide is based on the commands and workflow in the accompanying WSL notes, expanded into a beginner-friendly Dev.to tutorial.

⚙️ Step 1 — Enable WSL Features

Before using WSL, make sure the required Windows features are enabled.

1. Open Windows Features

On Windows:

Press Win + R.
Type:

optionalfeatures

Press Enter.
In Turn Windows features on or off, enable:

✅ Virtual Machine Platform
✅ Windows Subsystem for Linux

Click OK.
Restart your PC when Windows asks you to.

💡 Why are these features required?

Windows Subsystem for Linux provides the Windows component required to run Linux environments.

Virtual Machine Platform provides virtualization support used by WSL 2.

🔁 A restart is important after enabling these Windows features.

🔍 Step 2 — Check Your WSL Installation

Open PowerShell or Windows Terminal and run:

wsl --status

What does it do?

wsl --status displays information about your WSL installation and configuration.

It is useful when you want to quickly check whether WSL is installed and see relevant version/configuration information.

Example

wsl --status

If WSL is working correctly, Windows will display information about the current WSL configuration.

🔄 Step 3 — Update WSL

To update WSL to the latest available version, run:

wsl --update

What does it do?

The command checks for and installs available updates for WSL.

Recommended workflow

If you are setting up WSL on a new machine, it is a good idea to update WSL before continuing:

wsl --update

📦 Step 4 — List Installed Linux Distributions

To see Linux distributions installed on your Windows system:

wsl --list

You may also use:

wsl -l

What does it do?

It lists the Linux distributions currently installed under WSL.

For example, you might have:

Ubuntu
kali-linux

🟢 Show Currently Running Distributions

Use:

wsl --list --running

or:

wsl -l --running

What does it do?

This shows only the Linux distributions that are currently running.

This is useful when you have several distributions installed and want to know which ones currently have active WSL instances.

🔎 Show Detailed Distribution Information

Use:

wsl --list --verbose

or:

wsl -l -v

What does it show?

The verbose list provides additional information about installed distributions, including their WSL version and whether they are currently running.

This is particularly useful for checking whether a distribution is using WSL 1 or WSL 2.

🌐 Step 5 — See Available Distributions

To see Linux distributions that can be installed through WSL, run:

wsl --install --online

You may also use:

wsl --list --online

Depending on your Windows/WSL version, the output will show distributions available for installation.

💡 Why use this command?

Instead of guessing distribution names, you can first check the names Windows recognizes.

For example, a distribution may have a specific identifier that should be passed to the installation command.

📥 Step 6 — Install a Linux Distribution

Once you know the distribution name, install it with:

wsl --install -d <distribution-name>

For example:

wsl --install -d Ubuntu

Or, if the available distribution is listed under another identifier:

wsl --install -d kali-linux

⚠️ Administrator privileges

The setup notes recommend running PowerShell as an Administrator for the installation process.

To do that:

Open the Start menu.
Search for PowerShell.
Right-click PowerShell.
Select Run as administrator.
Run the WSL installation command.

🗑️ Step 7 — Uninstall a Distribution

There are two approaches mentioned in the notes.

Method 1 — Windows Settings

You can uninstall a Linux distribution through:

Settings → Apps → Installed apps

Find the distribution you want to remove and uninstall it.

Method 2 — Use the WSL Command

You can unregister a distribution with:

wsl --unregister <distribution-name>

Example:

wsl --unregister Ubuntu

⚠️ Important

wsl --unregister removes the WSL distribution and its associated Linux filesystem/data.

Therefore, do not use this command unless you are sure you want to remove that distribution and its data.

⭐ Step 8 — Change the Default Distribution

If you have multiple Linux distributions installed, you can choose which one launches when you run:

wsl

Use:

wsl --set-default <distribution-name>

For example:

wsl --set-default kali-linux

🧠 How does this work?

Suppose you have:

Ubuntu
kali-linux

If Ubuntu is the default, running:

wsl

opens Ubuntu.

If you change the default:

wsl --set-default kali-linux

then:

wsl

will open Kali Linux instead.

🚀 Step 9 — Launch and Switch Between Linux Distributions

Launch the default distribution

Simply run:

wsl

This launches your default WSL distribution.

Launch a specific distribution

Use:

wsl -d <distribution-name>

Example:

wsl -d Ubuntu

or:

wsl -d kali-linux

💡 Why is this useful?

You can keep multiple distributions installed and launch the one you need without changing the default distribution.

🚪 Step 10 — Exit and Shut Down WSL

Exit the current Linux shell

Inside Linux, run:

exit

This exits the current Linux shell and returns you to the Windows terminal.

💡 The command exits the current shell; it does not necessarily mean every WSL distribution on your system has been shut down.

🛑 Shut down all WSL instances

From Windows, run:

wsl --shutdown

What does it do?

It shuts down all currently running WSL distributions.

This can be useful when:

🔄 You need to restart WSL completely.
🧹 You want to release resources.
🛠️ You are troubleshooting WSL behavior.

🎯 Shut down a specific distribution

Use:

wsl --terminate <distribution-name>

Example:

wsl --terminate Ubuntu

Difference between the two

Command	Purpose
`wsl --shutdown`	Stops all running WSL distributions
`wsl --terminate Ubuntu`	Stops only the specified distribution

📁 Step 11 — Access Windows Drives from Linux

Windows drives are available inside Linux through /mnt.

For example, the Windows C: drive can be accessed as:

/mnt/c

The D: drive can be accessed as:

/mnt/d

You can navigate to a Windows drive with:

cd /mnt/c

Example

cd /mnt/c
ls

This lets you view files and folders on the Windows C: drive from Linux.

🧠 Understanding the Path

Windows:

C:\

WSL/Linux:

/mnt/c

Windows:

D:\

WSL/Linux:

/mnt/d

The drive letter is converted into a Linux-style path under /mnt.

🪟 Step 12 — Use Windows Commands from Linux

One of the most useful WSL features is the ability to execute Windows commands directly from your Linux shell.

The notes demonstrate this by adding .exe to Windows commands.

For example:

ifconfig.exe

or:

ping.exe

The Windows executable is launched from the Linux environment.

🧠 The basic idea

Instead of:

Windows command

you can invoke the Windows executable:

Windows command.exe

This creates a convenient bridge between Linux and Windows.

📝 Step 13 — Run Windows Applications from Linux

WSL can also launch Windows applications.

For example, the notes use Windows Notepad:

notepad.exe document.txt

This launches Notepad and opens the specified file.

Why is this useful?

You can combine:

🐧 Linux command-line tools
🪟 Windows desktop applications

in the same workflow.

For example:

notepad.exe document.txt

allows a Windows GUI application to be launched directly from your Linux terminal.

💻 Step 14 — Use VS Code with WSL

WSL can be integrated with Visual Studio Code.

The notes describe the workflow as:

code demo.py

This allows you to open a file from the Linux environment in VS Code.

Recommended setup

Install Visual Studio Code on Windows.
Install the WSL extension in VS Code.
Open your WSL terminal.
Navigate to your project.
Run:

code demo.py

🧠 Why the WSL extension matters

The WSL integration allows VS Code to work with your Linux environment rather than treating the project as an ordinary Windows-only project.

This is especially useful for software development because you can use Linux tooling while keeping the Windows VS Code interface.

📂 Step 15 — Open the Current Linux Directory in Windows Explorer

From inside your Linux terminal, run:

explorer.exe .

What does `.` mean?

In Linux:

means:

the current directory

Therefore:

explorer.exe .

means:

Open the current Linux directory using Windows Explorer.

Example

cd ~/projects
explorer.exe .

Windows Explorer will open the current location.

🐧 Step 16 — Run Linux Commands from Windows

WSL also works in the opposite direction.

You can execute Linux commands directly from a Windows terminal by prefixing the command with:

wsl

For example:

wsl cat demo.txt

How does it work?

Windows runs:

wsl

and passes the remaining command to the Linux environment.

So:

wsl cat demo.txt

runs the Linux command:

cat demo.txt

without requiring you to manually enter the Linux shell first.

🛠️ Step 17 — Kali Linux Tweaks

If you are using Kali Linux, the notes mention:

kali-tweaks

What is it used for?

kali-tweaks provides a way to configure and customize aspects of a Kali Linux installation.

You can explore the available options from the tool itself.

Run:

kali-tweaks

and follow the interactive menus.

💡 This section is specific to Kali Linux. The command may not be available in other Linux distributions.

🔥 WSL's Windows ↔ Linux Integration

One of the biggest advantages of WSL is that Windows and Linux can work together.

Here is the basic relationship:

You can:

🐧 Linux → Windows

Run Windows commands:

ping.exe

Run Windows applications:

notepad.exe document.txt

Open Windows Explorer:

explorer.exe .

Launch VS Code:

code demo.py

🪟 Windows → Linux

Run Linux commands from Windows:

wsl cat demo.txt

This two-way integration is what makes WSL particularly convenient for development workflows.

🧠 Command Cheat Sheet

⚙️ Installation & Updates

Command	Purpose
`wsl --status`	Show WSL status/configuration information
`wsl --update`	Update WSL
`wsl --install --online`	Show distributions available for installation
`wsl --install -d <distro>`	Install a specific distribution

📦 Distribution Management

Command	Purpose
`wsl --list`	List installed distributions
`wsl --list --running`	List running distributions
`wsl --list --verbose`	Show detailed distribution information
`wsl --set-default <distro>`	Set the default distribution
`wsl --unregister <distro>`	Remove/unregister a distribution

🚀 Starting & Stopping

Command	Purpose
`wsl`	Launch the default distribution
`wsl -d <distro>`	Launch a specific distribution
`exit`	Exit the current Linux shell
`wsl --shutdown`	Shut down all WSL instances
`wsl --terminate <distro>`	Terminate one distribution

🪟 Windows ↔ Linux Integration

Command	Purpose
`cd /mnt/c`	Access the Windows C: drive
`explorer.exe .`	Open the current directory in Windows Explorer
`notepad.exe document.txt`	Open a file in Windows Notepad
`ping.exe`	Run the Windows ping executable from Linux
`code demo.py`	Open a file in VS Code
`wsl cat demo.txt`	Run a Linux command from Windows

🧪 Example: A Simple WSL Development Workflow

Here is a practical example combining several commands from this guide.

1️⃣ Check WSL

From PowerShell:

wsl --status

2️⃣ Update WSL

wsl --update

3️⃣ Check installed distributions

wsl --list --verbose

4️⃣ Start Ubuntu

wsl -d Ubuntu

5️⃣ Navigate to a Windows project directory

cd /mnt/c/Users/<your-username>/Desktop

6️⃣ Create or access your project

cd my-project

7️⃣ Open the project in VS Code

code .

8️⃣ Open the same directory in Windows Explorer

explorer.exe .

This workflow demonstrates how Windows and Linux can work together without constantly switching environments.

🧩 Useful Mental Model

If you are new to WSL, remember these three rules:

Rule 1 — Windows drives live under `/mnt`

C:\  →  /mnt/c
D:\  →  /mnt/d

Rule 2 — Windows `.exe` programs can be launched from Linux

notepad.exe
explorer.exe .

Rule 3 — Linux commands can be launched from Windows using `wsl`

wsl <linux-command>

For example:

wsl cat demo.txt

Once these three concepts become familiar, WSL becomes much easier to understand.

⚠️ Important Notes

🔐 Some WSL installation operations may require an Administrator PowerShell.
🔄 Restart Windows after enabling the required Windows features.
🗑️ Be careful with wsl --unregister because it removes the selected distribution and its data.
🐧 kali-tweaks is intended for Kali Linux.
💻 For VS Code + WSL development, install the WSL extension in VS Code.
📁 Windows drives are commonly accessed through /mnt/<drive-letter> from Linux.
🛑 wsl --shutdown affects all running WSL distributions, while wsl --terminate <distro> targets one distribution.

📖 Official Documentation

For the latest and most authoritative information, always refer to Microsoft's official WSL documentation.

🖥️ WSL GUI Applications

Microsoft's WSL GUI applications guide:

https://learn.microsoft.com/en-us/windows/wsl/tutorials/gui-apps

📚 WSL Basic Commands

Microsoft's WSL basic commands documentation:

https://learn.microsoft.com/en-us/windows/wsl/basic-commands

🔎 WSL is actively maintained, so command behavior and supported features can change over time. The official Microsoft documentation should be treated as the final reference for current behavior.

🎉 Conclusion

WSL provides a powerful bridge between Windows and Linux.

With just a few commands, you can:

🐧 Install and manage Linux distributions.
🔄 Update and troubleshoot WSL.
📦 Run multiple distributions.
🪟 Access Windows files from Linux.
💻 Run Windows applications from Linux.
🐧 Run Linux commands from Windows.
📝 Use VS Code with a Linux development environment.
📂 Open Linux directories directly in Windows Explorer.

The most important commands to remember are:

wsl --status
wsl --update
wsl --list --verbose
wsl --install -d <distribution-name>
wsl --set-default <distribution-name>
wsl
wsl -d <distribution-name>
wsl --shutdown
wsl --terminate <distribution-name>

And from inside Linux:

cd /mnt/c
explorer.exe .
notepad.exe document.txt
code demo.py

Happy Linux-ing on Windows! 🐧💻🚀

Configure Claude Code with Agent Router Using settings.json

Arpan Dhara — Mon, 10 Aug 2026 12:15:13 +0000

If you want to use Agent Router as the API endpoint for Claude Code, you can configure the connection directly through Claude Code's settings.json file.

This configuration sets:

Your Anthropic API key
Agent Router as the API base URL
The Claude model you want to use
Claude Code permission rules

1. Create or open `settings.json`

Depending on your Claude Code setup, create or edit your settings.json configuration file.

The basic configuration looks like this:

{
  "env": {
    "ANTHROPIC_API_KEY": "YOUR_ANTHROPIC_API_KEY",
    "ANTHROPIC_BASE_URL": "https://agentrouter.org",
    "ANTHROPIC_MODEL": "claude-opus-5"
  },
  "permissions": {
    "allow": [],
    "deny": []
  }
}

2. Configure the Anthropic API Key

Replace:

"ANTHROPIC_API_KEY": "YOUR_ANTHROPIC_API_KEY"

with your actual API key.

For example:

"ANTHROPIC_API_KEY": "sk-your-api-key-here"

3. Configure Agent Router

The following setting tells Claude Code to send API requests through Agent Router:

"ANTHROPIC_BASE_URL": "https://agentrouter.org"

Instead of communicating directly with the default Anthropic API endpoint, Claude Code will use the configured base URL.

4. Select the Claude Model

Set the model you want Claude Code to use:

"ANTHROPIC_MODEL": "claude-opus-5"

The model name must match a model supported by your Agent Router configuration.

If your Agent Router account uses a different model identifier, replace the value accordingly.

5. Configure Permissions

The permissions section controls which operations Claude Code is allowed or denied.

The minimal configuration is:

"permissions": {
  "allow": [],
  "deny": []
}

You can later add specific permissions according to your Claude Code workflow.

Complete `settings.json`

Here is the complete configuration:

{
  "env": {
    "ANTHROPIC_API_KEY": "YOUR_ANTHROPIC_API_KEY",
    "ANTHROPIC_BASE_URL": "https://agentrouter.org",
    "ANTHROPIC_MODEL": "claude-opus-5"
  },
  "permissions": {
    "allow": [],
    "deny": []
  }
}

Once the configuration is saved, Claude Code can use the configured Agent Router endpoint and model according to your setup.

Integrating AgentRouter with Tauric Research TradingAgents

Arpan Dhara — Sat, 08 Aug 2026 17:06:56 +0000

If you're using Tauric Research's TradingAgents framework and want to add AgentRouter as a fully supported LLM provider, this guide will walk you through the complete integration.

The process is organized file-by-file, so you can open each file and make all of the required changes before moving to the next one.

TradingAgents Repository:
[https://github.com/TauricResearch/TradingAgents.git]

What We'll Do

In this tutorial, we'll:

Register the AgentRouter API endpoint
Configure the AgentRouter WAF-bypass headers
Add AgentRouter's model catalog
Configure the AgentRouter API key environment variable
Bypass strict model-name validation
Add AgentRouter to the TradingAgents CLI
Configure the .env file
Reinstall and restart TradingAgents

Let's get started.

Step 1 — Update `openai_client.py`

Open:

tradingagents/llm_clients/openai_client.py

This file requires two changes:

Register the AgentRouter API endpoint
Configure the headers required by AgentRouter

The integration guide specifically places both changes in this file.

1A — Register the AgentRouter API Endpoint

Locate the:

OPENAI_COMPATIBLE_PROVIDERS

dictionary.

Add AgentRouter alongside the existing OpenAI-compatible providers:

"openrouter": ProviderSpec(
    base_url="https://openrouter.ai/api/v1"
),
"agentrouter": ProviderSpec(
    base_url="https://agentrouter.org/v1"
),

The important part here is the AgentRouter base URL:

https://agentrouter.org/v1

This allows TradingAgents to communicate with AgentRouter through its OpenAI-compatible API interface.

1B — Configure AgentRouter WAF-Bypass Headers

Still in:

tradingagents/llm_clients/openai_client.py

Locate the get_llm(self) method inside the OpenAIClient class.

Find the section that forwards user-provided keyword arguments:

# Forward user-provided kwargs
for key in _PASSTHROUGH_KWARGS:
    if key not in self.kwargs:
        continue
    if key == "reasoning_effort" and not _supports_reasoning_effort(self.model):
        continue
    llm_kwargs[key] = self.kwargs[key]

Immediately after this section, add the AgentRouter-specific headers:

# Forward user-provided kwargs
for key in _PASSTHROUGH_KWARGS:
    if key not in self.kwargs:
        continue
    if key == "reasoning_effort" and not _supports_reasoning_effort(self.model):
        continue
    llm_kwargs[key] = self.kwargs[key]

# --- NEW CODE START: Add spoofed headers for AgentRouter ---
if self.provider == "agentrouter":
    llm_kwargs["default_headers"] = {
        "Originator": "codex_cli_rs",
        "User-Agent": "codex_cli_rs/0.114.0 (Windows 10.0.26100; x86_64)",
        "Version": "0.114.0",
    }

# --- NEW CODE END ---

# The subclass (provider quirks) comes from the registry spec.
return chat_cls(**llm_kwargs)

These headers are part of the AgentRouter integration described in the guide.

Important: Make sure this code is placed inside the get_llm(self) method and before the final return chat_cls(**llm_kwargs).

Step 2 — Update `model_catalog.py`

Now open:

tradingagents/llm_clients/model_catalog.py

This file controls the models that can be selected for each provider.

2A — Define AgentRouter Models

Near the top of the file, around the existing model definitions, add:

_AGENTROUTER_MODELS: dict[str, list[ModelOption]] = {
    "quick": [
        ("GPT-4o Mini", "openai/gpt-4o-mini"),
        ("Claude 3.5 Haiku", "anthropic/claude-3-haiku"),
        ("DeepSeek V3", "deepseek/deepseek-chat"),
        ("Custom model ID", "custom"),
    ],
    "deep": [
        ("GPT-4o", "openai/gpt-4o"),
        ("Claude 3.5 Sonnet", "anthropic/claude-3-5-sonnet"),
        ("DeepSeek R1", "deepseek/deepseek-reasoner"),
        ("Custom model ID", "custom"),
    ],
}

The quick category contains lighter model choices, while deep contains the deeper/reasoning-oriented choices listed in the integration guide.

2B — Register the AgentRouter Model Catalog

Scroll down to:

MODEL_OPTIONS

Add the AgentRouter mapping:

"bedrock": _CUSTOM_ONLY,
"agentrouter": _AGENTROUTER_MODELS,

This connects the agentrouter provider with the model catalog you just created.

Step 3 — Update `api_key_env.py`

Open:

tradingagents/llm_clients/api_key_env.py

Locate:

PROVIDER_API_KEY_ENV

Add the AgentRouter environment variable:

"openrouter": "OPENROUTER_API_KEY",
"agentrouter": "AGENTROUTER_API_KEY",

This tells TradingAgents to retrieve the AgentRouter API key from:

AGENTROUTER_API_KEY

The integration guide specifies this exact provider-to-environment-variable mapping.

Step 4 — Update `validators.py`

Open:

tradingagents/llm_clients/validators.py

TradingAgents normally performs strict validation of model names.

For AgentRouter, add the provider to:

_ANY_MODEL_PROVIDERS

The resulting tuple should include agentrouter:

_ANY_MODEL_PROVIDERS = (
    "ollama",
    "openrouter",
    "openai_compatible",
    "mistral",
    "kimi",
    "groq",
    "nvidia",
    "bedrock",
    "agentrouter",
)

This allows AgentRouter to work with model IDs without being restricted by the strict model-name validation.

Step 5 — Update `cli/utils.py`

Now open:

cli/utils.py

Locate:

_llm_provider_table()

This function contains the providers displayed in the interactive TradingAgents CLI.

Find the OpenRouter entry and add AgentRouter immediately after it:

("OpenRouter", "openrouter", "https://openrouter.ai/api/v1"),
("AgentRouter", "agentrouter", "https://agentrouter.org/v1"),

After this change, AgentRouter should appear as a selectable provider when you launch the TradingAgents CLI.

Step 6 — Configure the `.env` File

Now open the .env file in the root directory of your TradingAgents project.

Add your AgentRouter API key:

AGENTROUTER_API_KEY=your_actual_agentrouter_key_here

Replace:

your_actual_agentrouter_key_here

with your actual AgentRouter API key.

Keep Your API Key Private

Do not commit your .env file or API key to GitHub.

Make sure your .gitignore contains:

.env

Step 7 — Reinstall and Restart TradingAgents

Once you've completed all of the modifications, save your files.

Open your VS Code terminal and run:

pip install -e .

This reinstalls the package in editable mode so the modified Python definitions are refreshed.

Then launch TradingAgents:

TradingAgents

The integration guide specifically recommends restarting the CLI session after making the code changes so Python loads the modified code from disk.

Complete File Checklist

At this point, you should have modified the following files:

tradingagents/
├── llm_clients/
│   ├── openai_client.py
│   ├── model_catalog.py
│   ├── api_key_env.py
│   └── validators.py
│
└── cli/
    └── utils.py

.env

Here's a quick summary of what changes in each file:

openai_client.py
    ├── AgentRouter API endpoint
    └── AgentRouter WAF-bypass headers

model_catalog.py
    └── AgentRouter model definitions

api_key_env.py
    └── AGENTROUTER_API_KEY mapping

validators.py
    └── AgentRouter model validation bypass

cli/utils.py
    └── AgentRouter CLI provider entry

.env
    └── Your AgentRouter API key

Quick Verification Checklist

Before launching TradingAgents, verify that you have completed every step:

[ ] Added the AgentRouter API endpoint
[ ] Added the AgentRouter headers inside get_llm()
[ ] Added _AGENTROUTER_MODELS
[ ] Added "agentrouter" to MODEL_OPTIONS
[ ] Added AGENTROUTER_API_KEY to PROVIDER_API_KEY_ENV
[ ] Added "agentrouter" to _ANY_MODEL_PROVIDERS
[ ] Added AgentRouter to the CLI provider table
[ ] Added your AgentRouter API key to .env
[ ] Ran pip install -e .
[ ] Restarted the TradingAgents CLI

Conclusion

That's it!

AgentRouter is now registered as a provider in the TradingAgents framework, with:

OpenAI-compatible API support
AgentRouter-specific headers
Predefined model selections
Custom model support
Environment-based API key configuration
CLI provider selection

You can now launch TradingAgents and select AgentRouter from the interactive provider menu.

TradingAgents Repository:
[YOUR_TRADINGAGENTS_REPOSITORY_LINK]

If you're integrating another OpenAI-compatible provider into TradingAgents, the same general architecture can be useful: provider registration, model catalog configuration, API-key mapping, validation rules, and CLI registration.

Final Integration Flow

AgentRouter
     │
     ▼
API Endpoint Registration
     │
     ▼
OpenAIClient
     │
     ├── AgentRouter Headers
     │
     ▼
Model Catalog
     │
     ▼
API Key Environment Variable
     │
     ▼
Model Validation
     │
     ▼
TradingAgents CLI
     │
     ▼
AgentRouter LLM

Happy trading! 🚀

Integrating TokenRouter with Tauric Research TradingAgents

Arpan Dhara — Sat, 08 Aug 2026 17:02:48 +0000

If you're using Tauric Research's TradingAgents framework and want to integrate TokenRouter as an LLM provider, this guide walks through the complete process step by step.

The integration adds TokenRouter support to the TradingAgents interactive CLI and provides a predefined list of models that you can select directly from the interface.

TradingAgents Repository:
[https://github.com/TauricResearch/TradingAgents.git]

What We'll Do

In this tutorial, we'll:

Define TokenRouter models in the model catalog
Register the TokenRouter API endpoint
Configure the TokenRouter API key
Bypass strict model-name validation
Add TokenRouter to the interactive CLI
Configure the .env file
Reinstall and restart TradingAgents

Let's get started.

Step 1 — Define TokenRouter Models in the Model Catalog

First, open:

tradingagents/llm_clients/model_catalog.py

Near the top of the file, around the model definitions section, add a TokenRouter model dictionary.

_TOKENROUTER_MODELS: dict[str, list[ModelOption]] = {
    "quick": [
        ("GPT-4o Mini", "openai/gpt-4o-mini"),
        ("Claude 3.5 Haiku", "anthropic/claude-3-haiku"),
        ("DeepSeek V3", "deepseek/deepseek-chat"),
        ("Custom model ID", "custom"),
    ],
    "deep": [
        ("GPT-4o", "openai/gpt-4o"),
        ("Claude 3.5 Sonnet", "anthropic/claude-3-5-sonnet"),
        ("DeepSeek R1", "deepseek/deepseek-reasoner"),
        ("Custom model ID", "custom"),
    ],
}

The quick and deep categories provide predefined model choices.

You can also use the custom option when you want to specify your own model ID.

Next, locate MODEL_OPTIONS, around the section where providers are mapped.

Add tokenrouter after bedrock:

"bedrock": _CUSTOM_ONLY,
"tokenrouter": _TOKENROUTER_MODELS,

After this change, TradingAgents will know which models should be presented when TokenRouter is selected.

Step 2 — Register the TokenRouter API Endpoint

Now we need to tell TradingAgents where the TokenRouter API is located.

Open:

tradingagents/llm_clients/openai_client.py

Find:

OPENAI_COMPATIBLE_PROVIDERS

Add TokenRouter to the provider definitions:

"openrouter": ProviderSpec(
    base_url="https://openrouter.ai/api/v1"
),
"tokenrouter": ProviderSpec(
    base_url="https://api.tokenrouter.com/v1"
),

TokenRouter is registered here as an OpenAI-compatible provider.

Step 3 — Configure the TokenRouter API Key Environment Variable

Next, open:

tradingagents/llm_clients/api_key_env.py

Find:

PROVIDER_API_KEY_ENV

Add the TokenRouter environment variable:

"openrouter": "OPENROUTER_API_KEY",
"tokenrouter": "TOKENROUTER_API_KEY",

This tells TradingAgents which environment variable contains the TokenRouter API key.

Step 4 — Bypass Strict Model Name Validation

TradingAgents may normally validate model names against its predefined rules.

Because TokenRouter can provide different models through its API, we need to add it to the providers that allow arbitrary model names.

Open:

tradingagents/llm_clients/validators.py

Locate:

_ANY_MODEL_PROVIDERS

Then add tokenrouter:

_ANY_MODEL_PROVIDERS = (
    "ollama",
    "openrouter",
    "openai_compatible",
    "mistral",
    "kimi",
    "groq",
    "nvidia",
    "bedrock",
    "tokenrouter",
)

This allows TokenRouter model IDs to pass through the model validation layer.

Step 5 — Add TokenRouter to the Interactive CLI

Now we'll make TokenRouter visible in the TradingAgents interactive CLI.

Open:

cli/utils.py

Locate:

_llm_provider_table()

Find the OpenRouter entry and add TokenRouter immediately after it:

("OpenRouter", "openrouter", "https://openrouter.ai/api/v1"),
("TokenRouter", "tokenrouter", "https://api.tokenrouter.com/v1"),

After this change, TokenRouter should appear as a selectable provider when you launch the TradingAgents CLI.

Step 6 — Add Your TokenRouter API Key

Now we need to provide your TokenRouter API key.

Open the .env file in the root directory of the TradingAgents project.

Add:

TOKENROUTER_API_KEY=your_actual_tokenrouter_key_here

Replace:

your_actual_tokenrouter_key_here

with your actual TokenRouter API key.

Important: Never commit your .env file or API key to GitHub.

Make sure .env is included in your .gitignore.

Step 7 — Reinstall and Restart TradingAgents

After making all of the changes, save your files.

Open the VS Code terminal and reinstall the project in editable mode:

pip install -e .

Then launch TradingAgents:

TradingAgents

Restarting the application is important because Python needs to load the modified definitions from disk.

Final Project Changes

After completing the integration, you should have modified the following files:

tradingagents/
├── llm_clients/
│   ├── model_catalog.py
│   ├── openai_client.py
│   ├── api_key_env.py
│   └── validators.py
│
└── cli/
    └── utils.py

.env

The main additions are:

TokenRouter model definitions
        ↓
TokenRouter API endpoint
        ↓
TOKENROUTER_API_KEY environment variable
        ↓
Model validation bypass
        ↓
TokenRouter CLI provider
        ↓
TradingAgents

That's It!

TokenRouter is now integrated into the TradingAgents framework as an LLM provider.

You should now be able to select TokenRouter from the interactive CLI and use the predefined models or provide a custom model ID.

If you're working with the Tauric Research TradingAgents project, you can find the repository here:

Repository:
[YOUR_TRADINGAGENTS_REPOSITORY_LINK]

Quick Checklist

Before running TradingAgents, make sure you've completed everything:

[ ] Added _TOKENROUTER_MODELS
[ ] Added "tokenrouter" to MODEL_OPTIONS
[ ] Added the TokenRouter API endpoint
[ ] Added TOKENROUTER_API_KEY
[ ] Added TokenRouter to _ANY_MODEL_PROVIDERS
[ ] Added TokenRouter to the CLI provider table
[ ] Added your API key to .env
[ ] Ran pip install -e .
[ ] Restarted TradingAgents

If all of the above are complete, you should be ready to use TokenRouter with TradingAgents.

This integration guide is based on the TokenRouter integration procedure for the TradingAgents framework.