Headless AI Programming: Setting Up a Spare Mac for Claude Code to Control

The Experiment: Giving Claude the Keys to a Spare Mac

A developer known as ykdojo recently documented an experiment that feels like a plot point from a cyberpunk novel. The premise is elegantly simple: take a spare MacBook, strip it down to a headless server state, and hand the reins to Claude Code via SSH. No monitor, no keyboard, no direct human interaction—just an AI agent operating a physical machine through a terminal.

The setup is not a hypothetical. The full walkthrough lives on ykdojo’s blog, and it works. You SSH in from your daily driver, fire up Claude Code, and let it read, write, execute, and even interact with GUI applications through a VNC fallback. The machine becomes a sandboxed worker node in your personal compute cluster, and Claude becomes the operator.

What makes this different from running Claude Code locally? Isolation. You are not polluting your primary development environment with experimental AI-generated scripts, recursive file modifications, or accidental rm -rf incidents. The spare Mac absorbs the chaos. If Claude hallucinates a destructive command, it nukes a burner machine, not your production laptop.

Why This Matters for Engineers and FDEs

For the working engineer, this pattern unlocks a new tier of leverage. But for Forward Deployed Engineers (FDEs), it is practically a superpower. Let’s break down why.

Context Isolation Without VM Overhead

Virtual machines and containers are great until you need bare-metal performance or macOS-specific tooling. Xcode builds, iOS simulator tests, and Metal GPU workloads do not run gracefully inside a Docker container on Linux. A spare Mac solves this. It is native hardware, zero virtualization tax, and completely disposable from a configuration standpoint.

Parallel Agent Execution

Your main machine stays responsive while the agent Mac churns through a long-running task—say, refactoring a legacy codebase or running a multi-hour test suite. You could even chain multiple spare machines, each running a different Claude Code instance on different branches of a monorepo. This is the kind of parallelization that FDEs routinely need when integrating customer systems under tight deadlines. If you want to see how FDEs actually spend their time orchestrating these kinds of workflows, check out our deep dive on what a Forward Deployed Engineer actually does in a week.

The FDE Context

Forward Deployed Engineers operate in customer environments that are often messy, under-documented, and full of surprises. Having a dedicated agent machine means you can point Claude at a customer’s codebase, let it explore, generate integration code, and even write documentation—all without exposing your primary machine to potentially unvetted code. When the engagement ends, you wipe the machine. Clean slate. This maps directly to the essential skills for a Forward Deployed Engineer, where context-switching speed and environmental isolation are critical.

The Architecture: How the Headless Setup Works

The system design is straightforward but worth visualizing before we dive into terminal commands.

The architecture has two primary communication channels. The first is the SSH tunnel, which carries Claude Code’s terminal-based interactions—code generation, file manipulation, git operations, and shell command execution. The second is the VNC channel, which exists as a fallback for GUI-dependent tasks. Claude Code itself is terminal-native, but if you ask it to interact with a macOS application that lacks a CLI, the VNC path lets it control the mouse and keyboard programmatically.

The spare Mac runs in clamshell mode (lid closed) with power nap disabled so it stays awake indefinitely. A static IP on your local network or a Tailscale/WireGuard VPN keeps the connection stable and secure.

Step-by-Step: Configuring Your Spare Mac for Claude Code

Let’s build this. You need two Macs: your primary machine and a spare (any Apple Silicon or Intel Mac that runs a recent macOS). The spare machine will become the headless agent.

1. Prepare the Spare Mac

Start fresh if possible. Wipe the machine and install the latest stable macOS. Create a local admin account—call it agent or something equally descriptive. Do not sign into iCloud on this account unless you have a specific reason. The goal is minimalism.

Disable sleep and screen locking:

# Prevent the Mac from sleeping when lid is closed
sudo pmset -a disablesleep 1
# Disable screen lock (required for VNC to work unattended)
defaults write com.apple.screensaver askForPassword -int 0
defaults write com.apple.screensaver askForPasswordDelay -int 0

Enable automatic login so the machine boots straight to the desktop without a password prompt. This is a security trade-off we will mitigate later. Go to System Settings > Users & Groups > Login Options, and set the agent user to auto-login.

2. Enable Remote Access

