blog

This series covers prompt patterns for agents that run in a loop: the agent builds something, measures it, improves it, and repeats the cycle the next day without a person supervising. Across this series I cover:

• How to grow a long prompt without it contradicting itself
• How to keep an agent from damaging the machine it runs on
• How to hand an agent a loop it can run without approvals
• How to let real usage tune an interface
• How to get creative output you don’t have to babysit
• How to make the loop improve its own prompts

These patterns are for builders whose agent work looks like mine. I write prompts for Claude Code and hand them to an agent that works on its own for hours. My agents run across many sessions, so the prompt has to carry everything the next session needs to pick up the work. I patch my prompts constantly, and before I used these patterns each patch made the prompt longer and less coherent. These patterns pay off on the second and later cycles of a loop, so one-shot prompts get little from these patterns.

My daughter is old enough to have a phone so she can keep up with her friends. I’ve come to the conclusion that notifications, infinite scroll, and algorithms tuned for engagement are producing adults with limited reasoning and focus. So I gave her a Light Phone. She can text, take photos, and listen to music, and she skips the cognitive denial of service attack that comes with a modern smartphone.

She also needs to start learning how to make things with AI, so I built her an Omarchy workstation. Then I realized a workstation for learning AI was a bit like putting her on a vegan diet. Veggies are nice and all, but learning needs some fun in it. Quake had an outsized influence on my origin story. Quake is the reason I learned TCP/IP networking, and Quake pulled me into hacking and security. Maybe Quake would do the same for her.

So I set out to build a Quake server she could play on with her friends. The project vends a game server, multiplayer clients that run on Mac, Linux, or a mobile browser, and a nightly SportsCenter-style recap of the night’s games, complete with breakfast awards we review the next morning. I wanted the server to make it worth practicing a few Linux commands every day. I wanted an agent to build, run, and keep improving the whole system, on a home server that already runs a bunch of services my family relies on.

Each pattern in this series is a small trick, usually a paragraph or two of prompt text. The value comes from how the patterns stack on each other. I’ve found these patterns produce productivity acceleration similar to compound interest. A savings account that earns interest grows slowly at first and then quickly. Each year’s gain becomes part of the base for the next year. These patterns work the same way for agentic development. A build plan that absorbs every successful experiment makes the next rebuild better. A log of every confusing instruction makes next week’s prompts clearer. Each cycle of the agent’s loop starts from a higher base than the cycle before.

This first post covers how to grow the prompt itself. I couldn’t write my agent’s prompt in one pass, and rewriting the prompt every time a gap showed up kept breaking rules I’d already gotten right. My build loop went through eight rounds. Each round surfaced a requirement I hadn’t planned for, like sudo commands on a shared box, iPads, and an LLM that talks to the kids during play. Each new requirement became a new section added to the prompt instead of a rewrite.

I found these practices produced large amounts of time savings while the prompt grew:

1. Wire every new section into the plan contents list, the acceptance criteria, and the directory layout. The agent decides what to build from the plan contents list, what to test from the acceptance criteria, and where to put files from the directory layout. A requirement missing from the plan contents list, the acceptance criteria, and the directory layout gets skipped. Inserting new sections into the plan’s shared planning section ensures each new requirement built, tested, and stored in accordance with standards for the whole project.
2. Rank your goals in a numbered priority list at the top of the prompt. When two goals conflict, the agent follows the higher-ranked goal instead of guessing. Every rule section must cite a priority number, so each goal keeps a single wording as the prompt grows.
3. Write one interpretation of each ambiguous requirement into the prompt, and tell the person who gave the requirement which interpretation you chose before the agent runs. The person can correct a wrong interpretation with one message, before the agent spends a week acting on the wrong interpretation.

My build objectives

I wrote the priorities first, in rank order, so the agent knows which goal to give up when two goals collide.

1. Protect existing services. Every service on this host keeps running exactly as it runs today. A Quake feature that risks an existing service gets dropped or redesigned.
2. Working LAN Quake. Quake clients on the LAN connect and play fun sessions.
3. Game modes. Deathmatch and Quake Team Fortress work.
4. Web app. A local web app serves players and the operator.
5. Creativity. The experience produces stories the family retells later.

