Nº 014/Engineering/5 min read/
The Go Implementation
Building AgentSecrets in Go was not the obvious choice. We had a working Python codebase in secretscli, the team knew Python, and the AI ecosystem we were building for runs primarily on Python. Starting over in a different language had a real cost.
The decision came down to one requirement that Python could not satisfy cleanly: we needed to ship a single binary that anyone could install without caring what runtime it needed.
What the binary requirement actually meant
The proxy is not a library. It is a long-running process that sits between an agent and the network, manages OS keychain access across three different operating systems, handles concurrent HTTP requests, and needs to start and stop cleanly. A library you pip install does not behave like that. It lives inside a Python process someone else controls, and you inherit whatever that process does.
When a developer installs AgentSecrets, we want them to run one command and have a working proxy, not work through a setup process involving Python versions, virtual environments, and pip installs before the proxy starts. That requirement pointed away from Python before we had written a line of the new codebase.
Go compiles to a static binary with no external dependencies, so the developer gets a file they can run anywhere through Homebrew, direct download, or go install, with the runtime embedded and nothing to configure.
The keychain work
Cross-platform keychain access was the first significant Go implementation challenge. macOS Keychain, Linux Secret Service, and Windows Credential Manager are three completely different systems with different APIs, different access control models, and different behaviours when things go wrong.
The Go ecosystem has libraries for all three, but using them in production required understanding the failure modes for each platform rather than just the happy path. On macOS, the keychain prompts for permission in certain contexts and not others, and the behaviour depends on whether the process has the right entitlements. On Linux, the behaviour depends on whether a keychain daemon is running, and in headless environments it often is not. On Windows, DPAPI ties encryption to the user account in ways that matter if you are thinking about what happens when credentials are migrated between machines.
We spent time on those edge cases before they became user-reported bugs, which is the right order. The abstraction layer we ended up with is clean enough that the rest of the proxy code does not need to know which platform it is running on, but that cleanness was earned by understanding the messy underlying reality first.
Concurrency and the proxy design
The proxy handles multiple simultaneous requests. An agent orchestrating several tool calls in parallel will send multiple requests to the proxy at the same time, and the proxy needs to handle them correctly without credential values leaking between concurrent operations.
Go's goroutine model made this straightforward to implement correctly. Each incoming request gets its own goroutine, credential resolution happens within that goroutine's scope, and the resolved value never touches shared state. The design that makes the zero-knowledge guarantee hold in concurrent usage is the same design that makes the code readable and the behaviour predictable.
This is one of those cases where the language's model aligned well with what the problem required. Concurrent request handling in Python with async or threading would have worked but would have required more care about shared state. In Go the right structure was also the natural structure.
What the rewrite cost
Rewriting a working codebase has a cost that is easy to underestimate until you are in it.
secretscli worked and the team used it, which meant moving to a new codebase required rebuilding that functionality in a new language while simultaneously building the new proxy architecture, which is more work than it sounds when both things are happening at the same time.
The Go learning curve was real for parts of the team. Go is a simple language but simple does not mean immediately intuitive, and the early parts of the codebase reflect that. There are places where we solved problems in ways that a more experienced Go team would not, and we have cleaned some of them up and will clean up more as the codebase matures.
The test coverage also lagged behind the implementation in the early stages, which is a pattern that tends to happen when you are moving fast on a new architecture. We have been catching up on that, and the proxy is better tested now than it was at launch, but it is still an area we are actively improving.
What it gave back
The distribution story has been the clearest return. Developers install AgentSecrets with brew install and it works, without setup instructions about Python versions, dependency conflicts, or environment issues that only reproduce on specific machines.
The binary size is also worth mentioning. Go produces larger binaries than some languages, but the AgentSecrets binary is small enough that it is not a meaningful concern. Developers download it once and forget about it.
Performance has not been a bottleneck. The proxy adds a small overhead to each API call, proxy resolution and header injection, and in practice that overhead is negligible compared to network latency. We did not optimise for performance early because it was not the constraint. If it becomes one, Go gives us the tools to address it without changing the architecture.
The SDK staying in Python
The Go CLI and proxy coexist with a Python SDK, and that split is intentional. The SDK is how developers build on AgentSecrets, and the developers building AI agents in 2026 are primarily working in Python. Asking them to switch languages to use the SDK would have been a real barrier that the binary distribution argument does not apply to.
Go and JavaScript SDKs are on the roadmap. The Python SDK came first because it reaches the developers who need it most right now, and the right time to build the others is when the Python SDK has demonstrated what the interface should look like.
Part 06 covers zero-knowledge cloud sync, how the client-side encryption works in practice, and what the server actually holds.
AgentSecrets is open source and MIT licensed. The full architecture is at agentsecrets.theseventeen.co. The repository is at github.com/The-17/agentsecrets.