Build a SaaS on the harness
A worked design for a multi-tenant app on @venom/harness, using a collections back office as the example: tenancy, tools, human approvals, audit, cost caps and deployment.
This page puts the other harness pages together into one design. The example is a collections back office: collectors work a queue of overdue accounts, and an agent reads each account, proposes the next action (a reminder, a payment plan, an escalation) and drafts the message. Nothing reaches a debtor until a collector approves it. Replace the domain words with yours; the structure carries over to support desks, claims processing or internal tooling.
Architecture
browser ── Next.js app (auth, queue UI, approval inbox)
│ HTTP
▼
agent worker (Node, long-lived)
├─ createHarnessServer or createHarness per job
├─ your tools ── your database, mailer, payment provider
└─ provider ── venom orchestrator / Venom Cloud / your own vLLMRun sessions in a long-lived worker, not in serverless functions: a run takes minutes and an approval can wait on a person. The web app talks to the worker over HTTP (embed createHarnessServer from @venom/harness-server, which gives you sessions, events over Server-Sent Events and remote approvals) or through a job queue (embedding).
Tenancy
A harness has no global state, so one per tenant (or per job) isolates them inside one process:
| Concern | Per tenant |
|---|---|
| State | venomHome: /var/lib/app/venom/<tenant>, agentDir: …/<tenant>/agent |
| Workspace | cwd: a directory holding only that tenant's working files (exports, drafts), never a shared one |
| Policy | rules and mode built from the tenant's plan and settings |
| Audit | an AuditSink that writes rows tagged with the tenant id |
| Model access | provider.apiKey: a key per tenant (for example a Venom Cloud key whose budget is that tenant's) |
| Cost | guards.maxCost per run, runtime.quotas.maxCost per session, or a Venom Cloud gear budget |
Pass compat: false and policy explicitly: the agent should not pick up CLAUDE.md files or a machine-wide policy by accident. Set plugins: false unless you ship plugins on purpose.
Tools, not prompts
Give the agent your data through tools rather than pasting it into prompts. Tool output is treated as untrusted content (spotlighted and scanned for injected instructions), which matters when account notes contain text debtors wrote.
const tools: InlineExtension = {
name: "collections",
factory: (pi) => {
pi.registerTool(defineTool({
name: "lookup_account", label: "Lookup account", promptSnippet: "lookup_account: read an account",
description: "Read one account of the current tenant: balance, due dates, contact preferences, notes.",
parameters: Type.Object({ id: Type.String() }),
annotations: { readOnlyHint: true },
execute: async (_id, { id }) => text(await db.accounts.get(tenant, id)),
}));
pi.registerTool(defineTool({
name: "propose_action", label: "Propose action", promptSnippet: "propose_action: queue a reminder, plan or escalation for approval",
description: "Queue an action for a collector to approve. Nothing is sent until approved.",
parameters: Type.Object({ id: Type.String(), kind: Type.Union([Type.Literal("reminder"), Type.Literal("plan"), Type.Literal("escalate")]), body: Type.String() }),
execute: async (_id, a) => text(await db.proposals.insert(tenant, a)),
}));
},
};
const text = (v: unknown) => ({ content: [{ type: "text" as const, text: JSON.stringify(v) }], details: undefined });Scope every query by the tenant inside the tool; never let the model pass a tenant id. Tools that send, charge or delete belong behind an approval or out of the agent's reach entirely: here the agent can only propose, and your own code sends after a collector approves.
Human approvals
Two patterns, which combine:
- Propose, then act outside the agent (above): the agent's tool only writes a proposal; your UI shows it; your code acts on approval. The agent never holds the power to contact anyone.
- Gate the call: a tool without
readOnlyHintasks indefaultmode, and yourapprovecallback decides. Over HTTP the approval is an event your UI answers; it is denied if nobody answers within the server'sapprovalTimeoutMs(60 s by default), so use pattern 1 for decisions that can wait hours.
Return feedback on a denial so the model knows what to do instead.
Lock the policy down
createHarness({
cwd, mode: "default", compat: false, plugins: false, approve,
rules: { deny: ["bash", "web_fetch", "web_search", "write", "edit"] }, // this agent only reads and proposes
network: "offline", // no web tools, no remote MCP servers
sandboxNetwork: false,
subagents: false,
audit: tenantAuditSink,
guards: { maxToolCalls: 60, maxSeconds: 600, maxCost: 0.5 },
});Denying built-in tools you do not need is the strongest control you have: the model cannot misuse a tool it cannot call. Every decision still lands in your audit sink, including denials.
Data handling
- Prompts and tool results go to the model server you configure and nowhere else; the harness makes no other network calls on its own. With a self-hosted model behind the venom orchestrator, account data never leaves your infrastructure.
- Secret redaction is on in every session: known key shapes (provider keys, JWTs, private keys, passwords in URLs) and the values of credential-named environment variables are replaced with
[redacted:<kind>]in tool output before the model sees it.SecretRedactorandsessionRedactor(root entry) expose it for your own text. Customer personal data is not a secret shape: decide in your tools which fields the model needs. - Saved transcripts exist only with
persist: true, under the tenant'sagentDir. Leave it off unless you need replay or resume, and apply your retention policy to that directory if you turn it on.
Scheduled work
Nightly triage of new overdue accounts is a cron job: either your own scheduler calling the worker, or schedules: in venom.yaml under venom serve with a per-run budget (default $1, 120 minutes). Unattended goals pass a goal gate (goalgate.checkGoal) so a vague goal does not spend money. User guide: automation section.
Checklist
- One harness per tenant or job, with its own
venomHomeandcwd -
compat: false,plugins: false, explicitpolicy - Unused built-in tools denied;
network: "offline"if the agent needs no web - Tools scope by tenant internally; side effects go through proposals or approvals
- An
AuditSinkwriting to your database -
guardsand a per-tenant key or budget capping spend - Sessions run in a long-lived worker, not an edge or short serverless function
Related
- Your own tools and approvals
- The permission engine
- Server API section
- Venom Cloud section, for keys and budgets per key group