SSH is the backbone of this setup. Enable it under System Settings > General > Sharing > Remote Login. Check the box and note the login command displayed—it will look like ssh agent@192.168.x.x.

Configure SSH key authentication from your primary Mac to avoid password prompts:

# On your primary Mac, generate a key pair if you don't have one
ssh-keygen -t ed25519 -C "primary-to-agent-mac"
# Copy the public key to the spare Mac
ssh-copy-id agent@<spare-mac-ip>

Test the connection: ssh agent@<spare-mac-ip>. You should land in a shell with no password prompt.

3. Install Claude Code

Claude Code is Anthropic’s official CLI agent tool. On the spare Mac, install it via npm (requires Node.js):

# Install Node.js if not present (use nvm for flexibility)
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.7/install.sh | bash
nvm install 20
# Install Claude Code globally
npm install -g @anthropic-ai/claude-code

Authenticate Claude Code with your Anthropic API key or via the OAuth flow. Run claude once interactively to complete the setup, then exit.

4. Set Up VNC for GUI Fallback

Claude Code operates in the terminal, but some tasks require GUI interaction—clicking buttons, inspecting rendered output, or controlling applications that lack CLI interfaces. macOS has a built-in VNC server.

Enable it under System Settings > General > Sharing > Remote Management (or Screen Sharing). Set a VNC password. On your primary Mac, use the built-in Screen Sharing app (or a client like RealVNC) to connect to vnc://<spare-mac-ip>.

Headless VNC trick: If the spare Mac has no monitor attached and you get a black screen over VNC, plug in an HDMI dummy plug—a small dongle that emulates a connected display. These cost under $10 and force macOS to render a desktop.

5. Network Configuration

Assign a static IP to the spare Mac via your router’s DHCP reservation, or configure a static IP directly in macOS network settings. This prevents the IP from changing after reboots.

For remote access outside your LAN, set up Tailscale on both machines:

# On both Macs
brew install tailscale
tailscale up

Tailscale gives you a stable WireGuard mesh with IPs in the 100.x.x.x range. Now you can SSH from anywhere without exposing port 22 to the internet.

Security Hardening: Don’t Just Open Port 22

A headless Mac with auto-login and SSH enabled is a juicy target if left unhardened. Here is the minimum defensive posture.

SSH hardening: Edit /etc/ssh/sshd_config on the spare Mac:

# Disable password authentication entirely
PasswordAuthentication no
# Disable root login
PermitRootLogin no
# Only allow your specific user
AllowUsers agent
# Use a non-standard port if you are not using Tailscale
Port 2222

Reload the SSH daemon: sudo launchctl unload /System/Library/Application\ Support/ssh/sshd.plist && sudo launchctl load /System/Library/Application\ Support/ssh/sshd.plist.

Firewall: Enable the macOS application firewall and block all incoming connections except SSH and VNC. Go to System Settings > Network > Firewall, turn it on, and add exceptions only for Remote Login and Screen Sharing.

FileVault: Encrypt the disk. If someone physically steals the spare Mac, the data is unreadable without the recovery key. This is mandatory for any machine that touches customer code.

Network segmentation: Put the spare Mac on a separate VLAN or a guest network if your router supports it. This limits lateral movement if the agent machine is compromised.

API key isolation: Use a dedicated Anthropic API key with usage limits for the spare Mac. Do not reuse your primary development key. If Claude Code goes rogue and burns through tokens, the blast radius is contained.

Real-World Workflows: What to Actually Run

What do you do with a headless Claude Code machine once it is online? Here are three high-signal workflows.

Automated Refactoring Batches

Point Claude at a legacy codebase and give it a refactoring directive. Let it run overnight. In the morning, review the diff over SSH. If you like what you see, merge. If not, reset the repo and tweak the prompt.

ssh agent@<spare-mac>
cd ~/projects/legacy-monolith
claude "Refactor the authentication module to use async/await consistently. Do not change any business logic. Write tests for the refactored code."

Integration Code Generation for FDEs

You are at a customer site. Their API is poorly documented, but they gave you a dump of raw request/response logs. Scrape the logs, feed them to Claude on the headless Mac, and ask it to generate a Python client library. While Claude works, you focus on the customer’s architecture diagrams. This is the kind of parallel execution that makes FDEs dangerous. For more on building tools that automate customer-facing workflows, see our guide on writing customer-facing technical docs that actually get read by engineers.

