🚀 HarnessRouter: community package now available

[LoudLemur]

TL;DR: HarnessRouter puts one OpenAI Responses-compatible API and a web console in front of agent command-line tools (OpenCode, Codex, Claude Code): your scripts or product send a request, HarnessRouter runs the agent, streams its progress and keeps the transcript. It is now packaged for Cloudron, with every agent session running as its own unprivileged user behind an egress firewall, and your provider keys held by HarnessRouter rather than by the agents. Built and tested on Cloudron 10; unofficial and community maintained.

Headline features

• One API for several agent tools: call OpenCode, Codex or Claude Code through the same OpenAI Responses-style endpoint, with streaming.
• A web console to run turns by hand, read transcripts, manage model connections and create API keys for your own scripts.
• Bring your own model: Anthropic, OpenAI, OpenRouter, or any OpenAI-compatible endpoint, including one you host yourself.
• Sessions resume: a later request can continue an earlier one, and each session keeps its own working directory.
• API keys for programs, so a script can drive agents without a console login.

Links

• Project homepage: https://harnessrouter.ai
• Upstream repo: https://github.com/HarnessRouter/harnessrouter
• 🧱 Cloudron package repo: https://github.com/OrcVole/harnessrouter-cloudron
• What the package does to contain agents, as measured: https://github.com/OrcVole/harnessrouter-cloudron/blob/main/docs/CONTAINMENT.md

How to install

The easiest route is the dashboard. In the App Store, click the Add custom app dropdown (top right) and choose Community app, then paste the CloudronVersions.json URL below into the box that pops up. Apps installed this way receive automatic updates.

https://ca.cloudron.io/app/io.github.orcvole.harnessrouter

Or with the CLI:

cloudron install \
  --versions-url https://raw.githubusercontent.com/OrcVole/harnessrouter-cloudron/main/CloudronVersions.json \
  --location harnessrouter.example.com

Minimums: a 4 GiB memory limit, measured against ten agent sessions running at once (about 0.2 GiB for the app plus about 0.25 GiB per active session), and the localstorage addon. The package asks for the net_admin capability, which it uses only for the agents' firewall; Cloudron grants it with the install. The first start downloads the agent tools under their own licences and takes several minutes; the console does not answer until that finishes.

First run: the console password is generated on first start. Open the app's Web Terminal, run cat /app/data/.secrets/admin-password, sign in as harnessrouter, then change the password on the Profile page. Add a model connection in the console, and create an API key there for your own scripts.

For users

Why try it: if you want to put coding agents behind your own product, or run them from scripts, HarnessRouter gives you one API and keeps the transcripts, so you do not have to wrap each tool yourself. Cloudron wins: backups of your transcripts, settings and keys, one-click updates, and agents kept apart from the rest of your server. Good fit for agent work driven by programs; probably not if you only want a chat window.

🧰 For packagers: what we learned

What helped: upstream already ships a broker mode, written for its hosted service, in which agents never hold the real provider key. The package switches it on and cannot be talked out of it.

What was tricky: containment. Each session already runs as its own user upstream; the package moves those users to a high uid range and adds an IPv4 and IPv6 owner-match firewall, so agents reach the internet, DNS, HarnessRouter's own API and nothing on Cloudron's internal network or the mail ports. The app refuses to start if the firewall cannot be installed. Agents can traverse the data directory to run their tools, so anything there with a world-read bit is readable by name: the package now makes the settings file root-only at every start, and its containment test checks every file, not a list.

