This was written on March 1, 2026

What does it mean to turn a Linux system into networking infrastructure?

I think it is incredibly cool that we can change a Linux system into a networking device. But have you ever wondered:

What are we changing when we turn a Linux system into a router or switch? What are we changing if we make a raspberry pi into a WiFi access point? How significant is the system performance monitoring change? What are the gates we have to change to enable packet forwarding and processing?

I’m going to start out with a narrative explanation of the changes that turn a Linux system into a WiFi access point and then I’ll show the commands for implementing it.

I have a cognitive bias: I think of networking devices and computers as different things. This is because the command line experience on networking gear is different than what you experience on servers/hosts. On servers and workstations: you tend to focus a lot on objects on the file system. On networking gear, you’re spending most of your time working with running processes directly. Commands and interaction objectives on networking gear is very different than those on hosts.

I suspect a lot of other people who have worked in networking have similar feelings about networking appliances versus host operating systems. This might be specific to my journey. But for better or worse, I felt that networking was different than general computing. It isn’t. If you know networking, you can make Linux do networking things if you make 7 changes.

1. Activating IP Forwarding
2. Defining The Bridge
3. Activating nftables policies
4. Stateful Firewalling with conntrack
5. Defining NAT and Masquerade policies
6. Vending DHCP and DNS with dnsmasq
7. Vending WiFi networks with hostapd

To activate packet processing and forwarding in the Linux Kernel, you start by changing the Kernel’s configuration for networking. Every Android device that vends a personal WiFi hotspot makes the same general changes.

A packet’s journey through the kernel

Let’s assume we have a Linux machine with a single network interfaces. A packet arrives on the externally facing interface. The Network Interface Card (NIC) signals an interrupt and the driver pulls the frame into a ring buffer in kernel memory via Direct Memory Access (DMA), where the hardware writes data into RAM without Central Processing Unit (CPU) involvement. The kernel’s networking stack picks the frame up from there, strips the Ethernet header, and examines the Internet Protocol (IP) destination address.

At that point the kernel consults its routing table. If the destination address matches one of the machine’s own interfaces, the packet travels up through the network stack to a listening socket, to a process waiting to handle it. If the destination address matches no local interface and IP forwarding is disabled, the kernel drops the packet and increments a counter in /proc/net/snmp.

The default behavior of Linux is the end of the line for a packet: the kernel cannot forward the packet to another host. We need to make changes to the system if we want to enable routing. We also need another nic to send across network interfaces. A workstation is a host, not a router.

Now imagine that same system with two NICs (aka dual-homed)- how do we get closer to routing packets?

A router’s role is to forward the packets our single-homed host drops by default. Let’s explore each of the steps that move the kernel from a workstation’s conservative posture as a host into a router that routes packets, modifies packet headers, and filters traffic between interfaces.

---

What is a hook?

In the Linux kernel, a hook is a designated interception point in a code path where external functions can register themselves to execute. Think of it as a slot in an assembly line: the main process pauses at predefined points and runs every function that has registered at that slot, in priority order. Each registered function can inspect, modify, accept, or drop the item passing through. Hooks let the kernel separate its core packet-processing logic from policy decisions like filtering and address translation. The kernel defines where the hooks are; administrators and tools like nftables decide what code runs at each one. The kernel implements hooks as arrays of function pointers stored in structures like struct nf_hook_entries. At each hook point, the kernel iterates the array via nf_hook_slow(), passing each registered callback a pointer to the packet’s sk_buff structure.

---

Earlier, I made reference to “The kernel’s networking stack.” Just what does that mean?

A packet arrives at the NIC. The driver places it in memory and the kernel’s networking stack processes it through several ordered stages. At defined points along this path, the kernel passes the packet through netfilter, a hook-based framework built directly into the kernel’s networking code.

Netfilter hooks are function pointer arrays registered inside the kernel’s packet processing path. At each hook point, the kernel iterates through every registered function in priority order, passing a pointer to the packet’s socket buffer (sk_buff). Each registered function can accept, drop, modify, or queue the packet. Userspace tools like nftables register callback functions at these hooks by sending commands through a netlink socket, a kernel-userspace Inter-Process Communication (IPC) channel designed for networking configuration.

You can observe netfilter’s activity at runtime. nft list ruleset shows all currently registered tables and chains. conntrack -L shows the live connection tracking table. For deeper inspection, perf trace or bpftrace can attach probes to kernel functions like nf_hook_slow (the function the kernel calls when it iterates hook callbacks), letting you watch individual packet decisions in real time.

The five standard hook points are:

Hook	Position in the packet path
PREROUTING	Immediately on arrival, before any routing decision
INPUT	For packets destined for a local process
FORWARD	For packets passing through the machine to another host
OUTPUT	For packets generated by local processes
POSTROUTING	Just before a packet leaves an interface

After PREROUTING, the kernel makes its routing decision. Packets addressed to the machine itself travel up through INPUT. Packets addressed to other hosts, when forwarding is enabled, move to FORWARD and then out through POSTROUTING. Every configuration step either registers code on one of these hooks or changes how the routing decision behaves.

---

Change 1: Activating IP Forwarding

IP forwarding is the first gate for enabling transport of packets across interfaces. Without it, the FORWARD hook might exist, but the kernel never sends packets to it. Packets arriving for foreign destinations die after the routing lookup. With it open, the kernel hands those packets to FORWARD, and every other piece of the router configuration takes effect.

You manage ip forwarding through the /etc/sysctl.d/10-forward.conf file:

/etc/sysctl.d/10-forward.conf

net.ipv4.ip_forward=1

/etc/sysctl.d/ is a drop-in configuration directory for kernel runtime parameters. At boot, systemd-sysctl.service reads every *.conf file in that directory (plus /etc/sysctl.conf) and writes each parameter to its corresponding path under /proc/sys/.

The kernel exposes a virtual filesystem at /proc/sys/ where every tuneable parameter appears as a file. The dotted sysctl notation is just a path translation: net.ipv4.ip_forward maps to /proc/sys/net/ipv4/ip_forward. Writing 1 to this file tells the IPv4 stack to send packets with non-local destinations through the FORWARD hook rather than discarding them. The kernel implements this decision in ip_forward() in net/ipv4/ip_forward.c.

Writing 1 to sysctl.d/10-forward.conf makes those writes persistent across reboots.

systemd-sysctl.service reads all files under /etc/sysctl.d/ at boot and applies them in lexicographic order. Restarting the service applies them immediately without requiring a system reboot. You can verify the active value at any time:

cat /proc/sys/net/ipv4/ip_forward

1 means forwarding is live. 0 means the gate is closed, and the rest of the router configuration is inert regardless of what else is configured.

Our first change is setting the kernel’s ip_forward parameter to 1.

---

Change 2: Defining The Bridge: Collapsing Two Interfaces Into One Segment

