Running a SPIRE Agent on macOS by Building It Yourself

On this page
SPIRE 1.16.0 comes with release builds for Linux and Windows. There is no macOS download. For a design where a Mac may need a SPIFFE identity, that looked like a dead end until we tried the obvious thing: SPIRE is written in Go, so build it.
It works. Here’s the build, what makes it work on macOS, and a local end-to-end test that issues a real certificate.
Build the agent #
You need Go and the SPIRE source at a release tag. We used Go 1.27 on Apple Silicon.
git clone --depth 1 --branch v1.16.0 https://github.com/spiffe/spire.git
cd spire
CGO_ENABLED=0 go build -o out/spire-agent ./cmd/spire-agent
file out/spire-agent
out/spire-agent: Mach-O 64-bit executable arm64
The agent needs no cgo. The binary is large (about 110 MB) because it carries every plugin.
Why it actually works on macOS #
A binary that compiles isn’t the same as one that works. The part that matters is the Workload API: when a process asks the agent for an identity, the agent has to find out which process is asking. On Linux it reads the peer credentials of the Unix socket.
SPIRE has a separate implementation for the BSD family, and macOS is part of it. The peer tracker files carry this build constraint:
//go:build darwin || freebsd || netbsd || openbsd
On macOS the agent asks the socket for the caller’s PID (LOCAL_PEERPID) and uses kqueue to notice when that process exits, so a PID can’t be reused to steal an identity. The fallback that returns “unsupported platform” is only built on other systems.
The unix workload attestor then turns the caller into selectors: uid, user, gid, group, and with discover_workload_path = true also the binary’s path and sha256. That last pair lets you tie an identity to one specific executable, not just to a user.
A local end-to-end test #
To prove it, we ran a throwaway SPIRE server and the agent on the same Mac. The server isn’t the point here, so we built it locally too. Its SQLite datastore needs cgo, which the agent doesn’t:
CGO_ENABLED=1 go build -o out/spire-server ./cmd/spire-server
Without cgo the server starts and immediately stops with:
datastore-sql: sqlite3 is not a supported dialect when CGO is not enabled
Keep the sockets on a short path. macOS limits Unix socket paths to about 104 characters, and a deep working directory breaks the agent with a confusing connect: invalid argument. We put the sockets in a fresh directory under /tmp.
server.conf:
server {
bind_address = "127.0.0.1"
bind_port = "18081"
socket_path = "/tmp/spire-demo/api.sock"
trust_domain = "poc.test"
data_dir = "./server-data"
}
plugins {
DataStore "sql" {
plugin_data {
database_type = "sqlite3"
connection_string = "./server-data/datastore.sqlite3"
}
}
KeyManager "memory" { plugin_data {} }
NodeAttestor "join_token" { plugin_data {} }
}
Start the server, create a join token for the Mac and register an identity for your own user ID:
mkdir -p /tmp/spire-demo
./out/spire-server run -config server.conf &
./out/spire-server token generate \
-socketPath /tmp/spire-demo/api.sock \
-spiffeID spiffe://poc.test/node/mac
./out/spire-server entry create \
-socketPath /tmp/spire-demo/api.sock \
-parentID spiffe://poc.test/node/mac \
-spiffeID spiffe://poc.test/workstation/$(id -un)/claude-code \
-selector unix:uid:$(id -u)
./out/spire-server bundle show \
-socketPath /tmp/spire-demo/api.sock > bundle.pem
agent.conf:
agent {
data_dir = "./agent-data"
server_address = "127.0.0.1"
server_port = "18081"
socket_path = "/tmp/spire-demo/agent.sock"
trust_bundle_path = "bundle.pem"
trust_domain = "poc.test"
}
plugins {
NodeAttestor "join_token" { plugin_data {} }
KeyManager "memory" { plugin_data {} }
WorkloadAttestor "unix" {
plugin_data { discover_workload_path = true }
}
}
Start the agent with the token, then ask it for an identity as your normal user:
./out/spire-agent run -config agent.conf -joinToken <token> &
./out/spire-agent api fetch x509 \
-socketPath /tmp/spire-demo/agent.sock -write .
Received 1 svid after 312.761333ms
SPIFFE ID: spiffe://poc.test/workstation/pderuiter/claude-code
SVID Valid After: 2026-11-18 15:21:39 +0000 UTC
SVID Valid Until: 2026-11-18 16:21:49 +0000 UTC
The certificate carries the SPIFFE ID as a URI SAN and is valid for one hour. The agent rotates it before it expires.
openssl x509 -in svid.0.pem -noout -ext subjectAltName
X509v3 Subject Alternative Name:
URI:spiffe://poc.test/workstation/pderuiter/claude-code
If your first fetch logs No identity issued, give it a few seconds. The agent syncs registration entries from the server on an interval, and a fetch that arrives before the first sync finds nothing.
What this doesn’t give you yet #
This test proves the agent runs on macOS. It isn’t a production setup:
- Node attestation. A join token is single-use. If the agent loses its state, it needs a new token. A device certificate (the
x509popattestor) lets the Mac attest again by itself, at the cost of a key in a file. There’s no attestor for the Secure Enclave. - The identity is “processes of this user on this Mac”. Add the
pathorsha256selectors if you want to narrow it to one binary, and accept that every update changes the hash. - Run it as a service. In practice that means a launchd agent and a socket path every client agrees on.
- Build it in CI and sign it. You’re running a security component you compiled yourself, so treat it like any other artifact you ship.
Do you even need it? #
In our MCP design, mostly not. The interactive AI tools on a Mac can sign in to the gateway with Keycloak OAuth, which works on every operating system. The macOS agent becomes useful when an unattended workload runs on the Mac and needs its own identity, the same way our Kubernetes and Linux workloads get theirs.
It’s good to know the option is a go build away and not a missing platform.
Get new posts by email
One mail when a new article goes live: what it covers and a link. No tracking pixels, unsubscribe in one click.