Still rough: session workspaces are kept outside the backup on purpose (about 50 MB each, rebuilt from each session's checkpoint, which is backed up). Streaming through the reverse proxy was proven for framing, not yet for event-by-event timing against a slow model.

️ For the Cloudron team

Maintenance burden: upstream releases often; the package pins the agent tool versions and moves them together on each bump. Why it suits the App Store: agent infrastructure is in demand, the upstream is Apache-2.0, and it pairs with the AI apps already here. Friction worth knowing: we tried proxyAuth as an optional wall and measured that with supportsBearerAuth any request carrying an Authorization: Bearer header passes it, whatever the token, and that the addon takes the app's own /login; for an app with its own login it added nothing, so the package keeps HarnessRouter's own login.

For HarnessRouter's developers

Thank you for broker mode: it made a careful package possible. Making it the self-hosting default, and generating the first password instead of shipping one, would help every operator. Package source and pull requests welcome at https://github.com/OrcVole/harnessrouter-cloudron. Happy to co-maintain.

Unlocks

Now you can give your own scripts and products one API that runs coding agents on your own Cloudron, with transcripts kept and the agents fenced off from your server's internal network and your provider keys.

Synergies

• HarnessRouter + agentgateway: give HarnessRouter its own gateway key instead of a provider's master key, so you can limit or revoke it without touching the provider account.
• HarnessRouter + vLLM or Ollama: point a connection at a model you host yourself, through its public URL, and keep prompts on your own hardware.
• HarnessRouter + Forgejo: give agents a repository to clone, commit to and push, so their work lands in version control you own.
• HarnessRouter + Uptime Kuma: watch /login so you know when the console goes down.

Feedback, bug reports, and "works on my install" confirmations gratefully received.

[timconsidine]

I read all the words, but my brain doesn't understand the use case.
Maybe I am having a bad day.

[LoudLemur]

@timconsidine

Hey Tim, thanks for looking and commenting!

The problem. Coding agents like Claude Code, Codex and OpenCode are like very capable helpers who only work at a keyboard. You type to them in a terminal, they read files, run commands and write code. That works when you are sitting there. It doesn't work when your app or script wants to hand them a job.

What HarnessRouter does. It's a front desk for those helpers. Your program walks up to the desk and says "please do this task" through one standard API. HarnessRouter then:

• picks the helper you asked for (Codex, OpenCode or Claude Code);
• gives it a private room to work in (its own folder and its own user account);
• lets it think with whichever AI model you've connected;
• streams back what it's doing, and keeps a written record of everything it did.

Later you can come back and say "carry on from where you left off", and it picks up the same job.

Why that's useful. You can build things on top of agents without wiring each tool up yourself:

• a support tool that drafts replies;
• a script that reviews code every night;
• a feature in your own product that "does the task for the user".

One API covers every helper, and you can swap helpers or models without rewriting your code.

What the Cloudron package adds. These helpers can run commands, so you don't want them poking around your server. Our package keeps them fenced in:

• One room each. Every job runs as its own user and can't see the others.
• No keys in hand. The helpers never hold your real AI provider key. HarnessRouter holds it and passes requests along for them.
• Fenced off from your server. A firewall stops them reaching your other apps, your internal network or email. They can still reach the internet, which they need for models and code repositories.
• Cloudron housekeeping. You get backups, one-click updates and a generated password.

In one line: HarnessRouter turns "an AI agent in a terminal" into "an AI agent service your programs can call", and the Cloudron package makes running it on your own server reasonably safe.

[robi]

@timconsidine Mercury is in retrograde, has some effects during Halloween.

It's basically a Trae for many other Trae's and Hermes and OpenCode, etc...

Manage many, vs one at a time.

[timconsidine]

Mercury is in retrograde, has some effects during Halloween.

Thank you, I knew something was off

I love all of this stuff, but almost always trip up over a deployment issue : giving the tool stuff to work on / with.

I'm very reluctant to run AI tools on my primary device (Mac laptop) apart from Opencode and TRAE, both of which I endeavour to watch like a hawk (but probably fail on occasions). I never give Ai tools access to primary email, just work off secondary accounts which get fed with email from primary.
Edging towards moving dev projects off laptop and then using opencode-web. But not making much progress.
Theoretically every project needs its own silo / environment, but can't get my head around structuring and managing that.

Still playing with firing up on-demand environments (like fly.io sprites and machines) but also slow progress.

[robi]

@timconsidine Yep, remember to zoom out when you get stuck.

Fly.io is awesome and a great use case for a harness like this.

Don't mind all the fear porn out there, it's deliberate narrative and they don't share any logs or proof.

[robi]

Not sure this needs a separate app, but is VERY useful in any agent/harness
https://github.com/goodnight000/api-anything

[timconsidine]

@robi fascinating ... but I think I need a brain upgrade (trying to recover from changing traditional colour terms to being expressed in oklch for Tailwind 4).

[LoudLemur]

@timconsidine said:

I'm very reluctant to run AI tools on my primary device

From our experience, that is a wise choice. AI has repeatedly "found itself" operating outside of its designated areas, i.e. in No Go zones. It is able to provide a plausible excuse when it is spotted. Also, "mistakes were made", like deletion of half an archive.

The difficult thing is that once you start using AI, it becomes so helpful that the same machine becomes your main machine.