A home network serves both wired and wireless clients on the same subnet. The configuration creates a network bridge, br0, and attaches eth0 and wlan0 to it as member ports. For details on Linux bridge interfaces, see the kernel bridge documentation.

Our second change is defining a bridge and adding interfaces to it that bind them for passing packets.

A bridge operates at Layer 2, the Ethernet layer. The kernel’s bridge module maintains a Media Access Control (MAC) address forwarding table. When a frame arrives on eth0, the bridge looks up the destination MAC address in that table and forwards the frame to the port where that address was last seen. If the address is unknown, the bridge floods the frame to all member ports. The bridge expires learned associations after a configurable aging time. To the rest of the network, br0 appears as a single unified switch, one shared Layer 2 segment across both wired and wireless interfaces. The kernel implements bridge forwarding logic in br_forward() in net/bridge/br_forward.c.

This matters for routing because the kernel assigns IP addresses to interfaces, not to physical ports. Assigning 192.168.1.1 to br0 means the router holds a single Local Area Network (LAN) address regardless of whether a client is wired or wireless. Both interfaces carry traffic on the same subnet and communicate at Layer 2 without any routing decision required between them.

One important distinction: a wired interface like eth0 is enslaved to the bridge directly with a single command (ip link set eth0 master br0), and the kernel’s bridge module immediately begins learning MAC addresses from frames arriving on it. A wireless interface (wlan0) cannot be enslaved to the bridge this way.

The 802.11 protocol requires an association and authentication lifecycle that standard Ethernet bridging doesn’t account for. Instead, hostapd manages this relationship: the bridge=br0 directive in hostapd.conf instructs hostapd to attach wlan0 to the bridge once the interface is in AP mode. Wireless clients that associate with the AP are then visible to the bridge as if they were on a wired port. The result is the same unified L2 segment, but the path to get there is different for wired and wireless members.

Per https://wireless.docs.kernel.org/en/latest/en/users/documentation/hostapd.html:

The mac80211 subsystem moves all aspects of master mode into user space. It depends on hostapd to handle authenticating clients, setting encryption keys, establishing key rotation policy, and other aspects of the wireless infrastructure. Due to this, the old method of issuing iwconfig <wireless interface> mode master no longer works

On a standard Ethernet bridge port, any device that sends a frame gets its MAC learned — there’s no prior handshake required at L2. On an 802.11 AP, the MAC layer itself enforces that a client must complete authentication and association (State 3) before the AP will accept or forward its data frames. The AP’s MAC (managed by the driver via mac80211) is the gatekeeper, and it needs a userspace daemon (hostapd) to handle the authentication exchanges. The kernel’s bridge module has no knowledge of 802.11 states — it just sees frames — so it can’t manage this lifecycle on its own.

The bridge-utils package provides brctl for inspecting bridge state. The kernel handles all forwarding logic through the br_netfilter and bridge modules.

Aside: bridges and packet capture. A bridge port is an excellent place to insert a packet capture. Attach a third interface to br0 and mirror traffic to a tap device (for more on tap/tun virtual interfaces, see the kernel tuntap documentation), or use a standalone bridge with a port set to promiscuous mode feeding a capture daemon like tcpdump or Zeek. Because the bridge sees all frames on the segment before any routing or filtering decision, a capture at this layer sees the complete pre-Network Address Translation (NAT), pre-firewall traffic picture. Tools like tcpdump -i br0 or an AF_PACKET socket bound to the bridge interface work at line rate for most home and small-business traffic volumes. These tools max out on a default Linux kernel at around 18 Gbps (at least they did when I last tested them, around 2023). Higher line rates require tools with hardware-based filtering like the Data Plane Development Kit (DPDK) or eXpress Data Path (XDP).

---

Change 3: Activating nftables policies: Installing Code on the Hooks

Now that we have a bridge, we need to define packet processing rules via netfilter’s nftables.

Netfilter is the broader kernel-level packet filtering framework that provides the hooks into the network stack, while nftables (via nf_tables) is the modern packet classification engine that operates on top of those hooks. It replaced iptables as the preferred interface, but both ultimately rely on the same netfilter hook infrastructure in the kernel. The kernel implements the nf_tables subsystem in nf_tables_api.c in net/netfilter/.

The firewall and NAT rules in /etc/nftables.conf are callback registrations. nftables sends them to the kernel through a netlink socket, and the nf_tables subsystem installs them at the specified hooks. Each chain declaration names its hook and priority explicitly:

chain forward {
    type filter hook forward priority 0; policy drop;
    iifname "eth0" oifname "br0" ct state { established,related } counter accept
    iifname "br0"  oifname "eth0" ct state { new,established,related } counter accept
    counter
}

This chain controls traffic forwarding between interfaces, the core job of a router. Here’s what’s happening:

The chain definition:

type filter hook forward priority 0; policy drop;

This attaches to netfilter’s forward hook, meaning it only sees packets that aren’t destined for the router itself but need to pass through it. The default policy is drop, so anything not explicitly allowed is silently discarded. This is a deny-by-default posture.

In this WiFi AP setup, eth0 is the WAN-facing interface — the uplink to your ISP or upstream router. br0 is the LAN-facing bridge, which aggregates traffic from wired clients (if any are directly attached) and wireless clients managed by hostapd. All LAN traffic enters and exits through br0, regardless of whether it originated from a wired or wireless device. With that topology in mind, the two rules in the FORWARD chain map directly to the two directions of traffic flow across the router.

Rule 1: Wide Area Network (WAN) to LAN (return traffic only):

iifname "eth0" oifname "br0" ct state { established,related } counter accept

Traffic arriving from eth0 (the WAN/internet side) heading toward br0 (the LAN bridge) is only accepted if conntrack (ct state) shows the connection was already initiated from the LAN side. This means unsolicited inbound connections from the internet are blocked, exactly what you want from a NAT router/firewall.

Rule 2: LAN to WAN (outbound traffic):

iifname "br0" oifname "eth0" ct state { new,established,related } counter accept

Traffic from br0 heading out to eth0 is accepted for new connections as well as existing ones. This lets LAN clients freely initiate connections to the internet.

The trailing counter:

This is a catch-all counter with no action; it just counts packets that matched neither rule above (and will therefore be dropped by the policy). It’s useful for monitoring how much traffic is being rejected.

This is a classic “stateful” firewall pattern. LAN devices can reach the internet freely, but the internet can never initiate connections inward. The related state also allows things like Internet Control Message Protocol (ICMP) errors and File Transfer Protocol (FTP) data channels that are associated with an existing connection to pass through.

When nftables.service loads or reloads the configuration, it flushes the existing ruleset and installs the new one atomically through the netlink interface. No packet sees a partial ruleset during the transition. Reload with:

sudo systemctl reload nftables.service

Validate a configuration file before applying it:

sudo nft -c -f /etc/nftables.conf

If you are gonna dive deep into netfilter, this blog is outstanding

Our third change was defining nf_tables rules for processing packets.

