{/* banner prompt: A paper collage illustration with a tangible, handcrafted feel, showing layered cutouts of a browser window (AI agent) and a network file cabinet, connected by a paper bridge with a keyhole representing a secure API, with visible paper textures and soft drop shadows to create depth, in a palette of muted craft paper colors, 16:9. */}

## The Problem

**Claude Cowork** is a desktop application, but it ships with a built-in sandbox. You can toggle the sandbox off in settings — and technically, it could access an SMB/CIFS network share on the same machine or LAN. Yet even with it disabled, accessing a network drive remains out of reach. This is not an oversight; it is a deliberate design decision by Anthropic. An agent with unconstrained access to mounted network shares can do real damage if it misinterprets an instruction or hallucinates a path — deleting a client folder, overwriting an authoritative document, or crawling terabytes of data it was never meant to touch.

The constraint is reasonable. But it creates a practical gap: many businesses keep authoritative files on a local network share — accounting records, client folders, scanned documents. If the AI agent cannot reach those, you end up copy-pasting content manually, which defeats the purpose.

The solution is not to fight Anthropic's design — it is to work within it. An **HTTP API in front of your file share** is something every AI agent already knows how to call. You define exactly which operations are exposed (list, read, write — but not delete). The agent gets the access it needs; you keep meaningful guardrails in place.

## The Solution: HTTP File Server as a Gateway

The key insight is that **any HTTP server sitting in front of your network share immediately makes it universally reachable** — from any network, any device, any AI agent that can make HTTP requests. No VPN. No SMB port forwarding. No credentials beyond a bearer token.