Every rule section in my prompt opens by naming the priority the rule section protects. The standing rules section starts with “Each rule exists to keep priority 1 intact while you work.” When I added a privilege model section three rounds later, the privilege model section cited priority 1 instead of explaining again why the other services matter.

Problem: an agent hits conflicts between goals all the time, and a prompt that states its goals in several places gives the agent several different answers about which goal wins. Say the agent finds that QuakeWorld’s default port, 27500, is already taken by another service on the box. The networking section says players must be able to connect. The safety section says existing services keep running. If each section describes its own goal in its own words, with no ranking between the goals, the agent has no tiebreaker, and the agent could free the port by catastrophically stopping the other service. The wording of goals also drifts apart as the prompt grows, because each new section restates the goals a little differently, and after a few rounds two sections disagree about which goal wins.

Solution: I wrote the goals once, ranked, at the top of the prompt. Each rule section opens by naming the priority number the rule section serves. When two rules conflict, the agent compares the priority numbers of the two rules and follows the rule with the lower number. In the port example, priority 1 protects existing services and priority 2 is working Quake, so the agent picks a different free port and leaves the other service running. Later sections cite a priority number instead of restating the goal, so each goal has exactly one wording in the whole prompt and the sections stay in agreement as the prompt grows.

The pattern that carries over to any prompt: rank your goals once, in one place, and make every rule point to a rank. The ranking gives the agent a tiebreaker the orchestration agent can apply without asking you, and the single wording of each goal keeps new sections from redefining old goals.

Adding a section for each problem

When a new requirement showed up, I added a new headed section to the prompt for that requirement and left the existing sections as they were. My prompt is one markdown file with a heading per topic: priorities, standing rules, and one heading per build phase. Each requirement the file didn’t cover got its own heading. The new requirements showed up in this order:

Round	Problem that came up	Section I added
2	Some steps need sudo and could hurt other services	Privilege Model and Change Control
3	Claude Code on the host can generate content during play	Phase 4B: LLM-Powered Live Experiences
4	Players on iPads and iPhones need a way in	Research topic 10, iPad and iPhone play
5	Touch controls will need dozens of small tweaks	Phase 5B: Apple Device UI Fast Loop
6	I want a daily page that recaps the last session	Phase 4C: The Chronicler Agent
7	I want cheaper models doing most of the work	Orchestration and Model Tiers

Problem: rewriting the prompt to absorb the iPad requirement would have meant touching the server, client, and testing sections at once. This would result in the loss of prompt instructions that I’d worked hard to tune and that produced high quality results.

Solution: I wrote the iPad requirement as its own research topic and left the server, client, and testing sections untouched. A new section can only refer to things the prompt already names, so each new section forced me to name the things the new section needed to point at. The privilege model needed to tell “commands that touch only my project” apart from “commands that touch the whole server,” so I defined privilege tiers. The feature toggles needed a list of features, so I created a feature manifest file. Resuming after an interruption needed a place to read progress from, so I created the STATE/ directory. Every later section points at the privilege tiers, the feature manifest, and the STATE/ directory by name instead of describing them again.

The pattern that carries over to any prompt: when a new section needs to refer to something that only exists as scattered descriptions, give that thing a name and a file. Named things become stable reference points that later sections can cite without redefining them.

Wiring each new section into the build, test, and file lists

After writing a new section, I edit three other places in the prompt: the plan contents list, the acceptance criteria, and the directory layout. The agent reads the plan contents list to decide what to build, the acceptance criteria to decide what to test, and the directory layout to decide where files go.

flowchart LR
    P[Unanticipated problem] --> S[New prompt section]
    S --> A1[Build plan contents]
    S --> A2[Acceptance criteria]
    S --> A3[Directory layout]
    A1 --> B[Agent decides what to build]
    A2 --> T[Agent decides what to test]
    A3 --> F[Agent decides where files go]

Here’s the wiring for iPad support. The iPad research section was the new section. The edits below to the plan contents list, the acceptance criteria, and the directory layout made the agent build, test, and store iPad support.

Plan contents:

- Client bundle contents and install flow for Linux, plus the chosen iPad and iPhone path: browser client hosting and transport bridge, or native app build and install procedure, including any local TLS setup and the per-device onboarding steps.

Acceptance criteria:

- An iPad and an iPhone each complete the documented onboarding and join the same match as a Linux client, with playable frame rate and working touch or controller input.