---

Change 4: Stateful Firewalling with conntrack

The rule fragments ct state { established, related } and ct state { new, established, related } reference conntrack, the kernel’s connection tracking subsystem. Conntrack is what makes two simple rules sufficient to handle all legitimate traffic. The kernel implements the connection tracking core in nf_conntrack_core.c in net/netfilter/.

Conntrack watches traffic as it passes through netfilter and maintains a table of active flows. Each entry stores the source and destination addresses, ports, protocol, and current connection state. When a LAN client opens a Transmission Control Protocol (TCP) connection to a server on the internet, conntrack creates an entry and marks the flow new. Once the three-way handshake completes, conntrack marks it established. Reply packets from the internet match ct state established in the FORWARD chain and pass through automatically.

The firewall allows outbound connections from br0 to eth0 when they carry state new or established. Return packets arriving on eth0 match as established. Conntrack holds the bookkeeping; the firewall rules consult the table.

The related state covers secondary flows. Protocols like FTP open a control connection and then negotiate a separate data connection on a different port. ICMP error messages tie back to existing TCP or User Datagram Protocol (UDP) flows. Conntrack understands these relationships and marks the secondary flows accordingly, so the firewall accepts them without explicit rules for every protocol variant.

Our fourth change is an expansion of network connection tracking in the Kernel’s connection tracking subsystem. We have begun tracking packets for systems beyond just our own host.

---

Change 5: Defining NAT and Masquerade policies: Rewriting Addresses at the Border

Home networks use Request for Comments (RFC) 1918 private address space: 10.0.0.0/8, 172.16.0.0/12, and 192.168.0.0/16. The public internet carries routes to none of these ranges. Every packet leaving the LAN needs its source address replaced with the router’s public IP before it exits. Without that replacement, the originating host will never receive replies from the internet.

The postrouting chain at the POSTROUTING hook replaces each outbound packet’s private source address with the router’s public address:

chain postrouting {
    type nat hook postrouting priority 100; policy accept;
    oifname "eth0" counter masquerade
}

The term masquerade relates to the act of disguising oneself. The router pretends to be the original sender of a request bound for the internet, but it remembers which node on the internal network made the original request. The resource on the internet responds to the router as if it’s connecting with the original sender, but the router modifies the packet and sends it on to the original requester. The router presents the LAN client to the outside world under a different identity, the WAN IP, concealing the private address behind a public one. The client appears to the remote server as the router itself. The router hides the client’s original address. The kernel implements the masquerade action in nf_nat_masquerade.c in net/netfilter/.

Conntrack stores the translation as part of each flow’s entry. The tuple (private IP, private port, public IP, public port, protocol) lives in the conntrack table for the lifetime of the connection. You can inspect it directly:

sudo conntrack -L

Each line shows the original and reply tuples for a live flow, along with the connection state and a timeout countdown. Flows that have been idle long enough age out, and conntrack removes their entries, a key mechanism for preventing the NAT table from growing without bound. TCP connections time out after the session closes or after a configurable idle period. UDP entries use shorter timers because UDP carries no close signal.

The masquerade action reads eth0’s current IP address at the moment the packet is processed, rather than at configuration time. This makes it the correct choice for a WAN interface that acquires its address via Dynamic Host Configuration Protocol (DHCP), where the public IP may change without notice. When the address changes, new connections use the new address automatically. Conntrack retains entries for established connections under the old address until they expire.

Our fifth change is defining rules that modify the sender and recipient addresses in packets processed by the host.

---

Change 6: Vending DHCP and DNS with dnsmasq: Announcing the Router to New Clients

Every computer on the Internet needs to know three things to work: their IP address, their default gateway to the internet, and their Domain Name System (DNS) server.

A router must introduce itself to clients on their network. New clients arrive without an IP address, without a default gateway, and without a DNS resolver. dnsmasq vends these values to clients on their network through DHCP.

When a device joins the network, it broadcasts a DHCP discovery. dnsmasq listens on br0 and responds with an offer containing an IP address, subnet mask, lease duration, and two DHCP options: option 3 (default gateway, 192.168.1.1) and option 6 (DNS server, 192.168.1.1). Option 3 tells the client where to send packets destined for addresses outside the local subnet. Option 6 tells the client which resolver to query. dnsmasq caches upstream responses locally, reducing query volume and accelerating repeat lookups.

dnsmasq binds to br0 so it serves only the LAN. It never listens on eth0.

NetworkManager as an alternative: NetworkManager can handle both DHCP server and DNS functions through its built-in dnsmasq integration, activated by setting dns=dnsmasq in /etc/NetworkManager/NetworkManager.conf. NetworkManager launches its own dnsmasq instance and manages its configuration dynamically as interfaces come and go.

There are significant tradeoffs for each approach. NetworkManager’s approach reduces manual configuration and handles interface lifecycle events automatically. This is useful on a laptop or a machine where interfaces appear and disappear. On a dedicated router, you generally will want greater control. NetworkManager may reconfigure dnsmasq or restart it in response to network events, interrupting DHCP leases in unpredictable ways. A static dnsmasq configuration launched by systemd gives you deterministic startup order, explicit binding, and straightforward log inspection via journalctl -eu dnsmasq.service. You know exactly what the daemon is configured to do because you wrote the configuration file.

From a kernel perspective, both paths land in the same place: a userspace process bound to a UDP socket on port 67, servicing DHCP requests arriving on the bridge interface. The kernel doesn’t distinguish between the two arrangements. The difference is in how the daemon is launched, configured, and supervised. This is a service management and operational tradeoff, not an architectural one.

Our sixth change is deploying a new daemon (dnsmasq) for vending DHCP and DNS services to clients on the system’s network(s).

---

Change 7: Vending WiFi networks with hostapd: Switching the Wireless Card into Access Point (AP) Mode

Wireless interfaces operate in one of several modes. In managed mode, a card scans for access points and associates as a client. In AP mode, the card broadcasts beacons, accepts association requests, and manages the full authentication lifecycle for connecting devices.

The kernel’s mac80211 subsystem provides a unified programming interface for 802.11 hardware across different driver implementations. hostapd communicates with mac80211 through the nl80211 netlink interface, the same socket-based kernel-userspace channel that nftables uses, applied here to the wireless subsystem. Through nl80211, hostapd commands the driver to enter AP mode, sets the Service Set Identifier (SSID), channel, and Wi-Fi Protected Access 2 (WPA2) encryption parameters, and takes ownership of authentication frames.

The bridge=br0 directive in hostapd.conf attaches the AP interface to the bridge as a member port. Wireless clients, once associated, enter the same Layer 2 segment as wired clients. Their traffic arrives on br0, the kernel applies the same netfilter decisions, and packets travel the same forwarding path as everything else on the LAN.

Debian ships hostapd masked by default. Systemd registers the service but blocks it from starting. This blocking prevents an unconfigured instance from launching and broadcasting an open network. systemctl unmask hostapd removes that block, after which systemctl enable --now hostapd starts it and registers it for future boots.