We used [FileBrowser Quantum](https://github.com/gtstef/filebrowser), a self-hosted file manager that exposes a clean REST API. It mounts your network shares as named "sources" and lets you list, read, search, download, and write files through standard HTTP calls.

---

## Architecture

```
┌─────────────────────────────────────────────────────────────┐
│  Office / LAN                                               │
│                                                             │
│  \\fileserver\data   (SMB/CIFS)                             │
│          │                                                  │
│          │  mount                                           │
│          ▼                                                  │
│  Linux VM  /srv/nas_data                                    │
│          │                                                  │
│          │  volume mount                                    │
│          ▼                                                  │
│  ┌──────────────────────┐                                   │
│  │  FileBrowser Quantum │  :8080                            │
│  │  Docker container    │                                   │
│  └──────────┬───────────┘                                   │
│             │                                               │
│             ▼                                               │
│  nginx  :443  ──── Cloudflare ────▶  files.example.com     │
└─────────────────────────────────────────────────────────────┘
                                            │
                         ┌──────────────────┤
                         │                  │
                         ▼                  ▼
              Claude Code / API      Claude Desktop (Windows)
              (direct HTTP calls)    ┌────────────────────┐
                                     │  filebrowser-mcp   │
                                     │  local Node.js     │
                                     │  stdio MCP server  │
                                     └────────────────────┘
```

The file server host can be set up in two ways:

- **Cloud VM with VPN or peering into the LAN** — the VM mounts the SMB share over a private tunnel; only the HTTPS endpoint is public-facing.
- **Office server with a port exposed** — FileBrowser runs directly on a machine that already has access to the share; nginx (or a reverse proxy like Cloudflare Tunnel) exposes only port 443 to the internet.

Either way, FileBrowser Quantum runs as a Docker container and mounts the share as a local path. nginx sits in front, terminates TLS via Cloudflare, and enforces an IP allowlist. The whole stack is reachable at `https://files.example.com`.

AI agents on any network — a cloud VM, a remote laptop, a Windows desktop — reach the file server through that HTTPS endpoint.

---

## Setting Up FileBrowser Quantum

### 1. Mount the SMB share on the Linux host

```bash
# /etc/fstab entry
//192.168.1.100/data  /srv/nas_data  cifs  credentials=/etc/smbcredentials,uid=1000,gid=1000,file_mode=0664,dir_mode=0775  0  0
```

The `uid`/`gid` and mode flags are important — they ensure the Docker container (running as a non-root user) can both read and write files.

### 2. docker-compose.yaml

```yaml
services:
  filebrowser:
    image: gtstef/filebrowser:stable
    container_name: filebrowser
    ports:
      - "8080:80"
    volumes:
      - /srv/nas_data:/nas:rw
      - /opt/filebrowser/data:/config
    environment:
      - FB_DATABASE=/config/database.db
      - FB_CONFIG=/config/config.yaml
    restart: unless-stopped
```

### 3. config.yaml — define sources

```yaml
sources:
  - name: main
    path: /nas
```

You can define multiple sources if you have more than one share.

---

## REST API at a Glance

Once running, the API is straightforward:

```bash
TOKEN="<your-jwt-token>"

# List a folder
curl "https://files.example.com/api/resources?source=main&path=/CLIENTS" \
  -H "Cookie: filebrowser_quantum_jwt=$TOKEN"

# Read a text file
curl "https://files.example.com/api/resources?source=main&path=/CLIENTS/acme/notes.txt&content=true" \
  -H "Cookie: filebrowser_quantum_jwt=$TOKEN"

# Download a binary file (PDF, xlsx, etc.) — note: file= not path=
curl "https://files.example.com/api/resources/download?source=main&file=/CLIENTS/acme/report.xlsx" \
  -H "Cookie: filebrowser_quantum_jwt=$TOKEN" \
  --output report.xlsx

# Search by filename
curl "https://files.example.com/api/tools/search?source=main&query=tax+return+2024" \
  -H "Cookie: filebrowser_quantum_jwt=$TOKEN"

# Write a file
curl -X POST "https://files.example.com/api/resources?source=main&path=/CLIENTS/acme/summary.txt&override=true" \
  -H "Cookie: filebrowser_quantum_jwt=$TOKEN" \
  -H "Content-Type: text/plain" \
  --data "AI-generated summary goes here"
```

> **Gotcha:** The download endpoint uses `file=` as the query parameter, not `path=`. Using `path=` returns `{"status":400,"message":"no files specified"}`. This inconsistency is worth documenting — it tripped us up initially.

---

## Security Measures

Opening file server access to the internet requires deliberate controls. Here is what we applied, from most to least important.

### 1. Scoped, long-lived JWT tokens

FileBrowser Quantum supports issuing named API tokens with explicit permission sets embedded in the JWT payload. We created a dedicated `ai` user with only the capabilities the agent actually needs:

```json
{
  "Permissions": {
    "api":      true,
    "modify":   true,
    "create":   true,
    "download": true,
    "share":    true,
    "delete":   false,
    "admin":    false
  }
}
```

**Delete is disabled.** An AI agent that can delete files is a data-loss risk — one hallucinated path and important client files are gone. Write access is sufficient for almost every automation use case. If you genuinely need deletion, do it through a separate, human-triggered workflow.

The token is set to expire in ~3 years. Long enough that it does not need babysitting, short enough that it will eventually rotate.

### 2. Removing delete — the BoltDB patch

FileBrowser Quantum stores user records in a BoltDB (key-value) database. The standard HTTP API for updating user permissions (`PUT /api/users?id=N`) had a quirk in our version: it always reset all permissions to false. We had to patch the database directly.

We wrote a small Go script that:
1. Stopped the Docker container to release the exclusive BoltDB lock.
2. Opened the database directly using the `bbolt` library.
3. Located the user record by its big-endian uint64 key.
4. Decoded the JSON user record, set `permissions.delete = false`, and cleared the `tokens` field (to invalidate any old tokens that still had delete enabled).
5. Wrote the record back, verified it in the same transaction, then restarted the container.

The `tokens` field step is critical. FileBrowser embeds the full permission set inside the JWT itself. If an old token with `delete: true` is still stored in the user record, the server restores those permissions on startup — overriding your DB change. Clearing `tokens` forces the server to issue fresh tokens reflecting the updated permissions.

### 3. nginx IP allowlist

The public URL is fronted by nginx, which checks the real client IP (passed through by Cloudflare via `X-Forwarded-For`) against an allowlist:

```nginx
geo $allowed_ip {
    default         0;
    200.0.13.10    1;   # office static IP
    2004:ab8::/48   1;   # authorised IPv6 prefix
}

server {
    listen 443 ssl;
    server_name files.example.com;

    if ($allowed_ip = 0) {
        return 403;
    }

    location / {
        proxy_pass http://127.0.0.1:8080;
    }
}
```

If a request comes from an unknown IP — even with a valid token — nginx returns 403 before FileBrowser ever sees the request. This means a leaked token is useless from outside the authorised IPs.

For AI agents running on cloud VMs, add their static IPs or CIDR prefix to the allowlist.

### 4. HTTPS only via Cloudflare

All traffic goes through Cloudflare, which handles TLS termination and provides DDoS protection. The origin (nginx) only accepts connections from Cloudflare's IP ranges, so the raw VM IP is not directly reachable on port 443.

---

## Wiring It Into Claude Desktop via MCP

For Claude Desktop on Windows (where you want the agent to work with local files after downloading them), we added a local [MCP](https://modelcontextprotocol.io/) server. The MCP server is a small Node.js process that wraps the FileBrowser HTTP API as MCP tools, communicating with Claude Desktop over stdio.

`claude_desktop_config.json`:
```json
{
  "mcpServers": {
    "workspace": {
      "command": "C:\\Program Files\\nodejs\\node.exe",
      "args": ["C:\\Tools\\filebrowser-mcp\\index.js"],
      "env": {
        "FILEBROWSER_URL": "https://files.example.com",
        "FILEBROWSER_TOKEN": "<token>"
      }
    }
  }
}
```

The MCP server exposes these tools to the agent:

<Table data={
    {
        headers: ['Tool', 'Purpose'],
        rows: [
            ['fs_list_sources', 'List available drives'],
            ['fs_list_folder', 'Browse a folder'],
            ['fs_read_file', 'Read text file content'],
            ['fs_download_file', 'Download binary file to local temp folder'],
            ['fs_search_files', 'Search by filename'],
            ['fs_get_file_metadata', 'Get size / date / type'],
        ]
    }
} />

The key tool here is `fs_download_file`. Claude's `web_fetch` tool cannot pass custom headers, so it cannot supply the auth cookie. The local MCP server, running as a native process with the token in its environment, has no such restriction — it fetches the file over HTTPS and saves it to the Windows temp folder, returning the local path so Claude can then read it with normal file tools.

```javascript
async function downloadFile({ source, path, save_to }) {
  // note: download endpoint uses file= not path=
  const url = `/api/resources/download?source=${encodeURIComponent(source)}&file=${encodePath(path)}`;
  const res = await fbFetch(url);
  const buffer = await res.arrayBuffer();
  const filename = path.split("/").pop();
  const localPath = save_to || join(tmpdir(), filename);
  writeFileSync(localPath, Buffer.from(buffer));
  return { source, path, filename, local_path: localPath, size_bytes: buffer.byteLength };
}
```

---

## Why This Works Better Than Alternatives

Claude does provide built-in connectors for services like Dropbox and OneDrive. In practice, though, most organisations have multiple accounts spread across different purposes — a Dropbox for one team, an OneDrive for another, a legacy NAS for a third. Each connector needs its own authorisation flow and only covers one account at a time.

An HTTP file server flips this: you mount every share behind a single endpoint, define named sources, and the agent accesses all of them through one token and one API. No per-account OAuth dance, no switching contexts.

<Table data={
    {
        headers: ['Approach', 'Trade-off'],
        rows: [
            ['VPN', 'Requires credential management; gives the agent broad network access'],
            ['Cloud sync connectors (Dropbox, OneDrive)', 'One connector per account; multiple accounts across teams means multiple authorisation flows to manage'],
            ['Direct SMB exposure', 'SMB was not designed for internet exposure; serious security risks'],
            ['HTTP file server (this setup)', 'Single endpoint, multiple sources; scoped token; IP allowlist; works for cloud storage and on-prem shares alike'],
        ]
    }
} />

The HTTP approach is universally accessible because every AI agent — whether it is Claude Code running on a cloud VM, Claude Desktop on a Windows workstation, or an API-driven automation script — already knows how to make HTTP requests. No special drivers, no OS-level mounts, no VPN configuration.

---

## Summary

If you have an office NAS that AI agents need to reach:

1. **Deploy FileBrowser Quantum** (or any HTTP file server) on a VM that can mount the share.
2. **Issue a scoped token** — read/write, no delete, fixed expiry.
3. **Lock it down at the network layer** — nginx IP allowlist, TLS via a CDN.
4. **For Claude Desktop**, add a local MCP server that wraps the HTTP API, so the agent can download binary files it could not otherwise fetch (PDFs, spreadsheets, etc.).

The result is an AI agent that can list folders, search for files, read documents, write results back, and download any file type — from any network — without ever needing a VPN or direct NAS access.

659c4cf1a18721f124647065e90f17a06648a0fa3fa9defdd99645014a13435f

A practical walkthrough of deploying FileBrowser Quantum as an HTTP gateway over SMB network shares, issuing scoped long-lived JWT tokens, and wiring the API into Claude Desktop via a local MCP server — so AI agents can access office files without VPN or physical LAN access.

Claude Cowork (and similar browser-based AI agents) can browse web pages but cannot reach SMB/CIFS network shares. Here is how we wrapped our office NAS in an HTTP API so the agent can list, read, search, and write files from anywhere — with proper security controls.

Giving AI Agents Access to Network Drives via an HTTP File Server

{/* banner prompt: A minimal Scandinavian-style office scene with soft, natural light from a window; on a clean light oak desk, an elegant metal padlock and a small white block with a Google Cloud logo are physically separated by a translucent orange glass cube, creating a sense of a clear, frustrating obstacle.

Additional instructions: an unitree style robot as a runner */}

# From App Engine to Cloud Run: A New Chapter

For a long time, Google App Engine (GAE) has been my go-to for hosting web applications. It’s reliable and handles the heavy lifting of infrastructure. However, Google’s **Cloud Run** has emerged as a compelling successor that promises even better cost efficiency and flexibility.

## What is Cloud Run?

Cloud Run is a fully managed compute platform that automatically scales your stateless containers. Unlike App Engine, which has specific language runtimes, Cloud Run allows you to run **any** language, library, or binary because it is built on the **Knative** (Kubernetes-based) standard.

### Benefits vs. App Engine

1.  **Scale to Zero:** Cloud Run is truly "pay-as-you-go." If no one is using your app, it scales to zero instances, and you pay $0. App Engine's standard environment does this too, but Cloud Run's pricing model is often more granular and cheaper for low-to-medium traffic.
2.  **Containerization:** Since it uses Docker containers, the "it works on my machine" guarantee is much stronger. No more worrying about App Engine-specific constraints or proprietary APIs.
3.  **Concurrency:** A single Cloud Run instance can handle up to 250 requests simultaneously, whereas App Engine instances are often more restricted in how they handle concurrent loads.

## Why the "Trading Journal" Project?

For a project like a **Trading Journal**, Cloud Run is a perfect fit:
*   **Cost Efficiency:** This trading tool is built for a small audience and may get very few visitors, if any. Cloud Run is a good fit because it can scale to zero when nobody is using it, keeping the monthly cost minimal.
*   **Fast Iteration:** If this tool ever evolves, the container-based workflow will make it easier to roll out new calculation logic or UI improvements.
*   **Portability:** If we ever need to move to a full Kubernetes cluster or another cloud provider, the Docker image is already built and ready.

---

# The "Gotcha": Domain Mapping & The 24-Hour Wait

After successfully deploying the Trading Journal to Cloud Run, I hit a major roadblock: **Domain Mapping.** 

I mapped [`sprolo.tyosis.com`](sprolo.tyosis.com) to the service, and then... nothing. I waited 24 hours, and the status remained stuck on **"Waiting for certificate provisioning."**

### How it works under the hood
Cloud Run uses a Kubernetes-based technology stack. The domain mapping service behaves similarly to a **Certbot** container. To provide you with a managed SSL certificate, Google must prove to the Certificate Authority (CA) that it controls your domain. It does this via an ACME challenge: the CA looks for a specific token at your domain's IP address.

### Why the mapping failed
The issue was **Cloudflare**. My domain was using Cloudflare's "Proxy" mode (the Orange Cloud). 

When Google's verification bot tried to check the domain, it didn't see the Google servers; it saw **Cloudflare's edge nodes**. Because Cloudflare was hiding the actual IP from the internet, the authentication and validation process could never finish. Google was effectively shouting into a void, waiting for a challenge response that Cloudflare was intercepting.

### The Fix: The "Grey Cloud" Strategy

To solve this, you have to temporarily "step out of the way" of the SSL handshake:

1.  **Grey Cloud the Record:** In Cloudflare DNS, change the `sprolo` CNAME record from "Proxied" to **"DNS Only"** (Grey Cloud). This exposes the `ghs.googlehosted.com` target directly to the public internet.
2.  **Wait for Google:** Once the proxy is off, Google's verification bot can see the challenge data. In my case, the "Ready" status appeared within about 20 minutes after being stuck for a day.
3.  **Re-enable Proxy:** After the Cloud Run domain status shows a green checkmark and "Ready," you can flip the Orange Cloud back on in Cloudflare to regain your CDN and security benefits.

### Summary
If you are moving to Cloud Run and use Cloudflare, don't wait 24 hours like I did. **Turn off the proxy until the certificate is issued.** Once Google has that initial validation, the routing works perfectly even when you turn the proxy back on.


b7b553d54173b5060c799c36adbc1dcfa3c1e5221792729b587fac847d295553

A practical note on fixing a Cloud Run custom domain that stays stuck on 'Waiting for certificate provisioning' behind Cloudflare. Explains why orange-cloud proxying breaks validation and how switching the record to DNS-only lets the SSL certificate complete.

Cloud Run domain mapping can stay stuck on certificate provisioning when Cloudflare proxying blocks Google's SSL validation.

Cloud Run Domain Mappings with Cloudflare: Why Your SSL is Stuck

{/* banner prompt: Of course! Here are three creative and engaging prompts for a banner image, each with a different artistic focus but all reflecting the core idea of the blog post.

---

### Option 1 (Metaphorical & Cinematic)

This prompt focuses on the idea of an AI breaking free from its digital confines to take direct control of a system.

**Prompt:**
> A cinematic digital art masterpiece. On the left side of the frame, a brilliant, glowing AI neural network is trapped inside a transparent, sandboxed cube representing a browser. A powerful, focused beam of light, composed of streaming green `bash` and blue `PowerShell` command-line text, shatters the cube's wall. This beam, representing the Cygwin SSH connection, extends to the right side of the frame, where it elegantly manipulates a complex, holographic 3D model of the Windows operating system. The beam is precisely deleting registry hives, stopping service gears, and cleaning up file system clutter, transforming chaos into order. The overall aesthetic is dark, futuristic, and infused with glowing neon data streams. --ar 16:9

---

### Option 2 (Direct & Illustrative)

This prompt visualizes the conversational aspect and the direct cause-and-effect of the user's request.

**Prompt:**
> A futuristic command center interface. In the foreground, a sleek, floating chat window displays a human's request: `"Uninstall all bloatware and clean the registry."` An AI responds: `"On it. Establishing SSH connection..."`. In the background, a massive, dynamic data visualization of the Windows OS shows the command in action. Streams of code flow from a central SSH terminal icon, targeting and dissolving icons for unwanted programs, while a 3D representation of the Windows Registry is being methodically scanned and cleaned by glowing green cursors. The style is clean, high-tech, and focuses on UI/UX design, with a dark theme and vibrant blue and green highlights. --ar 16:9

---

### Option 3 (Symbolic & Abstract)

This prompt uses symbolism to represent the fusion of two different tech worlds: the open, command-line world and the Windows GUI world.

**Prompt:**
> An abstract digital painting. A stylized, glowing Tux penguin (representing Linux/Cygwin) and a serene, blue AI entity (representing Claude) are working together as one. They are extending their hands, which are made of pure command-line code, through a shimmering portal shaped like the Windows logo. On the other side of the portal, their code-hands are masterfully deconstructing and reassembling Windows components like services, registry keys, and startup items, represented as intricate, glowing geometric shapes. The background is a dark, digital void, emphasizing the powerful and precise nature of the remote management. The lighting is dramatic and symbolic. --ar 16:9

Additional instructions: An AI maid */}

## The Problem with Browser-Based AI Assistants

If you've ever tried to get an AI assistant to help you actually *do* something on your Windows computer — not just tell you *how* to do it — you've probably hit a wall like this:

> *"I don't have direct access to your Windows system settings, so I can't check or change remote connection settings on your behalf."*

> *"I appreciate you asking, but there are a couple of important limitations here: I can't install software on your Windows computer. I have access to a sandboxed Linux environment for running code, but that's separate from your actual Windows system. I have no way to download or install applications like Cygwin or Python onto your PC directly."*

These are real responses from browser-based AI tools like "Claude Cowork" (Claude.ai in a chat window). They're not wrong in this context, but the limitation is narrower than "can only give advice": Claude Cowork can work with local files you expose to it and automate tasks that live inside the Chrome browser. What it still can't do is directly administer your Windows machine end-to-end the way an SSH-connected agent can.

But what if Claude could actually *do* it?

That's exactly what **Claude Code, Codex, Gemini, or any smart agent** with SSH access enables. Once your Windows machine is reachable over SSH, the agent — running on another machine on your network — can log in, run commands, read files, edit the registry, and manage your system end-to-end. No GUI required. No copy-pasting commands. You just ask.

---

## Part 1: The Hard Part — Making Windows SSH-Accessible

The one-time setup requires physical or RDP access to the Windows machine. After that, you'll never need it again.

### Step 1: Install Cygwin with OpenSSH

Download the Cygwin installer from [cygwin.com](https://www.cygwin.com) and install it. During package selection, make sure to include:

- `openssh` — the SSH server and client
- `cygrunsrv` — used to register Cygwin services as Windows services (will be included in standard installation)
- `bash`, `coreutils`, `grep`, `sed`, `awk`, `findutils` — standard Unix tools (often included in standard installation)
- `git` — useful for cloning repositories and working with source code

![](https://storage.googleapis.com/www-tyolab-com-blog-assets/images/blog/2026/04/managing-windows-made-easy-with-cygwin-and-claude/2026-04-15-20-08-42.png)

![](https://storage.googleapis.com/www-tyolab-com-blog-assets/images/blog/2026/04/managing-windows-made-easy-with-cygwin-and-claude/2026-04-15-20-14-53.png)

The default install path is `C:\cygwin64`.

### Step 2: Clone the Setup Scripts

The scripts are available on GitHub. Open a Cygwin terminal (not PowerShell yet) and clone the repo:

```bash
git clone https://github.com/e-tang/installcygwinsshd
cd installcygwinsshd
```

The repo contains two scripts:
- **`installsshd.ps1`** — installs and configures the Cygwin SSHD service
- **`verify.ps1`** — verifies the installation is working correctly

Basically, to install / enable the sshd service:
```bash
ssh-host-config --yes --cygwin 'ntsec' --name 'sshd' --port 22 --user 'cyg_server'
```

### Step 3: Run the Install Script

Open PowerShell **as Administrator** and run:

```powershell
cd C:\path\to\installcygwinsshd
Set-ExecutionPolicy -Scope Process -ExecutionPolicy Bypass
.\installsshd.ps1
```

What the script does:
- Runs `ssh-host-config` inside Cygwin to generate host keys and create a `cyg_server` service account
- Sets the `CYGWIN=ntsec` environment variable (required for proper permissions)
- Opens port 22 in Windows Firewall
- Sets the `sshd` service to start automatically and starts it immediately

### Step 4: Verify the Setup

Still in the Administrator PowerShell, run:

```powershell
.\verify.ps1
```

### Step 4: Set Up SSH Key Authentication

From your Linux/Mac machine (or another machine running a smart agent: e.g. Claude Code), copy your SSH public key to the Windows machine so you don't need a password every time:

```bash
ssh-copy-id username@a-win-machine
```

You'll be prompted for the Windows user password once. After that, all SSH connections use your key. If `ssh-copy-id` isn't available, do it manually:

```bash
# On the client machine, copy your public key
cat ~/.ssh/id_ed25519.pub

# Then on the Windows machine (via password SSH), paste it into:
# C:\cygwin64\home\username\.ssh\authorized_keys
```

Also add the host to your known_hosts to avoid interactive prompts:

```bash
ssh-keyscan a-win-machine >> ~/.ssh/known_hosts
```

Once this is done, you can SSH in silently:

```bash
ssh a-win-machine "uname -a"
# CYGWIN_NT-10.0-19045 a-win-machine 3.6.7-1.x86_64 ...
```

That's it. **The hard part is over.** From this point on, you manage the machine through Claude Code — just by asking in plain English.

---

## Part 2: The Easy Part — Let Claude Do the Work

### Real Example: Removing Riot Games Completely

Here's a real session. I simply told Claude Code:

> *"I need you to remove / delete 'Riot Games' for me"*

Claude SSHed in, found the installation, confirmed before deleting, removed the directories, then I asked it to clean the registry too. Here's exactly what it did — autonomously:

**1. Locate the installation:**
```bash
ssh a-win-machine "find /cygdrive/c -maxdepth 2 -iname '*riot*' -type d 2>/dev/null"
# /cygdrive/c/ProgramData/Riot Games
# /cygdrive/c/Riot Games
# /cygdrive/c/Riot Games/Riot Client
```

**2. Check for running processes before deleting:**
```bash
ssh a-win-machine "tasklist.exe | grep -i riot"
# (nothing running — safe to proceed)
```

**3. Delete the directories:**
```bash
ssh a-win-machine "rm -rf '/cygdrive/c/Riot Games' '/cygdrive/c/ProgramData/Riot Games'"
```

**4. Search the registry for leftover keys:**
```bash
ssh a-win-machine "reg.exe query 'HKLM\\SOFTWARE' /f 'Riot' /k"
ssh a-win-machine "reg.exe query 'HKCU\\SOFTWARE' /f 'Riot' /k"
```

**5. When I mentioned "but it started when the computer starts"**, Claude found it immediately:
```bash
ssh a-win-machine "reg.exe query 'HKCU\\SOFTWARE\\Microsoft\\Windows\\CurrentVersion\\Run'"
# RiotClient  REG_SZ  C:\Riot Games\Riot Client\RiotClientServices.exe --launch-background-mode
```

**6. Deleted the startup entry:**
```bash
ssh a-win-machine "reg.exe delete 'HKCU\\SOFTWARE\\Microsoft\\Windows\\CurrentVersion\\Run' /v RiotClient /f"
```

Total time: a few minutes of conversation. No GUI. No digging through Add/Remove Programs. No regedit hunting. Just asking.

---

## Part 3: What Else Can You Do?

Once Claude Code has SSH access to your Windows machine, the possibilities are broad. Here are examples of tasks you can just *ask* for:

### Software Management

```
"Install Python 3.12 silently"
"Check what version of Node.js is installed"
"Uninstall all Adobe products"
"List all installed programs and their versions"
```

Claude can use `winget`, `choco`, or direct installers:
```bash
ssh a-win-machine "winget.exe install Python.Python.3.12 --silent"
ssh a-win-machine "winget.exe list | grep -i node"
```

### Windows Services

```
"Stop and disable the Windows Search indexing service — it's slowing down the disk"
"Restart the print spooler"
"Show me all services that are set to auto-start but are currently stopped"
```

```bash
ssh a-win-machine "sc.exe stop WSearch && sc.exe config WSearch start= disabled"
ssh a-win-machine "sc.exe query type= all state= all | grep -B1 'STOPPED' | grep 'SERVICE_NAME'"
```

### Startup and Scheduled Tasks

```
"Show me everything that runs at startup"
"Remove that suspicious MLWapp startup entry"
"Create a scheduled task to run a backup every night at 2am"
```

```bash
ssh a-win-machine "reg.exe query 'HKCU\\SOFTWARE\\Microsoft\\Windows\\CurrentVersion\\Run'"
ssh a-win-machine "schtasks.exe /create /tn 'NightlyBackup' /tr 'C:\\backup.bat' /sc daily /st 02:00"
```

### Disk and File Management

```
"Find the 20 largest files on C: drive"
"Delete all .tmp files in AppData"
"How much space is left on each drive?"
```

```bash
ssh a-win-machine "df -h /cygdrive/c /cygdrive/d"
ssh a-win-machine "find /cygdrive/c/Users/dev/AppData -name '*.tmp' -delete"
ssh a-win-machine "du -sh /cygdrive/c/* 2>/dev/null | sort -rh | head -20"
```

### Registry Management

```
"Disable Cortana telemetry in the registry"
"Find all registry keys pointing to a deleted program path"
"Back up the HKCU Software hive before I make changes"
```

```bash
ssh a-win-machine "reg.exe export HKCU\\SOFTWARE C:\\backup\\hkcu_software.reg"
ssh a-win-machine "reg.exe add 'HKLM\\SOFTWARE\\Policies\\Microsoft\\Windows\\Windows Search' /v AllowCortana /t REG_DWORD /d 0 /f"
```

### Network and Firewall

```
"Show me all open ports and what's listening on them"
"Block port 8080 in the firewall"
"What's my current IP address and DNS servers?"
```

```bash
ssh a-win-machine "netstat.exe -ano | grep LISTENING"
ssh a-win-machine "New-NetFirewallRule -DisplayName 'Block 8080' -Direction Inbound -Protocol TCP -LocalPort 8080 -Action Block" 
ssh a-win-machine "ipconfig.exe /all"
```

### System Health and Monitoring

```
"What processes are using the most CPU right now?"
"How long has this machine been running?"
"Show me the last 20 error events from the System event log"
```

```bash
ssh a-win-machine "tasklist.exe /fo csv | sort -t',' -k5 -rn | head -10"
ssh a-win-machine "wmic.exe os get LastBootUpTime"
ssh a-win-machine "powershell.exe -Command \"Get-EventLog -LogName System -EntryType Error -Newest 20 | Format-List TimeGenerated,Message\""
```

### Windows Updates

```
"Check if there are pending Windows updates"
"Install all available updates and tell me when it's done"
```

```bash
ssh a-win-machine "powershell.exe -Command \"Get-WindowsUpdate\"" 
ssh a-win-machine "powershell.exe -Command \"Install-WindowsUpdate -AcceptAll -AutoReboot\""
```

---

## Why This Beats Browser-Based AI

<Table data={{
    headers: ["Capability", "Browser AI (Claude Cowork)", "Claude Code + Cygwin SSH"],
    rows: [
        ["Read files on your PC", "Yes", "Yes"],
        ["Delete files or programs", "Yes", "Yes"],
        ["Edit the registry", "No", "Yes"],
        ["Manage Windows services", "No", "Yes"],
        ["Run PowerShell commands", "No", "Yes"],
        ["Set up scheduled tasks", "No", "Yes"],
        ["Monitor processes", "No", "Yes"],
        ["Install software", "No", "Yes (via winget/choco)"],
        ["Fix startup items", "No", "Yes"],
        ["Works without GUI", "No", "Yes"],
    ],
}}
/>

The browser-based assistant can mostly *advise*. Claude Code with SSH access can *act*. The gap is enormous.

---

## Tips for Day-to-Day Use

**Give your Windows machine a stable local hostname.** Whether via your router's DHCP reservation or `C:\Windows\System32\drivers\etc\hosts` on the client, `ssh a-win-machine` is much nicer than an IP address `ssh 192.168.X.X`.

**Keep SSH keys, not passwords.** Run `ssh-copy-id` once. After that, Claude Code can SSH in without any credential prompts — fully automated.

**Cygwin gives you Unix tools on Windows.** `grep`, `find`, `awk`, `sed`, `curl` all work inside your SSH session. You're not limited to `cmd.exe` syntax. Mix PowerShell (`powershell.exe -Command "..."`) with Unix tools freely.

**Combine with Claude Code's file editing.** Claude Code can read and edit config files directly over SSH, not just run commands. Got a broken `sshd_config`? Claude can fix it in place.

**It's auditable.** Every command Claude runs goes through the SSH session you can see. Unlike opaque agent frameworks, you can watch exactly what's happening.

---

## Conclusion

The one-time setup — installing Cygwin, running two PowerShell scripts, copying your SSH key — unlocks something genuinely powerful: a Windows machine you can manage entirely through conversation.

No more digging through nested menus. No more manually hunting for registry keys. No more wondering which startup entry belongs to which program. You describe what you want, Claude figures out how to do it, and it's done.

Browser-based AI tools will tell you to "open regedit and navigate to...". Claude Code with SSH will just do it.


493da379e7a8b52a12cdf5a80b0a814bcdfc4feb7d7c7f788e2ed9ac85d33547

A practical guide to setting up Cygwin SSHD on Windows and using Claude Code to manage it remotely — far beyond what browser-based AI assistants can do.

Stop fighting with Windows GUIs. With Cygwin, an SSH daemon, and Claude Code, you can manage any Windows machine from the command line — uninstalling software, cleaning the registry, killing startup entries — just by asking.

Managing Windows Made Easy with Cygwin and Claude

{/* banner prompt: Excellent! This is a great blog post that tells a clear story of a problem, a solution, and the resulting empowerment. Here are a few creative and engaging prompts for the banner image, ranging from conceptual to more literal, all designed to capture the essence of the post.

### Prompt Option 1 (Conceptual & Dynamic)

This prompt focuses on the partnership between the human and the AI, showing the AI as a powerful tool that untangles complexity.

**Prompt:**
> A dynamic digital art scene of a developer collaborating with a luminous AI entity. On a holographic interface floating between them, tangled, broken lines of red code representing bugs are being methodically repaired and woven into clean, flowing green code by the AI's energy. In the background, abstract cloud and DNS icons glow softly, symbolizing the Cloudflare API being fixed. The overall mood is one of breakthrough and efficiency, with a sleek, futuristic aesthetic. --ar 16:9

### Prompt Option 2 (Metaphorical & Powerful)

This prompt uses the metaphor of a bridge being repaired, which directly reflects the story of fixing a broken tool to connect the developer's intent to the API's function.

**Prompt:**
> Cinematic digital illustration of a broken bridge made of glowing code connecting a developer's command-line terminal to a massive, stable cloud structure representing the Cloudflare network. A sleek, intelligent AI, depicted as a focused beam of light or a robotic entity, is rapidly reconstructing the broken sections of the bridge, transforming chaotic red error symbols into solid, green success pathways. The scene is set in a dark, high-tech environment, emphasizing the AI as a beacon of solutions. --ar 16:9

### Prompt Option 3 (Direct & Action-Oriented)

This prompt is more direct, showing the "before and after" of the debugging process within a single, compelling image.

**Prompt:**
> A split-view digital artwork in a modern, tech-themed style. On the left, a frustrated developer is looking at a terminal screen filled with red error messages like "Invalid request headers" and "ENOENT". On the right, the same developer now looks confident as a helpful, transparent AI avatar hovers beside the screen, which now displays a stream of green "✓ Success!" messages and successfully executing CLI commands. The AI is pointing to the fixed code, bridging the gap between error and success. --ar 16:9

---

**Recommendation:**

**Prompt 1** is the most balanced and creative. It captures the core themes of AI collaboration, bug fixing, and open-source empowerment in a visually stunning and modern way without being overly literal. It provides the image generator with rich concepts like "luminous entity," "tangled red code," and "flowing green code" to create a unique and engaging banner. */}

## Introduction

In today's fast-paced development world, managing DNS records manually through web interfaces is time-consuming and error-prone. As someone who frequently needs to update DNS configurations across multiple domains, I wanted a better solution—a command-line tool that AI could use to automatically construct and execute commands based on the information I provide.

When I tried to set up domain for my a Google Cloud project, the below are the DNS records I needed to add:

{/* | Type  | Data                      | Alias |
|-------|---------------------------|-------|
| A     | 216.239.32.21             |       |
| A     | 216.239.34.21             |       |
| A     | 216.239.36.21             |       |
| A     | 216.239.38.21             |       |
| AAAA  | 2001:4860:4802:32::15     |       |
| AAAA  | 2001:4860:4802:34::15     |       |
| AAAA  | 2001:4860:4802:36::15     |       |
| AAAA  | 2001:4860:4802:38::15     |       |
| CNAME | ghs.googlehosted.com      | www   | */}

<Table data={
  {
    headers: ['Type', 'Data', 'Alias'],
    rows: [
      ['A', '216.239.32.21', ''],
      ['A', '216.239.34.21', ''],
      ['A', '216.239.36.21', ''],
      ['A', '216.239.38.21', ''],
      ['AAAA', '2001:4860:4802:32::15', ''],
      ['AAAA', '2001:4860:4802:34::15', ''],
      ['AAAA', '2001:4860:4802:36::15', ''],
      ['AAAA', '2001:4860:4802:38::15', ''],
      ['CNAME', 'ghs.googlehosted.com', 'www'],
    ],
  }
} />

And I am too lazy to click through the Cloudflare web dashboard to add them one by one. That's when I discovered [cloudflare-cli](https://github.com/danielpigott/cloudflare-cli) (cfcli), a promising Node.js tool for managing Cloudflare DNS records from the terminal. The vision was simple: I could tell an AI assistant "update these DNS records for my domain," and it would construct the proper cfcli commands and execute them automatically.

But there was a problem — cfcli was broken.

## The Problem: A Broken Tool

### The Configuration File

Cfcli requires a configuration file (`~/.cfcli.yaml`) containing your Cloudflare API credentials. I created mine with the following content:

```yaml
defaults:
   account: work
accounts:
   work:
      token: "p9XvQ2s7LwT8zR4bJ6yNf0c3KjHqWmVtSdFgLbXy"
       email: "eric@tyo.com.au"
       domain: example.com

```

When I first tried to use cfcli, I immediately ran into two critical bugs:

### Bug #1: Missing help.txt File

```bash
$ cd /tmp
$ cfcli help
Error: ENOENT: no such file or directory, open '/tmp/doc/help.txt'
```

Running cfcli from any directory outside its installation folder caused it to crash when trying to display help documentation.


### Bug #2: Invalid Request Headers

```bash
$ node ./bin/cfcli zones
Error response received: Invalid request headers
```

Every API request to Cloudflare was failing with cryptic "Invalid request headers" errors. The tool was completely unusable.

Initially, I used Google Gemini to run cfcli commands and update DNS records for me, but it kept failing due to these bugs. And Gemini simply gave up and asked me to update those records manually.

![](https://storage.googleapis.com/www-tyolab-com-blog-assets/images/blog/2025/10/empowering-open-source-development-with-ai-my-experience-fixing-cfcli/Screenshot_2025-10-04_17-01-24.jpg)

## Why This Mattered

These bugs weren't just inconvenient—they completely blocked my automation workflow. I needed cfcli to work reliably so that AI tools like Google Gemini, Claude Code, OpenAI Codex or others could:

1. **Automatically construct commands** based on natural language requests
2. **Execute DNS updates** without manual intervention
3. **Work from any directory** in my system
4. **Handle bulk operations** like updating multiple A, AAAA, and CNAME records at once

Without a working CLI tool, my entire automation strategy fell apart. I could continue using the Cloudflare web dashboard, but that defeated the purpose of having AI assistance.

## Enter Claude Code: From Broken to Fixed in Minutes

This is where things got interesting. Instead of spending hours debugging Node.js code, diving into axios documentation, and testing different configurations, I simply asked Claude Code to help me fix the bugs.

First, I forked the project to my own GitHub account: [e-tang/cloudflare-cli](https://github.com/e-tang/cloudflare-cli).

Then, I started a new conversation with Claude Code, providing the context about the two bugs I encountered.

Here's what happened:

### Step 1: Reproducing the Bug

Claude Code immediately understood the context and ran the local cfcli to confirm the error:

```bash
$ node ./bin/cfcli zones
Error response received: Invalid request headers
```

### Step 2: Intelligent Debugging

Rather than randomly trying fixes, Claude Code:

1. **Analyzed the codebase** to understand how authentication headers were being set
2. **Checked the axios version** (1.12.0) to identify compatibility issues
3. **Created test scripts** to isolate the problem
4. **Tested different authentication methods** (Bearer token vs. API Key)

Through systematic testing, Claude Code discovered that:

- The newer axios version (1.12.0) sets `Content-Type: undefined` by default
- This undefined header causes Cloudflare's API to reject requests
- The deprecated API Key authentication (X-Auth-Email + X-Auth-Key) doesn't work properly with newer axios versions
- Bearer token authentication works perfectly

### Step 3: The Fix

Claude Code implemented two elegant fixes:

**Fix #1: Remove the undefined Content-Type header**
```javascript
// lib/apiClient.js
const client = axios.create({
  baseURL: 'https://api.cloudflare.com/client/v4',
  timeout: 20000
});

// Remove the Content-Type header set to undefined by axios
// which causes issues with Cloudflare API in newer axios versions
delete client.defaults.headers.common['Content-Type'];
```

**Fix #2: Force Bearer token authentication**
```javascript
// bin/cfcli
let params = { ...config, ...argv };
// Remove email from params to force Bearer token authentication
// The old API Key authentication (email + key) is deprecated and causes issues with newer axios
if (params.token && params.email) {
  delete params.email;
}
```

### Step 4: Fixing the Path Resolution Bug

For the second bug, Claude Code identified that `path.resolve()` returns the current working directory, not the module's directory. The fix was straightforward:

```javascript
// index.js
import { fileURLToPath } from 'url';

const __filename = fileURLToPath(import.meta.url);
const __dirname = path.dirname(__filename);

showHelp() {
  return Promise.resolve(new Result([
    fs.readFileSync(path.join(__dirname, 'doc', 'help.txt'), 'utf8')
  ]));
}
```

### Step 5: Testing and Validation

Claude Code didn't just fix the bugs—it verified them:

```bash
# Test from the project directory
$ node ./bin/cfcli zones
✓ Success! Listed 4 zones

# Test from a different directory
$ cd /tmp && node /data/tyolab/node/cloudflare-cli/bin/cfcli help
✓ Success! Help text displayed correctly

# Test actual DNS operations
$ node ./bin/cfcli add --domain example.com --type A @ 216.239.32.21
✓ Added A record example.com -> 216.239.32.21
```

### Step 6: Proper Git Commits

Claude Code even created well-documented git commits following best practices:

```
commit e9ff7a6
Fix "Invalid request headers" error with axios 1.12.0

This fixes compatibility issues with the newer axios version (1.12.0)...

commit feef4f7
Fix help command path resolution when run from different directory

Changed from using path.resolve() (which returns current working
directory) to using import.meta.url with __dirname...
```

## The Real Magic: AI-Powered Automation in Action

With cfcli fixed, I could finally achieve my original goal. Here's what happened next:

**Me:** "For my domain example.com, please update them with: A 216.239.32.21, A 216.239.34.21, A 216.239.36.21, A 216.239.38.21, AAAA 2001:4860:4802:32::15, AAAA 2001:4860:4802:34::15, AAAA 2001:4860:4802:36::15, AAAA 2001:4860:4802:38::15, CNAME ghs.googlehosted.com www"

Claude Code immediately:
1. Parsed my natural language request
2. Constructed the proper cfcli commands
3. Executed them in sequence
4. Verified the results

```bash
# Added 4 A records
Added A record example.com -> 216.239.32.21
Added A record example.com -> 216.239.34.21
Added A record example.com -> 216.239.36.21
Added A record example.com -> 216.239.38.21

# Added 4 AAAA records
Added AAAA record example.com -> 2001:4860:4802:32::15
Added AAAA record example.com -> 2001:4860:4802:34::15
Added AAAA record example.com -> 2001:4860:4802:36::15
Added AAAA record example.com -> 2001:4860:4802:38::15

# Updated CNAME record
Added CNAME record www.example.com -> ghs.googlehosted.com
```

What would have taken me 15-20 minutes of clicking through the Cloudflare dashboard took **less than 10 seconds** with AI assistance.

## Lessons Learned

This experience taught me several valuable lessons about AI-assisted development:

### 1. AI Excels at Systematic Debugging

Rather than guessing, Claude Code used a methodical approach:
- Reproduce the error
- Analyze the codebase
- Identify the root cause
- Test potential solutions
- Implement the fix
- Verify it works

### 2. AI Understands Context

Claude Code didn't just fix the immediate bug. It understood:
- The purpose of the tool
- The compatibility issues with newer dependencies
- Best practices for path resolution in ES modules
- Proper git commit message formatting

### 3. AI Accelerates Learning

Throughout the debugging process, I learned about:
- How axios handles headers in different versions
- The difference between API Keys and API Tokens in Cloudflare
- ES module path resolution with `import.meta.url`
- Better patterns for CLI tool development

### 4. The Compound Effect of Automation

By fixing cfcli, I unlocked a new level of productivity:
- **Before:** Manual DNS updates through web UI (15+ minutes per domain)
- **After:** Natural language commands to AI → Automatic execution (seconds)

## The Bigger Picture: AI as a Development Multiplier

This story isn't just about fixing two bugs in a CLI tool. It's about how AI tools like Claude Code are fundamentally changing software development:

### From Bug Fixing to Feature Building

Instead of spending hours debugging, I spent minutes. That freed me to:
- Update DNS records for all my domains
- Write this blog post
- Think about other automation opportunities

### From Manual Work to Intelligent Automation

The combination of AI and CLI tools creates powerful workflows:
1. I describe what I want in natural language
2. AI translates it into technical commands
3. AI executes and verifies the results
4. I review and confirm

### From Isolated Tools to Connected Systems

By fixing cfcli, I created a reliable bridge between:
- Natural language (what I want)
- Technical commands (how to do it)
- Cloud APIs (where it happens)

## Conclusion: Life Becomes Easier with AI

The title says it all—life really does become much easier with AI assistance. But not in the way you might expect.

AI didn't replace my understanding or judgment. Instead, it:
- **Amplified my productivity** by handling repetitive debugging tasks
- **Accelerated my learning** by showing me best practices
- **Enabled new workflows** that weren't practical before

The open source community benefits too. Those two bug fixes are now committed to my local fork, ready to be shared back with the project maintainers. You can find the pull request here: [Fix axios compatibility and path resolution bugs in cfcli](https://github.com/danielpigott/cloudflare-cli/pull/95)

This is the promise of AI-assisted development: not replacing developers, but empowering them to focus on what matters—solving real problems and building valuable tools—while AI handles the tedious details.

## What's Next?

With cfcli working perfectly, I'm exploring more automation opportunities:
- Automated DNS configuration for new projects
- Bulk DNS record management across multiple domains
- Integration with infrastructure-as-code tools
- Automated SSL certificate management

The possibilities are endless when you combine AI intelligence with reliable CLI tools.

---

**Have you used AI to debug open source software?** I'd love to hear your stories. Share them in the comments or reach out on Twitter [@_e_tang](https://twitter.com/_e_tang).

**Want to try Claude Code?** Visit [claude.com/claude-code](https://claude.com/claude-code) to get started with AI-assisted development.

---

*This post was written with assistance from Claude Code—the same AI that helped fix the bugs described in this story. Meta, right?*


<ContactFooter />

953434a060c981d93e981a06c73bc6262063fdcf3e68e9b5c962f40a7862f352

A practical story of using AI-assisted development to fix open source software bugs, featuring axios compatibility issues and path resolution problems in the Cloudflare CLI tool.

How Claude Code helped me debug and fix critical bugs in cloudflare-cli, transforming a broken tool into a reliable DNS management solution in minutes.

Tag: Devops

Tag: Devops

Giving AI Agents Access to Network Drives via an HTTP File Server

Cloud Run Domain Mappings with Cloudflare: Why Your SSL is Stuck

Managing Windows Made Easy with Cygwin and Claude

Empowering Open Source Development with AI: My Experience Fixing cloudflare-cli