Directory layout:

  ios-ui/   # Apple device UI configs, envelope, tests, telemetry, fast-loop log

The agent builds and tests iPad support only when the plan contents list and the acceptance criteria both list iPads. The agent builds the items in the plan contents list and tests the items in the acceptance criteria. A prompt with the iPad research section alone would get an agent that researches iPad options, writes a recommendation, and then builds and tests a Linux-only server.

Problem: a requirement described only in its own section stays out of the lists the agent builds and tests from, so the agent researches the requirement and never ships the requirement.

Solution: after adding a section, add a line for the new requirement to the plan contents list, the acceptance criteria, and the directory layout. I use the plan contents edit, the acceptance criteria edit, and the directory layout edit as a checklist every time the prompt grows.

Naming the files each phase produces

Every phase in my prompt ends with an Artifact line listing the files the phase must produce. The agent marks the discovery phase complete when these files exist:

Artifact: STATE/discovery.md, STATE/storage-decision.md, STATE/blog-howto.md,
STATE/healthcheck.sh, STATE/baseline-health.md

The listed files are the documentation for the phase, so the record of the phase is the work the agent already produced. The same files are also where a fresh agent session picks up the work after an interruption.

Stating which interpretation of an ambiguous requirement got encoded

When a requirement could mean two things, the prompt author writes one interpretation into the prompt and tells the person who gave the requirement which interpretation was chosen. I asked for a daily recap page that becomes “viewable the day after the last visit.” The phrase could mean the day after anyone’s visit or the day after a specific kid’s visit. Claude, drafting the prompt with me, chose the day after anyone’s visit, wrote that interpretation into the publication rules, and told me the choice in the same reply. Correcting the interpretation at that point would have taken one message from me. Correcting the interpretation after a week of the agent publishing on the wrong schedule would have meant reading logs to figure out why the page appeared on the wrong days.

What I’d do differently

I worked these practices out while the prompt was already growing. Starting the next project with these improvements in place from the first draft would make each round of growth cheaper.

I’d put empty headings for the plan contents list, the acceptance criteria, and the directory layout into the very first draft.
Why: without the headings in place, wiring each new requirement into the build, test, and file lists depends on my remembering to do it. A section that misses the wiring describes work the agent researches and never builds.
How: start the first draft with a “Plan contents” heading, an “Acceptance criteria” heading, and a “Directory layout” heading, each empty. Every time I add a section, I add one line under each heading in the same edit, so each new requirement reaches the build, the tests, and the file layout in the round I write the requirement.

I’d write the priority list before anything else and add only rules that name the priority they serve.
Why: a rule with no priority behind it gives the agent instructions without a reason, so the agent can’t tell how much the rule matters when the rule conflicts with another rule. Unranked rules also make the prompt longer without making it clearer.
How: write the ranked goals as the first section of the prompt. Before adding a rule, write the priority number the rule protects as the rule section’s first sentence. If no priority fits, either the rule is unnecessary or the priority list is missing a goal, and I fix the priority list first.

I’d keep a dated log of every interpretation chosen for an ambiguous requirement, in the prompt repo.
Why: interpretations get decided in conversation and then disappear from memory. When the agent does something odd months later, I need to know whether the agent is following an interpretation I approved and forgot, or whether the agent is making a mistake.
How: create an INTERPRETATIONS.md file next to the prompt. Each entry records the date, the original requirement wording, the interpretation chosen, the alternative that was rejected, and the prompt section that encodes the interpretation. Check that file first whenever the agent’s behavior surprises me.

Summary

A prompt for a long-running agent grows one requirement at a time, and these practices kept my prompt coherent through eight rounds of growth:

• Rank your goals in a numbered priority list at the top of the prompt, and open every rule section with the priority number the rule serves. The agent uses the ranking as a tiebreaker when goals conflict.
• Add a new headed section for each new requirement and leave the existing, tuned sections as they are. Give a name and a file to anything a new section needs to point at.
• Wire each new section into the plan contents list, the acceptance criteria, and the directory layout, so the agent builds, tests, and stores the new requirement.
• End every phase with an Artifact line naming the files the phase must produce. Those files serve as the phase’s documentation and as the restart point after an interruption.
• Write one interpretation of each ambiguous requirement into the prompt and confirm the interpretation with the person who gave the requirement before the agent runs.