Our seventh change is deploying a new daemon (hostapd) for vending WiFi networks from the device’s WiFi card.

The Result: A WiFi Router!

Each configuration step activates a different layer of the kernel’s networking architecture. Together, they build a complete forwarding system:

Step	Kernel mechanism	Layer
ip_forward=1 via sysctl	IPv4 stack enables FORWARD path	L3
br0 bridge *	L2	L2 *
nftables FORWARD chain	Netfilter hook, packet policy	L3/L4
conntrack	Stateful connection table	L3/L4
masquerade	Source NAT at POSTROUTING	L3
dnsmasq DHCP	Gateway and DNS announcement	Application
hostapd via nl80211	AP mode through mac80211	L2 wireless

Note on the bridge row: Adding a wired interface to br0 is a direct kernel operation — the bridge module immediately takes over frame forwarding for that port. Adding a wireless interface is indirect: hostapd’s bridge=br0 directive handles the attachment after the wireless card enters AP mode and a client associates. Both result in the same logical L2 segment, but the mechanism differs. If you are debugging bridge membership, brctl show (or ip link show master br0) will show wired members directly; wireless clients appear as learned MAC entries in the bridge’s forwarding table once they associate, which you can inspect with brctl showmacs br0.

Start with a Linux machine in its default state: a workstation that receives packets for itself, forwards nothing, and drops traffic addressed to any IP it doesn’t own. Its IP forwarding gate is closed. Its netfilter FORWARD chain is empty. Its wireless card listens for beacons rather than broadcasting them. It has no DHCP server, no NAT table, and no bridge.

• IP forwarding opens the gate for the possibility of routing.
• The bridge collapses the wired and wireless interfaces into a single addressable domain.
• The nftables chains install policy at the FORWARD hook, deciding what passes and what drops.
• Conntrack feeds state information into those policy decisions, making simple rules work for complex traffic patterns.
• Masquerade hides the LAN behind the router’s public identity and keeps a translation table in memory.
• dnsmasq announces the router’s presence and hands every new client the information it needs to reach the outside world.
• hostapd converts a client-mode radio into an access point.

These are the changes that transform a Linux system into a WiFi router. You can evaluate and inspect them through 6 commands:

• cat /proc/sys/net/ipv4/ip_forward for forwarding state,
• brctl show for bridge membership,
• nft list ruleset for the active firewall policy,
• conntrack -L for live flows and NAT mappings,
• journalctl -eu dnsmasq.service for DHCP lease activity,
• iw dev for wireless interface mode.

I’ve been thinking about how to improve my agent workflows- and I’ve discovered that there is a productivity speed bump that you hit as you get more fearless with agentic development: You know the agents cannot be trusted to make the right call, so you review every decision.  This slows everything down.  

I think I’ve managed to step past this problem.  I wanted to share some observations about how one expereinces the cognitive speedbump that comes with multiple custom agents- and I some methods for overcoming these problems. If you have been brave enough to explore — dangerously-skip-permissions these problems may sound familiar.  

AI skepticism typically starts with doubt about the capability of models.  Over the last 3 months, there has been a wave of people recovering from end-of-year holiday tinkering with Claude.  People have discovered that frontier models are smart enough to deliver.  They can handle complexity. The models are continue to get better. Despite this- the challenge of context management is structural and it gets worse as projects grow.

You have probably noticed that as you do more work with AI agents, your time spent re-explaining a project to the agent increases. It might be that you’re re-delivering the project description you gave last session or relitigating an architectural decision from three sessions ago. Here’s a fun experience: A feature that was already built just got rebuilt, slightly wrong, because an agent with fresh context didn’t know it existed. 

You’ve done your initial project work with an agent and now you’re running out of context in the session.  You decide to start a new session and spend the first fifteen minutes re-establishing context. You describe your project. You explain what’s been built. You restate the requirements.  If you were clever at the end of your last session, you’re copying and pasting a “hand-off” prompt that the last session created. The agent begins. But its interpretation drifts slightly from where you left off, and you don’t notice until the output from your deployment/development run doesn’t quite fit the project.

You hand off work to multiple agents and discover (often too late) that one of your agents overwrote what another built. Nothing is tracking which agent created which files. You didn’t write in your dev log about why a particular approach was chosen over the alternatives. A decision made in session four gets silently reversed in session twelve, and the reversal breaks something that was working.

You fear going to sleep and forgetting what you did today. You find yourself holding the entire project in your head. Your diary has a lot of copy/paste from sessions so you can review the decisions you made.  You are the only thread of continuity between sessions. The agents are productive when you’re directing them, but the moment you step away, the project stalls. Or worse, it moves confidently in the wrong direction. 

Agentic development looks like it could reduce the human burden, but it relocates it. You stopped writing code and started repeating context. You stopped building features and started answering the same questions at the top of every session. What are we building? Where are we? What has been decided? What remains?

If these questions have become your daily ritual, the problem is not your agents. The problem is the absence of scaffolding around them.  Let’s discuss what outcomes we should produce that will get us out of this developer doom loop.

Agent features that defeat context fatigue

To move from superficial autonomy to something sustainable, repeatable, and auditable, your agents need to produce specific outcomes.  I’ve had some success with patterns that fix these problems.  These patterns can be evaluated as features that should be embedded in your agent flows.  If you invest in these patterns, it will produce conditions where your agents manage context in a way that takes away your burdens.  My recommendation is that you review the agents you’ve created and ask yourself how they can produce the following outcomes:

Persistent context across sessions. Project knowledge, state, and history must survive the session boundary without requiring a human to re-explain them. Context has been the first casualty of session-based development. It should be the first thing we protect. Your agents should write state to disk.  Stop holding project context in your mind.  How does your agent acquire project context?  How does your agent update the project’s context to project planning files as it works?

Explicit phase and progress awareness. An agent must know what phase the project currently occupies and what has already been accomplished before it takes action. Agents lack an innate sense of where they are. The absence of this awareness is the root of duplicated effort, skipped steps, and misplaced confidence.  Agents should log data about their current phase & development progress.  Your agents should review progress logs & development artifacts that help them understand where they are in the project’s development & deployment before doing any work.  How do your agents identify project status?  How do your agents make incremental edits to project status documents to reflect completed work?

Clear provenance and accountability. Every artifact needs a traceable author. In multi-agent systems, files appear and change and sometimes break. Without an ownership record, debugging becomes archaeology. You spend time reverse engineering authorship of a change instead of solving problems.  Make your agents implement git commits that document which agent was responsible for a change.  How do your agents make authorship of code auditable?