Incident Response Drill Automation

Simulate an incident by injecting a fault into a staging environment, then ask Claude to triage logs, identify the root cause, and draft a postmortem. This is a direct extension of the pattern we covered in our on-call incident summarizer build. Running it on a dedicated machine means the investigation does not compete for resources with your IDE, Slack, and 47 Chrome tabs.

The Sharp Edges: A Balanced Take

This setup is powerful but not without friction. Let’s be honest about the limitations.

Claude Code is Still a CLI Tool

Despite the VNC fallback, Claude Code’s primary interface is the terminal. It cannot natively inspect visual UI elements or understand pixel-level rendering. If you ask it to “check if the button is blue,” it will struggle unless you write a script that captures a screenshot and pipes it to a vision model. The VNC path is a blunt instrument—it can click coordinates, but it does not understand what it is clicking.

Token Costs Add Up

Claude Code can be chatty. A long refactoring session can easily consume millions of tokens. At Anthropic’s current pricing, that is real money. Set hard usage limits on your API key and monitor them.

Security is a Shared Responsibility Model

You are giving an AI agent shell access to a machine. Even with sandboxing, a cleverly hallucinated command can do damage. Claude Code has guardrails, but they are not bulletproof. Always run it on a machine you can afford to wipe. For a deeper look at the UX pitfalls in AI coding tools—and what they teach us about designing for safety—read our analysis of what Claude Code teaches us about AI tooling UX.

Not a Replacement for CI/CD

This setup is for exploratory, semi-supervised work. Do not wire it into your production deployment pipeline. Claude Code is not deterministic; the same prompt can produce different outputs. Use it for generation, exploration, and first-draft work, then have a human review before anything ships.

The FDE Opportunity

For Forward Deployed Engineers, this pattern is especially compelling because it mirrors how we already work: we set up isolated environments, we automate aggressively, and we move fast in customer contexts where mistakes are cheap if contained. A headless agent Mac is just another tool in that kit—one that can write code while you write strategy.

FAQ

Do I really need a physical spare Mac, or can I use a VM?

You can use a macOS VM (UTM, Parallels, or VMware Fusion), but you lose bare-metal performance and some hardware integration. A physical spare Mac is ideal for Xcode builds, iOS simulators, and GPU workloads. That said, if you just need a sandboxed terminal environment, a macOS VM works fine and is easier to snapshot and reset.

Can I use this setup with other AI coding tools like Codex or Copilot?

Yes, but the integration pattern differs. Claude Code is explicitly designed as an agent that can execute commands and manipulate files autonomously. GitHub Copilot is primarily an editor plugin. You could run VS Code Server on the spare Mac and connect to it remotely, but that is a different architecture. The SSH-plus-CLI-agent pattern is what makes this headless approach clean.

How do I handle macOS updates on the headless machine?

Enable automatic updates in System Settings, but be aware that a macOS update will reboot the machine and may break your SSH session. After a reboot, auto-login should bring the machine back to the desktop, and SSH will be available again. Test this before relying on the machine for long-running tasks.

What if Claude Code generates a command that bricks the machine?

This is why we use a spare Mac. Keep a bootable macOS USB installer handy. Better yet, enable Time Machine backups to a network drive, or use a configuration management tool like Ansible to reprovision the machine quickly. The mean time to recovery should be measured in minutes, not hours.

Is this approach suitable for a team, or is it a solo developer hack?

It is primarily a solo developer pattern today. Multi-user SSH access to a single macOS machine gets messy fast. For team use, consider running multiple headless Mac minis in a rack (yes, Mac minis in data centers are a thing) with a provisioning layer on top. But for individual FDEs and engineers who want a personal AI sandbox, the single-spare-Mac model is perfect.

Where can I learn more about building AI-powered automation like this?

If you want to go deeper into building practical AI tools—whether it is a daily standup bot or a smart clipboard—check out our hands-on build guides like the daily standup bot that collects updates via Slack or the smart clipboard that summarizes and translates anything you copy. These patterns share the same DNA: isolate the AI, give it a focused task, and let it run.