The next post will cover guardrails for keeping an agent from damaging the machine it runs on.

---

---

[part 1] Overview

[part 2] Isolating Claude’s traffic with network namespaces

[part 3] Extracting hostnames from encrypted traffic

[part 4] Decrypting HTTPS with a MITM proxy

[part 5] Classifying all of Claude’s network connections & Analyzing traffic by category

In part 3, we explored pulling hostnames from an encrypted session. In this post, we’ll crack some TLS.

Decrypting HTTPS with a MITM proxy

The hostname extraction helped us discover where scraping is launching from. WebFetch connects directly to target websites from your machine. But hostnames alone don’t reveal what Claude sends in those requests: the HTTP headers, the User-Agent string, the exact URL paths, or the response bodies it receives. To see the full content of Claude’s network traffic and understand exactly what target servers receive and what data flows back, we need to decrypt the TLS.

How MITM proxying works

We use a Man-in-the-Middle (MITM) proxy to read the plaintext content of claude’s HTTPS requests and responses. The proxy sits between claude and the target server, terminating TLS on both sides so it can read the traffic in between:

claude ──TLS──► mitmproxy ──TLS──► example.com
         ▲           │
         │      reads plaintext
         │      request & response
         │
  trusts proxy's CA
  (NODE_EXTRA_CA_CERTS)

1. Claude connects to mitmproxy (thinking it’s the real server)
2. mitmproxy presents a certificate it generated on-the-fly, signed by its own CA
3. Claude accepts this certificate because we told Node.js to trust that CA
4. mitmproxy reads the plaintext request
5. mitmproxy connects to the real server and forwards the request
6. The real server responds; mitmproxy reads the response
7. mitmproxy forwards the response back to claude

mitmproxy now has a complete plaintext transcript of every HTTP request and response.

Example analogy:

A MITM proxy is like a bilingual translator at a diplomatic meeting. Both sides think they’re talking directly to each other, but the translator sits in the middle, receiving every message, reading it, and forwarding it. The key requirement: each side must trust the translator’s credentials. If either side refuses to accept the translator, the communication fails.

Where this analogy breaks down: A real translator can only work if both parties agree to use one. In MITM proxying, the server doesn’t agree to anything. It sees a normal TLS connection from the proxy’s IP address. Only the client must be tricked (or, in our case, explicitly configured) into accepting the proxy’s certificates, so you only need to modify the client’s trust configuration, not the server’s.

Mental Model Check: “MITM is an attack technique.”

MITM interception on a network you don’t control is an attack. MITM proxying on your own machine, for a process you launched, with a CA you generated is a debugging technique. The mechanism is identical for both attacks and debugging. The only difference is authorization context. Burp Suite (penetration testing), Charles Proxy (mobile app debugging), Fiddler (Windows HTTP debugging), and corporate TLS inspection appliances all use the same approach. The claude-mitm.sh script is doing exactly what these tools do, scoped to one process.

Scoping the trust to one process

We scope the trust to one process. We don’t install the mitmproxy CA system-wide. Instead, we set three environment variables only for the claude process:

export HTTPS_PROXY=”http://127.0.0.1:8080″ # Route HTTPS through the proxy
export HTTP_PROXY=”http://127.0.0.1:8080″ # Route HTTP through the proxy
export NODE_EXTRA_CA_CERTS=”$HOME/.mitmproxy/mitmproxy-ca-cert.pem” # Trust the proxy’s CA

Node.js honors both HTTPS_PROXY (route traffic through a proxy) and NODE_EXTRA_CA_CERTS (trust additional CA certificates). These are set only in the shell environment of the claude process. No other process on the system is affected.

We can scope the trust this way because Node.js reads CA certificates from environment variables at startup. That means we can modify the trust configuration of one Node.js process without affecting any other process on the system. If claude were written in Go or Rust, we’d need a different approach. Those runtimes use the system certificate store and don’t honor NODE_EXTRA_CA_CERTS. The environment-variable approach works here specifically because claude is a Node.js application.

Running the MITM capture

Interactive mode (two terminals):

Terminal 1:

./claude-mitm.sh proxy    # Starts mitmweb with web UI at http://127.0.0.1:8081