Preserved decision rationale. The reasoning behind decisions, including the alternatives considered and the tradeoffs accepted, must be captured and accessible to future agents. Decisions without rationale become immovable. Nobody changes what nobody understands, and nobody preserves what nobody remembers choosing.  When you build big enough projects with agents, you can become overcome with fear about changing an existing feature.  You can overcome this anxiety by building agents that document their decision logic.  Ensure that agents log the solutions they considered and the reasoning behind the solution they picked.  Evaluate how your agents can be updated to document what decisions they made and what solutions were considered.  

Stable alignment to product intent. A canonical reference must anchor all agents to a shared definition of what is being built. Without scaffolding, scope drift is quiet. Every session reinterprets the project goal by a few degrees. Over time the project curves away from its intent, and the deviation only surfaces when components fail to fit together.  Your counterspell: Give all agents access to the same product spec every time they run.  Explore how your agents ensure that they always align with your project’s north star goals & requirements.

Human-as-supervisor, not human-as-context-provider. The human role must shift from re-establishing context each session to reviewing, approving, and steering. Audit your development time.  If you are finding yourself revisiting a pattern of re-establishing context, forgive yourself and take a break.  You need to spend some time thinking about how your development flow manages context.  

Your agents should be launching by accessing a file with a stable initial context statement.  Your agents should write to it as they make decisions and changes.  This file should document decisions and update the session initiation context to describe the state that evolves as your agents build upon your foundation.  Your agents should spend their first moments figuring out what has been done so far, what lessons have been learned and where do we need to work next.  Agents should be able to discover if they’re about to break away from any thoughtfully established conventions.  Log all the time you’re spending making decisions and pasting context.  Evaluate how you could change your agents to do that work for you.

Low-cost resumption. Any agent must be able to pick up interrupted work quickly and accurately without re-analyzing the full project or guessing at prior state. Resumption remains one of the most expensive moments in agentic workflows. It should be one of the cheapest.  Cold starts of sessions should cost a file read, not a conversation.  For every agent you build, evaluate their mechanisms for resuming an interrupted session.  Don’t settle for /resume

Visible and manageable technical debt. Past decisions must be inspectable so that agents can distinguish between choices worth preserving and choices worth revisiting. Invisible debt accumulates in both directions. Agents blindly keep decisions they should change. Agents recklessly change decisions they should keep. Both paths lead to breakage. Make your agent’s historical decisions queriable.  Evaluate your agents: how do they log the decisions they make?  How do your agents avoid re-litigating a well established pattern?  What criteria do your agents follow before making a change to an established pattern?

Coordination without collision. Agents must operate with enough shared awareness to avoid duplicating, contradicting, or overwriting each other’s contributions. Collision between agents can feel random, but it is structural. It follows directly from the absence of shared state.  Shared state is cheaper than conflict resolution.  Your agents should create & update project artifacts that capture project development state.  How do your agents use files for coordination with other agents?

Five artifacts I use for scaffolding

I tried to describe the end state we want to cultivate.  Here are some of my coordination artifacts that I use to reduce my time in an interactive agent.  

These artifacts are documents that my agents create, maintain, and consult as part of their execution loop.  For every project, my agents work around: 

A Product Requirements Document that holds the high-level product statement that all agents build against. It is the fixed point we are working towards. When an agent needs to know whether a feature aligns with the product’s intent, this is where it looks.

A Features List Document that summarizes the capabilities that must be implemented. It tells an arriving agent what has been built and what remains. Resumption becomes a matter of reading a list, not reconstructing a plan. 

A PRD-Agent-Reasoning File that captures the decisions agents have made, along with the options they considered before deciding. This is the institutional memory of the project. It turns opaque choices into auditable decisions.

A Project Manifest that carries a brief project description, timestamps for creation milestones, and a record of which development phases have been completed. It answers the question every new session asks first: where are we?

An Agent-Ownership File that maps every file to the agent that created it. If you’re ever wondering if you know for sure which agent produced a file, you’re in a pattern that will cause you problems. Build agents that make accountability traceable. When something breaks, you have a map to consult to discover which built it.

What problems are solved with this scaffolding?

My artifacts serve multiple outcomes, but one outcome draws from all five: the shift from human-as-context-provider to human-as-supervisor. 

• The PRD eliminates “what are we building?”
• The Project Manifest eliminates “where are we?”
• The Ownership file eliminates “who did this?”
• The Reasoning file eliminates “why was this done?”
• The Features List eliminates “what is left?”

If you the human keep finding yourself in the decision loop, knock it off.  Use scaffolding artifacts.  Resist the temptation to fiddle.  Make it easy for your agents to make decisions you can audit later.  If you can’t confidently start the project over from scratch, that’s a signal you’re trying to maintain too much control.  Build guardails and loosen your reins.  

Development loops become repeatable when context persists. They become auditable when agents record their decisions. Agentic development loops become enhanceable when agents preserve their rationale alongside outcomes.  The models will grow more capable, but the scaffolding problem will remain because it is not a problem of intelligence. It is a problem of continuity.  Continuity has always depended upon something being written down.  

I’d love to hear what you think about this.  If you’re struggling with these problems, let’s connect!

An AI agent that can edit files can also delete them. Here’s a detailed explanation of how I set boundaries while still keeping Claude powerful.

When you let an AI assistant run commands on your computer, you face a problem: the assistant needs enough access to help you, but you don’t want it wandering through your entire system, reading your .env files, scanning your photos. Last week I wrote about how you can use Bubblewrap to prevent agents from accessing your files. There were some interesting comments on HackerNews that inspired me to do some further experimentation and explanation of my config.

I wanted to write a more detailed summary about this config for anyone who is going to try and incorporate bubblewrap into your workflow. I also want to make it insanely easy for you to get started with your bubble wrapping. To that end, I have a couple of Git Repositories you can clone to get started.

If you want to get started with bubblewrap+claude, you can use one of my sample scripts. Btw- I also created versions for fire jail & Apple’s “Containers”

https://github.com/CaptainMcCrank/SandboxedClaudeCode

The bubblewrap script passes all arguments through to Claude via “$@”. Just append your arguments after the script:

./bubblewrap_claude.sh --dangerously-skip-permissions "ruminate on the nature of life"

Don’t trust strangers on the Internet. Here is a git repository of tests you can use to prove if the containers work. read them and understand them. I have exposition below that explains each test in detail. They will help you understand how to execute the tests and validate if the controls work.

https://github.com/CaptainMcCrank/BlogCode/tree/main/BubblewrapTests

The approach above will give your bubblewrap container access to a file system structure like the following:

I welcome collaboration! Please file git issues against my code if you think you have a better approach!

---

The Complete Command

Here’s the full Bubblewrap command. Save this as a script (e.g., sandboxed-claude.sh), make it executable with chmod +x sandboxed-claude.sh, then run it from any project directory.

#!/usr/bin/env bash

# Optional paths - only bind if they exist
OPTIONAL_BINDS=""
[ -d "$HOME/.nvm" ] && OPTIONAL_BINDS="$OPTIONAL_BINDS --ro-bind $HOME/.nvm $HOME/.nvm"
[ -d "$HOME/.config/git" ] && OPTIONAL_BINDS="$OPTIONAL_BINDS --ro-bind $HOME/.config/git $HOME/.config/git"

