How to Open-Source Your Agent Harness

Most guides to open-sourcing a project are wrong for this specific case, because an agent harness isn't an ordinary library — it's security-sensitive infrastructure that probably grew up tangled with your internal prompts, credentials, and private assumptions. Releasing an open source agent harness the way you'd release a utility library is how teams accidentally publish an API key in their git history or ship code that only runs against infrastructure nobody else has. This guide walks through doing it properly: what to scrub, how to make it usable by strangers, and the security posture a harness specifically needs.

The payoff is real — a well-released harness attracts contributors, builds your team's reputation, and often comes back better than it left. But the preparation matters more here than for almost any other kind of project, because the failure modes are worse than an embarrassing bug: a leaked production credential or a released sandbox with a hole in it is the kind of mistake that follows a team around, and both are entirely preventable with the steps below.

Quick-Start (Copy This Right Now)

Before anything else, audit your entire git history — not just the current files — for secrets. Secrets deleted in a later commit still live in history forever.

[object Object],
pip install detect-secrets
detect-secrets scan --all-files > .secrets.baseline
git ,[object Object], -p | grep -iE ,[object Object],

What this does: Scans every file and greps the entire commit history for the shapes of committed credentials. A key you added in commit 40 and removed in commit 55 is still exposed to anyone who clones the repo and reads the log — so you must find these before you make the repo public, not after. If you find any, you rewrite history or start a fresh repo; you never just delete-and-publish.

⚠️ Common mistake: Auditing only the current working tree and assuming a deleted secret is gone. Git never forgets. A secret ever committed is public the instant the repo is, no matter how many commits later you removed it. Treat any historically-committed credential as compromised, rotate it, and clean history before release — deletion in HEAD is not removal.

What an Open Source Agent Harness Needs

Three things determine whether your open source agent harness is actually usable by someone who isn't you, and none of them is the code quality you're probably focused on.

Coupling to your infrastructure. Your harness probably assumes your database, your secret store, your internal services. A stranger has none of those. The more your core logic is tangled with your specific infrastructure, the less anyone else can run it. Releasability is largely a measure of how cleanly the harness separates its logic from your environment.

Embedded internal knowledge. Prompts, tool definitions, and configs often encode things about your business you didn't mean to publish — internal endpoint names, product assumptions, sometimes prompt engineering you consider proprietary. Decide deliberately what's shared and what stays private.

Security expectations. A harness that runs untrusted code and takes actions is a project where security bugs matter enormously. Releasing it means inviting scrutiny, which is good, but also means you need a way for people to report vulnerabilities responsibly rather than posting them publicly.

Step-by-Step: Making It Usable by Strangers

Step one: Replace your infrastructure with pluggable interfaces so someone can run the harness against their backends, or a local default.

[object Object], ,[object Object],(,[object Object],):
    ,[object Object], ,[object Object],(,[object Object],) -> ,[object Object],: ...
    ,[object Object], ,[object Object],(,[object Object],) -> ,[object Object],: ...

,[object Object], ,[object Object],:          ,[object Object],
    ,[object Object], ,[object Object],(,[object Object],): ,[object Object],._d = {}
    ,[object Object], ,[object Object],(,[object Object],): ,[object Object], ,[object Object],._d.get(run_id, {})
    ,[object Object], ,[object Object],(,[object Object],): ,[object Object],._d[run_id] = state

What this does: Defines the state store as an interface and ships a simple in-memory implementation as the default, so the harness runs out of the box with zero setup while letting users plug in their own database. Your internal Postgres-backed store stays private; the released harness works for anyone the moment they clone it. Pluggable backends are what turn "runs against our infra" into "runs anywhere."

Step two: Provide a genuinely runnable example — one command, no private dependencies, that demonstrates the harness end to end.

[object Object],
harness = Harness(store=InMemoryStore(), tools=[calculator, web_search])
,[object Object],(harness.run(,[object Object],))

What this does: Shows a complete working agent using only the in-memory store and a couple of safe example tools, runnable with nothing but a model API key. This is the first thing a potential user tries, and if it works in one command, they keep going; if it needs your private database, they leave. The quickstart is your adoption funnel.

⚡ Pro tip: Test your quickstart on a truly clean machine — a fresh container with nothing installed and no access to your systems. It's astonishing how much "obvious" setup is actually your laptop's accumulated state, and the only way to catch those hidden dependencies is to run the example somewhere that has none of them. If it works in a bare container, it works for strangers.

Pro-Level Variations

Write a real README that leads with what the harness does and a copy-paste quickstart, not with architecture. People decide whether to try your project in the first thirty seconds, and a wall of design docs loses them before the part that would have hooked them.

Add a

SECURITY.md

Pick a license deliberately. Permissive licenses (MIT, Apache 2.0) maximize adoption; Apache 2.0 additionally includes an explicit patent grant, which some corporate users specifically require before they'll touch a dependency.

Troubleshooting Common Issues

Nobody can get it running. Your quickstart has a hidden dependency on your environment. Re-test in a clean container and remove every assumption that isn't the model API key.

You published a secret anyway. Rotate it immediately — assume it's compromised the moment it was public — then clean history. Rotation first, because cleaning history doesn't un-expose what was already cloned.

Contributors can't understand the architecture. Add a short

ARCHITECTURE.md

⚠️ Common mistake: Open-sourcing the harness but keeping the security-critical parts — the sandboxing, the permission checks — in a private layer you didn't release, so the public version is subtly unsafe to actually use. If you release a harness that runs untrusted code, release the isolation with it or clearly document that users must add their own. A harness that looks complete but omits its safety boundaries is worse than no release, because people will trust it.

Preparing for Life After the Release

The mistake that catches enthusiastic teams is treating the release as the finish line. Publishing an open source agent harness is the start of a commitment, and going in without a plan for what comes next is how promising projects strand their early users and quietly die.

The first thing that arrives is issues — bug reports, questions, feature requests — and a project that takes weeks to respond to its first few issues teaches people it's abandoned. You don't need to fix everything, but a quick acknowledgment sets the tone. Decide before launch who watches the repo and how fast you aim to at least respond.

The second is the security report, which for a harness is a matter of when, not if. Someone will find a way past your sandbox or a new injection vector, and how you handle that first disclosure defines your project's reputation. Have the private channel ready, know who triages it, and plan to credit the reporter — responsible disclosure handled well turns a scary moment into trust.

The third is contribution friction. If building and testing the harness locally takes an afternoon of undocumented setup, drive-by contributors won't bother, and you'll get no help maintaining it. A one-command test setup and a short contributor guide are what convert interested strangers into people who actually send fixes.

⚡ Pro tip: Run your own quickstart and test suite in CI on every commit, in a clean environment, from day one. It's the only reliable guard against the classic open-source failure where the project slowly stops working for anyone but the maintainer whose machine has all the hidden dependencies. If CI builds from clean and passes, you know a stranger can build it too — and that's the difference between a living project and an archived one.

Your Turn

Before you flip the repo to public, do the one non-negotiable step: audit your full git history for secrets. Then make the quickstart run in a clean container, add

SECURITY.md

Keep the released prompts, example tools, and configs versioned alongside your private ones in a library like PromptABCD, with a clear line between what's public and what's internal, so the boundary you drew deliberately at release time stays drawn — and an internal-only prompt never wanders into the public repo by accident.