Terminal 2:

./claude-mitm.sh run      # Launches claude routed through the proxy

Browse to http://127.0.0.1:8081 to see decrypted traffic in real time.

One-shot scripted mode (single command):

./mitm-capture.sh "Use the WebFetch tool to fetch https://example.com and report the title."

This starts mitmdump (the CLI version of mitmproxy) with the mitm_logger.py addon, runs one claude prompt through it, and writes a plaintext transcript to mitm.txt.

Reading the decrypted transcript

grep '^>>> ' mitm.txt    # Every outbound request
less mitm.txt             # Full headers and bodies

Here’s a real captured WebFetch request :

>>> GET https://example.com/
    Accept: text/markdown, text/html, */*
    Accept-Encoding: gzip, compress, deflate, br
    User-Agent: Claude-User (claude-code/2.1.168; +https://support.anthropic.com/)
    Host: example.com
<<< 200 OK  (example.com)
    Content-Type: text/html
    ...
--- response body ---
<!doctype html><html lang="en"><head><title>Example Domain</title>...

What the decrypted traffic reveals

With the TLS removed, we can now see exactly what Claude sends and receives. A few things stand out:

1. User-Agent: WebFetch identifies itself as Claude-User (claude-code/<version>; +https://support.anthropic.com/). Target servers can identify these requests.
2. Content preference: The Accept header lists text/markdown first. claude asks the server for markdown before HTML because markdown is more useful to a language model than raw HTML.
3. Direct connection: The request goes directly to example.com, confirming the SNI evidence from the encrypted traffic analysis. There is no intermediate Anthropic proxy.
4. API calls: You’ll also see POST https://api.anthropic.com/v1/messages. These are the model inference calls containing your prompt, tool results, and the model’s responses.
5. Telemetry: Requests to http-intake.logs.us5.datadoghq.com carrying usage metrics.

Security warning. mitm.txt contains your decrypted API authorization token in plaintext. Look for the Authorization: Bearer sk-ant-... header in every POST to api.anthropic.com. This is your Anthropic API key. It can be used by anyone who obtains it to make API calls billed to your account. The mitm.txt file is .gitignore‘d in the project. Delete it when you’re done: rm mitm.txt. Treat it with the same care as a credential dump.

[part 1] Overview

[part 2] Isolating Claude’s traffic with network namespaces

[part 3] Extracting hostnames from encrypted traffic

[part 4] Decrypting HTTPS with a MITM proxy

[part 5] Classifying all of Claude’s network connections & Analyzing traffic by category

In Part 1, we introduced the idea that coding agents like Claude Code may chose to scrape using a direct request from the host and a proxied request via Anthropic Infrastructure. In this post, we’ll start isolating traffic for an application using namespaces.

Isolating Claude’s traffic with network namespaces

The concept

We use a network namespace to filter out all networking traffic on the host that is unrelated to the claude process. A namespace gives a process its own isolated copy of the Linux network stack. The process in the namespace gets its own interfaces, routing table, iptables rules, and socket space, completely separated from the host. Because claude is the only process inside the namespace, every packet on that namespace’s interface belongs to claude. No filtering or guesswork required.

Example analogy:

Putting the process in a private interrogation room with one-way glass. The process can still make phone calls (network access via NAT), but every call goes through a single monitored line. Nothing else in the building uses that line, so the wiretap is perfectly clean.

Where this analogy breaks down: In a real interrogation room, the person knows they’re being watched. In a network namespace, the process has no way to detect that it’s isolated. It sees a normal network stack with a normal interface and normal routes. The process behaves exactly as it would in the real environment, which means your observations in the namespace are faithful representations of how the process works.

Mental Model Check: “Aren’t namespaces a Docker thing?”

Docker uses namespaces: network namespaces, PID namespaces, mount namespaces, and more. But namespaces are a kernel primitive, not a Docker feature. They’ve existed since Linux 2.6.24 (2008), years before Docker. You can create and manage them directly with ip netns and unshare, no container runtime needed. What we’re doing here is using them at the lowest level (Just the network namespace, nothing else) to get the isolation we need for traffic capture for the process.

The plumbing: veth pairs

We use a veth pair to connect the namespace to the host so claude can still reach the internet. A veth pair is a virtual ethernet cable with two endpoints. Packets entering one end emerge from the other. We place one end inside the namespace (where claude runs) and keep the other end in the host namespace (where we capture). This dedicated link is the only path claude’s traffic can take, which is what makes the capture clean.

Example analogy:

A private FaceTime call between two people. Everything said on the call is only heard by those two participants. No one else’s conversation is mixed in. If you record the call, you capture exactly that conversation and nothing else.

Where this analogy breaks down: A FaceTime call traverses real networks and can suffer latency, jitter, or dropped packets. A veth pair is a kernel data structure where packets pass between the two ends with no measurable delay or loss. It behaves like a direct wire, not a network connection.

┌──────────────────────────┐      ┌──────────────────────────┐
│     Host namespace       │      │    claudesbx namespace   │
│                          │      │                          │
│  ┌──────────────┐        │      │        ┌──────────────┐  │
│  │  veth-host   │◄━━━━━━━╋━━━━━━╋━━━━━━━►│   veth-ns    │  │
│  │ 10.200.1.1   │ veth   │      │  veth  │ 10.200.1.2   │  │
│  └──────┬───────┘ pair   │      │  pair  └──────────────┘  │
│         │                │      │                          │
│   iptables NAT           │      │     claude process       │
│   (MASQUERADE)           │      │     runs here            │
│         │                │      │                          │
│  ┌──────┴───────┐        │      └──────────────────────────┘
│  │  eth0/wlan0  │        │
│  │  (real NIC)  │        │
│  └──────────────┘        │
│                          │
└──────────────────────────┘

We capture at veth-host (the host side of the virtual cable) because every packet claude sends must cross this interface to reach the internet, and no other process’s traffic uses it. That gives us a clean, process-scoped capture with no filtering required.

NAT: Giving the namespace internet access

The namespace gives claude a private IP (10.200.1.2) that doesn’t exist on the real network, so claude can’t reach the internet without help. We set up NAT masquerading to bridge that gap. NAT masquerading is the same mechanism your home router uses for NAT. Outbound packets from 10.200.1.2 get rewritten with the host’s real IP as the source, and return traffic gets translated back. This gives claude full internet access while keeping all its traffic confined to the namespace’s interface where we can capture it.

Three pieces need to be in place for this to work:

1. IP forwarding (sysctl net.ipv4.ip_forward=1) tells the kernel to route between interfaces
2. MASQUERADE rule: rewrite the source IP on outbound packets
3. FORWARD rules: allows traffic to flow between the veth and the real NIC

Mental Model Check: “NAT is just one iptables rule.”

A word of warning: treating NAT as a single iptables rule is a common misconception that causes silent failures. MASQUERADE handles address rewriting, but the kernel won’t route packets between interfaces unless IP forwarding is enabled (net.ipv4.ip_forward), and the default iptables FORWARD policy is often DROP. You need all three: the sysctl, the NAT rule, and the FORWARD ACCEPT rules. Miss any of these changes and the namespace has no connectivity. It drops packets with no error message.

I have a helpful script for creating a network namespace for use with claude called claude-sandbox.sh

claude-sandbox.sh up does the following work, step by step.

Create the namespace an empty, isolated network stack:

ip netns add claudesbx

Create the virtual cable (both ends start in the host namespace)

ip link add veth-host type veth peer name veth-ns

Move one end into the namespace (this is the crucial step)

ip link set veth-ns netns claudesbx

Configure the host side (this becomes the capture point.

ip addr add 10.200.1.1/24 dev veth-host
ip link set veth-host up

Configure the namespace side- this is the process’s gateway

ip netns exec claudesbx ip addr add 10.200.1.2/24 dev veth-ns
ip netns exec claudesbx ip link set veth-ns up
ip netns exec claudesbx ip link set lo up
ip netns exec claudesbx ip route add default via 10.200.1.1

DNS: point the namespace at Cloudflare’s resolver

mkdir -p /etc/netns/claudesbx
echo "nameserver 1.1.1.1" > /etc/netns/claudesbx/resolv.conf

NAT: masquerade namespace traffic out the real interface

sysctl -wq net.ipv4.ip_forward=1
iptables -t nat -A POSTROUTING -s 10.200.1.0/24 -o eth0 -j MASQUERADE
iptables -A FORWARD -i veth-host -o eth0 -j ACCEPT
iptables -A FORWARD -i eth0 -o veth-host -m state --state RELATED,ESTABLISHED -j ACCEPT

Note: The script dynamically detects your uplink interface rather than hardcoding eth0. The actual line is: UPLINK="$(ip route show default | awk '/default/ {print $5; exit}')".

We can configure DNS separately for the namespace because Linux automatically binds /etc/netns/<name>/resolv.conf into it. The kernel’s namespace implementation includes this mount namespace integration, so processes inside the namespace see their own DNS configuration without any explicit mount commands.

Running the capture (privileged path)

This is a two-terminal workflow:

Terminal 1: bring up the namespace and start capturing:

sudo ./claude-sandbox.sh up
sudo ./claude-sandbox.sh sniff    # writes claude.pcap, prints live DNS + TLS SNI

Terminal 2: run claude inside the namespace:

sudo ./claude-sandbox.sh run

Use claude normally Ask it to fetch a URL, run a web search, anything. Watch Terminal 1 for live hostnames. When done:

sudo ./claude-sandbox.sh down     # removes namespace, NAT rules, veth

The rootless alternative

If you don’t want to use sudo, rootless-capture.sh achieves the same isolation using user namespaces:

The rootless-capture script is a helper script that invokes claude and activates packet capture for the namespace without requiring root. You pass it a prompt and it handles orchestrating the creation of the namespace for claude & corresponding packet captures.

 
./rootless-capture.sh "Use WebFetch to fetch https://example.com and tell me the page title."

This creates a user+net+mount namespace as your normal user, attaches slirp4netns for userspace networking, and captures with a custom raw-socket sniffer (nssniff.py).

Why a custom sniffer instead of tcpdump? Inside a --map-root-user namespace, the kernel denies setgroups(). tcpdump insists on dropping privileges at startup (calling setgroups), so it exits without capturing anything. Even with -Z root. nssniff.py opens an AF_PACKET socket and never drops privileges. It writes standard pcap format that any tool can read.

tcpdump’s privilege-dropping behavior is a security feature in normal contexts. It prevents a packet capture process from retaining root powers. But inside a user namespace where setgroups is blocked by design, that security feature becomes a compatibility obstacle. The custom sniffer exists because the “right” behavior in one context is the “broken” behavior in another.

What you now have

Checkpoint: After either path, you have claude.pcap. This is a packet capture containing only claude’s network traffic. This is the foundation everything else builds on.

In Part 3, we’ll explore extracting hostnames of the connection source and destinations from encrypted traffic.

This is an analysis of how Claude Code initiates web scraping requests. You might be surprised to find that claude code could scrape from an API endpoint, or from the host that’s running claude code. In this series, you will learn how to use network namespaces, tcpdump and MITMproxy to isolate a client’s network traffic and experimentally discover whether claude code is scraping content from an api endpoint or from the host that’s running claude code. Code for this project is available at my github.

You installed Claude Code. It ships with built-in network tools (WebFetch & WebSearch) that can reach out to the internet on your behalf. Each use requires your explicit approval (unless you’ve configured auto-approve policies). But here’s the question nobody answers in the documentation:

What exactly does it send and where is it sending requests from?

Inspecting Claude Code’s Network Traffic with Linux Namespaces and MITM Proxying

In the proxied fetch model, the request would route through Anthropic’s servers. The target system sees Anthropic’s IP, and Anthropic’s infrastructure handles the fetched content:

These two models have very different privacy and security implications. Which one does Claude Code actually use? This guide answers that question empirically.

When claude code “searches the web,” whose IP address does the search engine see- yours or Anthropic’s? What telemetry does it send home?

These aren’t hypothetical concerns. If you’re running an AI agent that has built-in network tools on a machine that can reach internal services, you need to know its traffic pattern. This guide shows you how you can discover this behavior directly and what I found during my analysis.

---

What you’ll learn

By the end of this guide, you’ll be able to:

• Isolate a single process’s network traffic on Linux using network namespaces: this technique ensures you won’t have other process’s packets in the capture
• Extract destination hostnames from encrypted TLS traffic using SNI and DNS metadata
• Decrypt HTTPS traffic for a specific process using MITM proxying with mitmproxy, scoped so only that one process is affected
• Classify all traffic the Claude CLI generates: API calls, web fetches, web searches, telemetry, and MCP connections
• Understand the security implications of a local-fetch model: What it means for your LAN and internal services

Prerequisites

You should be comfortable with:

• Linux terminal and shell scripting
• Basic networking concepts (IP addresses, ports, TCP, DNS)
• What tcpdump does (even if you don’t use it daily)
• What TLS/HTTPS provides (encrypted transport)

You’ll need installed:

• Linux with kernel namespace support (any modern distro)
• tcpdump, iproute2 (ip command), iptables
• Python 3 (for the analysis scripts)
• mitmproxy (pipx install mitmproxy or pip install mitmproxy) for the decryption sections
• The claude CLI on your PATH
• slirp4netns for the rootless approach to collecting packets (available in most distro repos)

git clone git@github.com:CaptainMcCrank/claude-netns.git
cd claude-netns
chmod +x claude-sandbox.sh claude-mitm.sh rootless-capture.sh mitm-capture.sh

Key Concepts Before We Start

This guide relies on Linux networking and TLS concepts that may be unfamiliar or counterintuitive.

There is no per-process packet capture on Linux. Linux’s packet capture mechanism (AF_PACKET) attaches to interfaces, not processes. There is no tcpdump --pid. If you capture on an interface shared by every process on the box, you get everything mixed together. The first half of this guide builds a workaround for this using network namespaces.

HTTPS does not hide all metadata. TLS encrypts the payload. The payload includes the URL path, headers, and body. But the destination hostname leaks in plaintext via the TLS SNI extension in every ClientHello, and DNS queries leak it again via standard unencrypted lookups. You can’t read the content, but you can see where traffic goes. That partial visibility turns out to be enough to answer the most important question (where does WebFetch connect?) without any decryption at all.

MITM proxying is a standard debugging technique. The same TLS interception mechanism used by attackers on hostile networks is used every day by Burp Suite, Charles Proxy, Fiddler, mitmproxy, and corporate TLS inspection appliances. Despite the fact that these tools have legitimate applications, many corporate security tools treat them as hacking tools. Only perform MITM Proxying on networks and clients you’re authorized to inspect. Do not proceed if you have any doubts about your authorization for such techniques. While this is all legitimate debugging and auditing, there’s no way for a 3rd party to independently distinguish if this work is an attack or authorized. Many corporate security teams configure monitoring tools to alarm when they see tools such as MITM proxy installed.

Where WebFetch actually connects is an empirical question. Does the request go through Anthropic’s servers, or does it connect directly from your machine? This guide answers that with packet captures.

---

Why a general tcpdump of all traffic fails

The straightforward approach is to capture traffic on your main interface:

sudo tcpdump -i eth0 -n -c 100 -w everything.pcap

Running this while using claude in another terminal produces a capture, but it contains a wall of noise: browser tabs, system update checks, NTP syncs, SSH keepalives, DNS queries from every application on the box. Claude’s traffic is in there somewhere, but finding it requires picking apart hundreds of flows by hand.

You might try filtering by destination:

sudo tcpdump -i eth0 -n host api.anthropic.com -w filtered.pcap

Better- but this requires you to know every destination in advance (e.g. api.anthropic.com). If claude contacts a URL you didn’t predict, you miss it. Additionally- other processes might also contact api.anthropic.com if you have other Anthropic integrations running.

Why this happens

tcpdump filters by network interface, not by process. There is no tcpdump --pid 12345 on Linux. The kernel’s packet capture mechanism (AF_PACKET sockets) attaches to interfaces and your main interface (eth0, wlan0, etc.) carries traffic from every process on the system.

Example analogy:

Trying to record one person’s phone calls by tapping the entire building’s phone line. You hear every tenant: browsers, updaters, background services. There’s no way to isolate one voice because they all share the same wire.

We need a way to give claude its own private network interface that carries only its traffic and nothing else. In Part 2, we’ll explore creating a Linux Namespace that enables us to isolate all network traffic for a specific process.

[part 1] Overview

[part 2] Isolating Claude’s traffic with network namespaces

[part 3] Extracting hostnames from encrypted traffic

[part 4] Decrypting HTTPS with a MITM proxy

[part 5] Classifying all of Claude’s network connections & Analyzing traffic by category