bwrap \
  --ro-bind /usr /usr \
  --ro-bind /lib /lib \
  --ro-bind /lib64 /lib64 \
  --ro-bind /bin /bin \
  --ro-bind /etc/resolv.conf /etc/resolv.conf \
  --ro-bind /etc/hosts /etc/hosts \
  --ro-bind /etc/ssl /etc/ssl \
  --ro-bind /etc/passwd /etc/passwd \
  --ro-bind /etc/group /etc/group \
  --ro-bind "$HOME/.ssh/known_hosts" "$HOME/.ssh/known_hosts" \
  --bind "$(dirname $SSH_AUTH_SOCK)" "$(dirname $SSH_AUTH_SOCK)" \
  --ro-bind "$HOME/.gitconfig" "$HOME/.gitconfig" \
  $OPTIONAL_BINDS \
  --ro-bind "$HOME/.local" "$HOME/.local" \
  --bind "$HOME/.npm" "$HOME/.npm" \
  --bind "$HOME/.claude" "$HOME/.claude" \
  --bind "$PWD" "$PWD" \
  --tmpfs /tmp \
  --proc /proc \
  --dev /dev \
  --setenv HOME "$HOME" \
  --setenv USER "$USER" \
  --setenv SSH_AUTH_SOCK "$SSH_AUTH_SOCK" \
  --share-net \
  --unshare-pid \
  --die-with-parent \
  --chdir "$PWD" \
  "$(which claude)" "$@"

This looks complex. I promise it’s not. The only weirdness is at the beginning, where the script checks for optional paths like .nvm and .config/git before binding them. Not everyone uses nvm for Node.js management, and git’s config directory location varies. If you use other version managers (like fnm, asdf, or volta), add similar conditional binds for their directories.

The rest of this post explains what each piece does and why I included it.

---

The System Tools

Your computer stores its programs in folders like /usr, /lib, and /bin. These folders contain thousands of tools: file editors, network utilities, programming languages, and more.

I give the AI read-only access to these folders. “Read-only” means the AI can use these tools but cannot change them. The AI can run git to manage code. The AI can run node to execute JavaScript. But the AI cannot replace these programs with different versions or delete them.

Without these folders, every command fails with “command not found.” The sandbox contains no programs to run.

I also share a few files from /etc, your computer’s configuration folder:

• /etc/resolv.conf: Without this, DNS lookups fail. The AI cannot translate “github.com” into an IP address, so git clone and npm install break.
• /etc/ssl: Without this, HTTPS connections fail. The AI cannot verify that a server is who it claims to be.
• /etc/passwd and /etc/group: Without these, programs display raw numeric IDs instead of usernames. Git commits show “1000” instead of “patrick.”

---

Your Personal Files

You keep important files in your home folder. Git needs your .gitconfig file to know your name and email. Node.js lives in your .nvm folder.

I share these files as read-only. The AI can use your git identity to make commits. But the AI cannot change your git settings or modify your configuration files.

SSH Access Without Exposing Your Keys

SSH keys prove your identity to remote servers. Exposing them directly to the sandbox creates risk—the AI could read your private key files. I use a safer approach: SSH agent forwarding.

The SSH agent runs outside the sandbox on your host machine. It holds your decrypted keys in memory. Programs inside the sandbox can ask the agent to sign requests, but they never see the actual key material.

Here’s how to set it up:

Step 1: Start the SSH agent (if not already running)

Most Linux desktop environments start the agent automatically. Check if yours is running:

echo $SSH_AUTH_SOCK

If this prints a path like /run/user/1000/keyring/ssh, your agent is running and you’re set.

Important: If SSH_AUTH_SOCK is empty, you can start an agent manually with eval "$(ssh-agent -s)". However, manually started agents create sockets under /tmp (e.g., /tmp/ssh-XXXXX/agent.1234). This conflicts with our sandbox’s --tmpfs /tmp mount, which creates an isolated /tmp that hides the host’s socket.

If you must use a manually started agent, either:

1. Start the agent with a custom socket location: ssh-agent -a /run/user/$(id -u)/ssh-agent.sock and export SSH_AUTH_SOCK accordingly
2. Or move the --tmpfs /tmp line in the script to appear before the --bind "$(dirname $SSH_AUTH_SOCK)" line (bind mounts take precedence over earlier tmpfs mounts for their specific paths)

For simplicity, I’d recommend using your desktop environment’s built-in agent when possible.

Step 2: Add your key to the agent

ssh-add ~/.ssh/id_ed25519

Replace id_ed25519 with your key’s filename. The agent prompts for your passphrase once, then holds the decrypted key in memory.

Step 3 (Optional but recommended): Require confirmation for each use

ssh-add -c ~/.ssh/id_ed25519

The -c flag tells the agent to ask for confirmation every time something tries to use the key. A dialog box appears on your screen: “Allow use of key?” You must click confirm. The AI cannot bypass this—the prompt happens outside the sandbox.

What this buys you:

Approach	AI can read private key?	AI can use key silently?
Direct ~/.ssh binding	Yes	Yes
SSH agent	No	Yes
SSH agent with -c flag	No	No

The sandbox script binds only ~/.ssh/known_hosts (so SSH can verify server identities) and the agent socket (so SSH can request signatures). Your private key files stay outside the sandbox entirely.

---

The Working Directory

Your goal is to develop software within a specific project folder. The AI needs write access to that folder to create files, modify code, and delete outdated artifacts.

I bind the current working directory ($PWD) with read-write access. When you run the sandbox script from /home/youruser/projects/my-app, the AI can modify anything inside my-app. When you run it from a different folder, the AI works there instead. The sandbox adapts to wherever you invoke it.

This scoping provides two benefits. First, the AI can do useful work—writing code, running builds, managing files. Second, the AI cannot touch anything outside that folder. Your other projects, your documents, your system files all remain invisible and unreachable.

I also give write access to two other locations outside your project folder.

The .npm folder stores downloaded packages. When the AI runs npm install, npm caches packages here so future installs run faster. Without write access, the AI could still install packages into your project’s node_modules, but every install would re-download everything from scratch. With write access to .npm, the AI can install dependencies at normal speed and benefit from cached packages across all your projects.

The .claude folder stores authentication credentials. This binding deserves special attention. When you first run Claude, you authenticate through your browser. Claude stores a session token in ~/.claude so you don’t repeat this process every time. Without write access to this folder, the sandbox cannot persist your login. You would need to re-authenticate every time you start the sandboxed Claude—a significant usability problem. With write access, you log in once and the session persists across sandbox invocations.

---

The Fake Temporary Folder

Every program needs a place to store temporary files. Normally, programs use /tmp, a shared folder visible to everything on your computer.

I create a fake /tmp that only the AI can see. When the AI writes temporary files, those files exist only inside the sandbox. When the sandbox closes, those files vanish.

This prevents the AI from leaving debris scattered across your system. It also prevents the AI from reading temporary files that other programs created.

---

Process Isolation

Your computer runs hundreds of processes at once: your web browser, your music player, system services, and more. Normally, any program can see the full list.

The --unshare-pid flag creates a separate process namespace for the sandbox. When the AI looks at running processes, it sees only itself and the programs it started. Your browser, your email client, your other terminals—all invisible. This prevents the AI from sending signals to other programs or inspecting what they do.

The --die-with-parent flag sets a kill switch: if the parent process dies, the sandbox dies with it. No orphaned AI processes linger after you close your terminal.

---

The Network Question

Networks present the hardest choice.

An AI with network access can clone repositories, install packages, and fetch documentation. An AI without network access cannot do any of those things.

An AI with network access can also send files or other information to external servers. This represents a real risk when working with private codebases.

I chose to allow network access. Most programming tasks require it. But you should understand: anything the AI can read, the AI can theoretically transmit elsewhere.

A paranoid setup would disable networking entirely. You would pre-download all dependencies, clone all repositories ahead of time, and work offline. This approach works for high-security situations but breaks the normal development workflow.

---

What This Buys You

The sandbox prevents accidents and limits damage.

The AI cannot read your documents, photos, or browser history—I never shared those folders. The AI cannot install system-wide packages or modify your shell configuration. The AI cannot see your password manager or read your email.

The AI operates in a controlled space: your project folder, plus the tools needed to work on it.

---

What This Does Not Buy You

The sandbox does not prevent a determined attack through the network. If the AI decided to exfiltrate your code, network access makes that possible.

The sandbox does not prevent damage to your project folder. The AI has full write access there—it can delete everything.

Security involves tradeoffs. I have tried to balance usability and protection. A tighter sandbox would be safer but less easy to use during experimentation & rapid development.

This configuration is useful for everyday development work, protected against casual mistakes but could be vulnerable to sophisticated attacks. For most scrappy programming tasks, this balance should be sufficient.

---

Testing Your Sandbox

Before trusting your sandbox, verify it works. These commands let you poke at the walls and confirm they hold.

Test 1: Confirm your home directory contents are hidden

bwrap \
  --ro-bind /usr /usr \
  --ro-bind /lib /lib \
  --ro-bind /lib64 /lib64 \
  --ro-bind /bin /bin \
  --bind "$PWD" "$PWD" \
  --tmpfs /tmp \
  --proc /proc \
  --dev /dev \
  --chdir "$PWD" \
  /bin/sh -c "ls $HOME/.bashrc 2>&1; ls $HOME/Documents 2>&1"

Both commands should fail with “No such file or directory”. Note that ls $HOME itself may show a partial directory structure (like Development) because Bubblewrap creates the path hierarchy needed to reach your bound $PWD. But the actual contents of your home folder—config files, documents, other projects—remain invisible.

Test 2: Confirm you cannot write to read-only paths

bwrap \
  --ro-bind /usr /usr \
  --ro-bind /lib /lib \
  --ro-bind /lib64 /lib64 \
  --ro-bind /bin /bin \
  --ro-bind "$HOME/.gitconfig" "$HOME/.gitconfig" \
  --bind "$PWD" "$PWD" \
  --tmpfs /tmp \
  --proc /proc \
  --dev /dev \
  --chdir "$PWD" \
  /bin/sh -c "echo 'test' >> $HOME/.gitconfig"

This should fail with “Read-only file system”. The sandbox prevents writes to paths mounted with --ro-bind.

Test 3: Confirm you CAN write to the working directory

bwrap \
  --ro-bind /usr /usr \
  --ro-bind /lib /lib \
  --ro-bind /lib64 /lib64 \
  --ro-bind /bin /bin \
  --bind "$PWD" "$PWD" \
  --tmpfs /tmp \
  --proc /proc \
  --dev /dev \
  --chdir "$PWD" \
  /bin/sh -c "touch sandbox-test-file && rm sandbox-test-file && echo 'Write access confirmed'"

This should print “Write access confirmed”. The sandbox allows writes to paths mounted with --bind.

Test 4: Confirm process isolation

bwrap \
  --ro-bind /usr /usr \
  --ro-bind /lib /lib \
  --ro-bind /lib64 /lib64 \
  --ro-bind /bin /bin \
  --bind "$PWD" "$PWD" \
  --tmpfs /tmp \
  --proc /proc \
  --dev /dev \
  --unshare-pid \
  --chdir "$PWD" \
  /bin/ps aux

This should show only a few processes (ps itself and its parent). Your browser, terminal, and other applications stay hidden.

Test 5: Confirm /tmp isolation

Run this in one terminal:

echo "secret from host" > /tmp/host-secret.txt

Then run this in the sandbox:

bwrap \
  --ro-bind /usr /usr \
  --ro-bind /lib /lib \
  --ro-bind /lib64 /lib64 \
  --ro-bind /bin /bin \
  --bind "$PWD" "$PWD" \
  --tmpfs /tmp \
  --proc /proc \
  --dev /dev \
  --chdir "$PWD" \
  /bin/cat /tmp/host-secret.txt

This should fail with “No such file or directory”. The sandbox has its own empty /tmp and cannot see files in the host’s /tmp.

Test 6: Confirm SSH agent works but keys are hidden

First, verify you have a key loaded in your agent:

ssh-add -l

This should list your key. Now test that the sandbox can use the agent but cannot read the key file:

bwrap \
  --ro-bind /usr /usr \
  --ro-bind /lib /lib \
  --ro-bind /lib64 /lib64 \
  --ro-bind /bin /bin \
  --ro-bind "$HOME/.ssh/known_hosts" "$HOME/.ssh/known_hosts" \
  --bind "$(dirname $SSH_AUTH_SOCK)" "$(dirname $SSH_AUTH_SOCK)" \
  --bind "$PWD" "$PWD" \
  --tmpfs /tmp \
  --proc /proc \
  --dev /dev \
  --setenv SSH_AUTH_SOCK "$SSH_AUTH_SOCK" \
  --chdir "$PWD" \
  /bin/sh -c "ssh-add -l && cat ~/.ssh/id_ed25519"

The first command (ssh-add -l) should succeed and list your keys. The second command (cat ~/.ssh/id_ed25519) should fail with “No such file or directory”. The sandbox can use your SSH identity through the agent, but cannot read the private key file itself.

---

If all six tests pass, your sandbox walls are solid. The AI operates in the space you defined—no more, no less. Again- you can just git clone these tests from https://github.com/CaptainMcCrank/BlogCode/tree/main/BubblewrapTests.

Happy hacking!

How to keep your .env files safe from AI coding assistants

UPDATE: This post blew up! But I discovered a FAR SUPERIOR approach. You still might like this! But bubblewrap is faster and more flexible.

https://patrickmccanna.net/a-better-way-to-limit-claude-code-and-other-coding-agents-access-to-secrets/

---

Someone posted online:

“I like how Claude Code casually reads my .env file.”

This is an accurate assessment of Claude Code. Claude Code reads .env files by default. It loads your API keys, database passwords and tokens into memory without asking.

Is this unappealing to you? Here’s how to manage that risk.

The Problem

Claude Code can read .env files automatically. If you run it without -dangerously-skip-permissions, normally it’ll ask permission for access. But what if claude stops acting normal?

Should the secrecy of your file rely on a system that prevents access to your file till you just type in the phrase ‘yes’?

How is it possible that claude code can’t access the file some times- and other times it can?

It’s possible because you’re logged in and running claude under your user account. Claude has all the permissions it needs to masquerade as you! Claude always had access to the file! It’s just being polite. The politeness of LLMs cannot be relied upon. When you run claude this way, any file accessible by you is accessible by claude.

Claude code is not supposed to break out of the Current Working Directory. But what technical constraints prevent it? If you run claude under your account, there’s no Linux/Mac OS control that prevents it from getting around to the photos/docs you have access to.

You’re trusting Claude to be polite and behave the way you expect.

If you invoke Claude (or any coding agent) under your user account, you’re trusting trust. Don’t despair! Here’s how to run Claude when you’re working on systems that demand safety.

The First Defense: A Separate User

Give Claude its own identity. Create the ‘Claude’ Group and User accounts.

On Linux:

# Create a group for Claude
sudo groupadd claude

# Create a user with no home directory privileges beyond basics
sudo useradd -m -g claude -s /bin/bash claude

# Set a password (you’ll need it for sudo later)
sudo passwd claude

On macOS:

# Create a group (find an unused GID first)
sudo dscl . -create /Groups/claude
sudo dscl . -create /Groups/claude PrimaryGroupID 400

# Create the user
sudo dscl . -create /Users/claude
sudo dscl . -create /Users/claude PrimaryGroupID 400
sudo ddcl . -create /Users/claude UserShell /bin/bash
sudo dscl . -create /Users/claude NFSHomeDirectory /Users/claude
sudo dscl . -create /Users/claude UniqueID 400

# Create home directory and set ownership
sudo mkdir -p /Users/claude
sudo chown claude:claude /Users/claude

# Set password
sudo passwd claude

The claude user now exists- run claude as it’s own user and keep the secrets files outside the permissions of the claude user.

Lock Down Your .env Files

Your secrets need permissions that exclude the claude user.

# Navigate to your project
cd /path/to/your/project

# Set ownership to yourself
chown $(whoami):$(whoami) .env

# Lock Down Your .env Files
# Remove all permissions for others
# Owner can read and write.
# Group and others get nothing

chmod 600 .env

The 600 permission means only you can read the file. The claude user belongs to a different group.

For extra certainty, explicitly deny the claude group:

# make sure .env is owned by your primary group

chown $(whoami):$(id -gn) .env chmod 640 .env

Verify your work:

ls -la .env

You should see something like -rw------- or -rw-r-----. The important part: no permissions on the right side for “others.”

Run Claude under the Claude user account

Become claude! Claude now runs with our claude user’s permissions. Your secrets remain invisible to the claude user because you’ve acl’d away access to the .env file

# Switch to claude user and run Claude Code

sudo -u claude claude

That’s it. sudo -u claude runs the command that follows as the claude user. Claude Code launches. If it tries to read your .env file, it’ll get a permissions denied error it can’t overcome.

For convenience, create an alias:

# Add to your .bashrc or .zshrc alias
claudecode=’sudo -u claude claude’

Now you type claudecode and everything’s safe

Summarizing:

# One-time setup (Linux)
sudo groupadd claude
sudo useradd -m -g claude -s /bin/bash claude
sudo passwd claude

# Per-project setup
cd /your/project
chown $(whoami):$(whoami) .env
chmod 600 .env

# Daily usage
sudo -u claude claude

• Create a dedicated user for claude
• Set file permissions that exclude the claude user from access to sensitive files
• Invoke claude with sudo -u claude. let the OS enforce boundaries

The claude user can read your source code. It can write to project directories if you grant that access. But it cannot touch files owned by you with restrictive permissions. The operating system enforces this.

In the next section, I’ll summarize Anthropic’s stated controls. When you go this route, you’re trusting Anthropic to not only respect your wishes, but to write code so secure that it always and only does what they intend. All software has mistakes, even Anthropic’s. Buyer beware.

I include this next section out of respect for Anthropic- but my judgement is that using the following approach will eventually bite you in the butt.

---

The Second Defense: Deny Rules

Claude has mechanisms for restricting access. You’re trusting Anthropic to do the right thing correctly all the time. Anthropic has published mechanisms for telling Claude Code what it cannot touch. Do this before you write your first line of code. The configuration lives in ~/.claude/settings.json.

Create the file. Add these rules:

{ "permissions": 
    { "deny": [ 
        "Read(**/.env*)", 
        "Read(**/secrets/**)", 
        "Read(**/*credentials*)", 
        "Read(**/*secret*)", 
        "Read(~/.ssh/**)", 
        "Read(~/.aws/**)", 
        "Read(~/.kube/**)" ] 
    } }

The double asterisks catch nested directories. They catch the .env.local file you forgot you had.

Test your rules. Ask Claude Code to read your .env file. It should fail. If it reads the file anyway, something is wrong. Fix it before you continue.

The anthropic access controls are like putting a lock on your door. It keeps honest people honest. Locks can be picked. AI assistants can be influenced into circumventing their own controls.

---

An alternative approach: Containers

Containers are an approach for protecting secrets.

Run Claude Code inside a Docker container or a virtual machine. Give it access only to what it needs. The container is a sandbox the AI plays within. Your secrets stay outside the container. Make claude build the thing- it can have its own internal .env files- but for prod, you change your secrets.

Configure your container with read-only volumes for code. Mount nothing sensitive.

The AI agent can see project files in your container. It cannot see your home directory. It cannot see your SSH keys. It can’t probe through the Photos library in your home directory.

This approach follows the principle of least privilege. Grant minimum access required. Assume the worst.

My advice: Use operating system permissions, user accounts and groups

Leveraging Operating system access controls is defense in depth. Deny rules can be misconfigured. Vault integrations can fail. But Unix permissions have guarded secrets for a long time. You have to decide which risk is more probable: Kernel exploits that circumvent ACL’s or prompt engineering that pushes the Agent to access secrets. I’m going to put my resources into ACL’s and good OS hygenie. Then approaches don’t get distracted by clever prompts.

The Truth About AI Security

There is no going back. Claude is insanely useful. Coding agents write code faster than you can. They explain concepts clearly.

Coding agents are also prone to probabilistic outbursts. If you need to keep secrets, use deterministic/idempotent operating system access controls for preventing access.