KHTDR – agents

agents: how it compares

mazzarelli@gmail.com (Joey Mazzarelli) — Wed, 16 Sep 2026 00:00:00 -0600

Two projects may come up when you are looking for similar solutions. Flue, an open TypeScript framework from the Astro team. Sapiom, a hosted platform. They are different enough from each other that the comparisons barely overlap. Both were checked in September 2026, and both move fast, so treat the specifics as a snapshot.

The short version

	This	Flue	Sapiom
What an agent is	A row in a database	A TypeScript function	TypeScript step code
Changing a prompt	Save it	Commit, build, deploy	Commit, build, deploy
Where it runs	Your laptop, your host, or inside your app	Your host or Cloudflare	Their cloud only
Model keys	Yours, via OpenRouter	Yours, per provider	Theirs, five models
Per-run cost	None	None	$0.50 to $1
Version history and replay	Yes	Git, and no replay	No
Survives a redeploy mid-run	Partly	Yes, by design	Yes
Sandbox	Capped subprocess	Managed cloud boxes	Managed cloud boxes
Slack, GitHub, Stripe ingress	Write it yourself	17 verified channels	Webhook triggers
Auth and tenancy	None	None	Yes, with SSO

Against Flue

Flue is Apache-2.0, self-hosted, bring your own model key, no account, no per-run fee. Everything I would normally compare is a tie. What is left is a disagreement about what an agent is.

The disagreement

In Flue an agent is a function with a React-style hooks API:

'use agent';
export function Triage() {
 useModel('anthropic/claude-sonnet-4-6');
 useSandbox(local());
 useTool(searchIssues);
 useSkill(reviewChecklist);
 return 'Investigate the reported issue and recommend the next action.';
}

The function re-renders before every model call. Hooks get re-evaluated each turn, so capabilities appear and disappear mid-conversation. You build it with Vite and deploy to Node or Cloudflare, where each conversation becomes a Durable Object.

The unit of work is different. Flue’s unit is a conversation. It is a stateful, addressable, long-lived service at a URL, with durable history and a contract that survives crashes and redeploys. This project’s unit is a run. It has an input, an output, a cost, and a tree of children. Flue asks what an agent knows and can reach right now. This asks what happened on that run, and whether you can do it again differently.

Data versus code. Here an agent is a row. It gets versioned on every save, replayed against an older version, and edited by someone who does not write TypeScript. In Flue an agent is source in a repo. Changing a prompt is a commit, a build, and a deploy, and there is no dashboard, no version history, and no replay. That is not an oversight. It is the same call Astro makes about pages. It does mean the whole A/B-and-replay half of this project has no counterpart there.

Side by side

Area	This project	Flue
License and backing	Private repo, one author, npm `@upship/agents`	Apache-2.0, Astro team, ~8.3k stars, 1.0 beta
Defining an agent	A JSON row: prompt, tier, tools, optional graph config	A TypeScript function with `use*` hooks
Who writes it	A person in the UI, an interview, or a coding agent from the generated brief	You, in an editor
Changing a prompt	Save, new version snapshot	Edit source, commit, build, deploy
Versioning and replay	Every save snapshots. Replay any run against another version or swapped tools	None. Git is the history
Unit of work	A run, with a status, a cost, and a child tree	A conversation at a URL, with an append-only stream
Execution modes	Freeform loop, DAG with conditions and merges, plan-then-execute, debate, reflection, quality gate, peer messaging	One model-driven turn loop. Branching is conditional hooks. Delegation is a `task` tool
Orchestration authored as	Config fields	Control flow you write
Sub-agents	An agent is a tool. Child runs roll up cost. Peers can message each other	`useSubagent()`, fresh context, isolated from the parent, depth capped at 4
Durability	Graph nodes park and resume by token, and a run answered but not yet restarted is picked up at boot. Freeform runs wait in-process and die with it	The headline feature. Leases, heartbeats, startup reconciliation, classified recovery, durable tools with checkpoints
Storage	Four drivers behind one port, with a conformance suite	Adapters for SQLite, Postgres, libSQL, MySQL, MongoDB, Redis. Free on Cloudflare
Sandboxing	Capped subprocess. No filesystem namespace. Reports what it could not enforce	Virtual, local, or remote providers: E2B, Daytona, Modal, Vercel, Cloudflare
Tools	~22 first-party plus MCP. Definitions are rows you can A/B and bind config to	`defineTool()` with Valibot, composed per render, conditionally visible
Skills	None	First-class, using the open agentskills.io format, progressively disclosed
Human in the loop	Parking tools, a derived answer form, a pending inbox in UI and CLI	Nothing named. A person sends the next message. No inbox
Models	OpenRouter, one key. Tiers mapped as data, repointable without a rebuild	`useModel()` per agent, keys per provider, automatic compaction
Triggers	None. Cron the CLI	No scheduler, but documented patterns per target
Inbound integrations	None	17 verified channels: Slack, Discord, GitHub, Linear, Stripe, Twilio and more
Frontend	Its own admin UI	`@flue/react` for your product’s chat UI, plus streaming data parts
Client SDK	None yet	Small, typed, one dependency
Observability	Run tree, live node events, cost columns, side-by-side comparison, in a UI	An event stream you ship to Sentry, Braintrust, or OpenTelemetry. No dashboard, by choice
Evals	None. Replay is the nearest thing	Vitest suites, judges, CI reporting
Auth	None. Binds to localhost for that reason	None built in, but you own the route map

What Flue does better

Durability. This is the gap that matters most. Every admitted submission reaches exactly one outcome, enforced by attempts, leases, startup reconciliation, and a classifier that tells a partial stream from an unresolved tool batch from a context overflow. Here, a freeform run waits in-process and dies with it. The heartbeat notices a dead run. It does not recover one. There is one recovery path and it is narrow: a paused run that got its answer but never got restarted is picked back up on the next boot, so a deploy cannot strand a run that had nothing left to wait for. A run that was mid-step when the process died is still closed out as an error.
Sandbox isolation from a provider. Managed Linux per conversation, with a real filesystem boundary and a package manager. run_script here covers computation and says plainly what it could not take away. It will not hand a coding agent a disposable box.
Channels. Verified webhook ingress from 17 providers, with signature checking, replay windows, and idempotency keys. Getting a GitHub issue into an agent here is a service you write.
Skills. A portable format for packaged expertise, disclosed progressively so an agent can carry dozens cheaply. No equivalent here.
Conversational agents. Long-lived services at a URL, joined by many people over days. Runs here are jobs.
A frontend story and a client SDK.
Evals, compaction, and OpenTelemetry.
A team, a license, and a community.

What this project does better

Agents as data. Version history, a UI, replay against an older version, side-by-side comparison. The whole precondition for A/B work.
Tool definitions as data. Many definitions over one implementation, each with its own wording, config, and secrets. Both projects have a defineTool() now. The unit is still different: theirs binds a schema once, mine is a row you can point at two accounts.
Declarative multi-step orchestration. Conditional edges, fan-in merges, gates with retry, plan-then-execute with human review, debate, reflection. In Flue each of those is control flow you hand-write.
Peer messaging between concurrent nodes, with deadlock detection. Flue’s delegation is strictly hierarchical and siblings never talk.
Human gates with an inbox. Flue makes asking natural and gives you nothing for finding what is waiting.
Durable memory with compare-and-set.
Model tiers as data. Repoint reasoning without a rebuild, and old runs keep the id they resolved to.
Cost you can look at. Microdollar columns, tool costs folded in, rollups across the tree. Flue emits numbers and hands them to someone else’s dashboard.
Authoring without the repo. An interview, a generated brief, a skill your coding agent can use.
No build step. agent serve and you have an API, a UI, and SQLite. Flue needs Vite, a config, a plugin ordering rule, and hand-maintained Durable Object migrations on Cloudflare.
An encrypted secret store instead of env vars, so a key rotates without a redeploy.
An outbound HTTP tool with an address policy.

Pick Flue if

The work must not be lost. A redeploy mid-task is routine and a dropped job is an incident.
The agent runs code against a real boundary. You want a disposable Linux box with a package manager, not a capped subprocess.
Users talk to it, in Slack or GitHub or a chat UI in your product.
You are a TypeScript team shipping a product, and you want agents in the repo and reviewed in pull requests.
You are already on Cloudflare. Durable Objects solve the one-owner problem that Node leaves to you.
You want an OSS project with a future behind it.

Pick this if

The agents should be editable by a person in a UI, versioned, replayed, and compared, by someone who is not going to open a repo.
The orchestration patterns matter. Debate, reflection, gates, fan-in merges, conditional routing. A config field here, a week of control flow there.
You want to A/B the wording.
The work is job-shaped, not conversation-shaped. Pipelines, batch classification, a nightly report. Run history is the product.
You want it running in one command, with no build and no deploy story.
You want to repoint models, rotate credentials, or rewire a graph without a redeploy.
You want to own and vendor the runtime.

Bottom line

Flue is built to keep work running. This is built to let you change the work and see what changed.

Someone picks Flue because their agent has to survive a redeploy while a customer is talking to it. Someone picks this because they want to change a prompt, re-run yesterday’s job against both versions, and see which one cost less.

Against Sapiom

Sapiom is venture-funded and hosted. Around $50M raised, Accel-led. It has three pieces:

Router. An OpenAI-compatible endpoint that picks a model per request from a small curated list and meters every call.
Runtime. A managed engine that runs your agent in their cloud as a typed step graph with durable pauses, retries, schedules, and per-attempt traces.
Capabilities. A catalog of paid services an agent calls through one pre-authenticated client. Web search, scraping, browser sessions, sandboxes, Postgres provisioning, image and video generation, file storage, email lookup, domain registration. No vendor accounts.

That third piece is the business. The pitch is that agents buy their own tools and every API call is a payment. Sapiom is a procurement layer with a runtime around it. This project is a runtime whose only payments layer is your OpenRouter bill.

Side by side

Area	This project	Sapiom
Where it runs	Your machine, any host, or inside your own app as a library	Their cloud only. Local runs stub every capability
Defining an agent	A JSON row, editable in the UI, versioned on every save	TypeScript in a repo they provision, with compile-checked step transitions
Who writes it	A person in the UI, an interview, or a coding agent	A desktop studio, or their MCP server inside your coding agent
Execution modes	Freeform loop, DAG with conditions and merges, plan, debate, reflection, gates, peer messaging	One step graph. Branching and escalation are hand-written
Model access	Any OpenRouter model, your key, tiers as data	Five curated models, their key, latency lanes
Tools	~22 first-party, plus yours, plus MCP. You bring the credentials	A capability catalog. No credentials to bring, and no way to add your own
Sandbox	Capped subprocess, no filesystem namespace	Managed cloud environments and a hosted coding agent, metered per call
Durable pause	Graph nodes park and resume by token, and an answered run that never restarted is picked up at boot	Signals with correlation ids and deadlines
Retries	Gates with retry, plan re-planning. No automatic per-step retry	Three attempts per step by default, plus an explicit retry directive
Scheduling	None. Cron the CLI	Cron, events, and webhook triggers
Memory	Durable memory with compare-and-set	Not a named feature. Use file storage or a provisioned database
Cost	Your OpenRouter usage, and nothing else	$0.50 to $1 per run on top of usage, plus per-call capability rates
Auth and tenancy	None at all	Accounts, orgs, per-agent spend rules, SSO, audit trail
Compliance	Whatever your host gives you	SOC 2, SLAs, telemetry export
Lock-in	Low. Agents are JSON, and the runtime vendors into your tree	High. Step code imports their package and capabilities are their client
Local dev	The real thing runs locally. Same database, same tools, real calls	Real step code, stubbed capabilities. Production behavior first happens in their cloud

What Sapiom does better

Someone else holds every credential and every invoice. A Sapiom agent can spin up a browser, register a domain, provision a Postgres, and generate a video with nobody creating an account anywhere. Here each of those is a key you go get. That gap got smaller when the fetch tool landed, since an HTTP API with a key is now a tool definition rather than a module. The signups and the invoices are untouched, and they were always the point.
Cloud sandboxes and a hosted coding agent. Managed compute with a real filesystem boundary and a package manager.
Schedules and webhook triggers. Here you wire cron to the CLI yourself.
Auth, tenants, policies, spend caps. None of that exists here. This platform has no notion of a caller anywhere.
Compile-time graph checking. Undeclared transitions are type errors. The equivalent here is schema validation at save time, which is good but runtime-typed.
Model routing by task shape. Here a tier is a fixed pointer you set.
Support, SLAs, SOC 2. You pay for someone to be on the hook.

What this project does better

It runs anywhere. One process, SQLite, no account. Sapiom cannot run your agent outside their cloud, and even local authoring needs a sign-in.
Agents as data. Version history, a UI, replay. Their agents are TypeScript, so changing a prompt is a deploy.
Higher-level orchestration built in. Debate, reflection, plan review, merge strategies, conditional edges, gates. You hand-write all of that as steps there.
A freeform loop as a first-class mode. Their unit is a deterministic step.
Bring your own model provider. Any OpenRouter model, any price, your key.
Bring your own tools, at no disadvantage. A file in ./tools gets the same treatment a built-in gets. Sapiom has no user-defined capability mechanism at all. Anything outside the catalog is a fetch buried in step code.
Peer messaging between concurrent nodes.
Durable memory with compare-and-set.
Tool definitions as data.
No per-run fee, and this is the big practical one. A run on a cheap model here costs about five cents. A heavy day of $10 in model calls is roughly 200 runs, which on Sapiom is $100 to $200 in run fees before any usage or capability rates. Ten to twenty times the cost is not a rounding error.
Full local fidelity. Your test run is the production run.
Source you can read, vendor, or depend on outright.

Pick Sapiom if

You do not want to collect API keys. Search, a headless browser, a scratch database, image generation, email lookup. That is five signups and five invoices on your own host, and one bill on theirs. This is the whole pitch and it is real.
You need a sandbox strong enough to be somebody else’s problem.
You need schedules and inbound webhooks without building them.
You are a team, not a person. Spend limits, an audit trail, SSO, someone to call.
You want compliance paper.
You prefer typed code over JSON config, with transitions checked by a compiler and agents reviewed in pull requests.

Pick this if

It is a personal or small-scale tool. No per-run fee, no account, no vendor.
The agents need to be editable in a UI, versioned, replayed, and compared.
The orchestration patterns matter.
You want to own the runtime. Read it, vendor it, patch it, run it on a Raspberry Pi, or compile it into your own app.
You already have tools or MCP servers and want them treated as first-class.
You want any model, including ones Sapiom does not route to.
You do not want your agent logic and all of its data flowing through someone else’s cloud.

Bottom line

They overlap on the runtime. Durable pause and resume, step graphs, shared state, traces, secrets, cost tracking. This project is ahead on orchestration patterns and on agents-as-data. Sapiom is ahead on everything around the runtime: hosting, scheduling, auth, tenancy, compliance, and a catalog of prepaid services.

What Sapiom sells is not having to hold the key. Someone picks Sapiom because they want to not operate anything and not sign up for anything. Someone picks this because they want to own it and run it cheaply.

What I would have to build to close the gaps

No hosting or billing in this list, because that is not a thing I am going to compete on.

Freeform durability. The biggest one and the hardest. A graph parks durably and a freeform run does not, because the freeform loop’s state lives inside the AI SDK’s multi-step generation. Closing it means owning the turn loop. Large, and arguably a rewrite of the runner.
Nested parking. Sub-agent nodes, reflection producers, debate producers, and peer waves cannot park today. Medium-large, and it unblocks the rest.
Recovery, not just reaping. Attempts, leases, and a classified resume, so a dead run continues instead of being closed out. Medium. The easy piece is done: a run that was answered and never restarted gets picked up. What is left is the hard half, continuing a run that died in the middle of a step.
Durable tools. A checkpoint so a tool that provisions something resumes mid-way. Small-medium on top of parking.
A stronger sandbox. A filesystem namespace, seccomp, a cgroup, installable packages. On reflection this is better bought than built, as an adapter for E2B or Daytona. Medium-large, and no longer blocking ordinary compute.
Channels. Verified webhook ingress with signature checking and idempotency, then a route that starts a run. The first provider is most of the work.
Schedules. A cron table plus a route that starts a run from a POST.
Skills. The agentskills.io format is open and already has adopters. Progressive disclosure is a catalog line plus a read tool. Cheap, and it interoperates.
A thin client SDK. Small. The CLI already has every call.
Context compaction. Nothing here manages a growing conversation.
OpenTelemetry export. The run tree is good, but a team with a tracing backend wants spans.
Evals. Replay and comparison are halfway there.
Auth and tenants. A bearer token is small. A real caller identity on every aggregate is medium-large, and every query grows a filter.

]]>

agents: CLI, API, embedding

mazzarelli@gmail.com (Joey Mazzarelli) — Tue, 15 Sep 2026 00:00:00 -0600

The web UI is a client, not the product. Everything it does is an HTTP call, the CLI makes the same calls, and the engine underneath both is a library you can import. Pick whichever one fits what you are doing.

The CLI

It streams output, takes piped input and file attachments, and prompts you right there when a run stops to ask something.

agent researcher "what changed in HTTP/3 this year"
echo "summarize this" | agent summarizer -f notes.md

agent new # build an agent by answering questions
agent skill install # teach Claude Code to write agents here
agent brief # what this install can do, as one document
agent tools # every tool an agent can use, and where each came from

agent pending is the inbox of everything waiting on a person:

agent pending
# Waiting (1)
#
# support-router aa3793db · 19h
# ⏸ Which environments should this go to?

The HTTP API

It is the same API the UI uses. About forty routes covering agents, runs, tools, secrets, memory, models, files, and the brief. Anything you can click, you can script.

curl -X POST localhost:2137/api/agents/researcher/run \
 -H 'content-type: application/json' \
 -d '{"input": "what changed in HTTP/3 this year"}'

curl localhost:2137/api/brief # what this install can author
curl localhost:2137/api/runs/pending # every run waiting on a person
curl -X POST localhost:2137/api/runs/$ID/pending/$TOKEN \
 -d '{"response": {"answer": ["staging"]}}' # and answering one

There is no authentication on it. That is why it binds to 127.0.0.1 by default. See operating it before you expose it.

Embedding it in your own app

The runtime that agent serve wraps is also a library. Your code calls runAgent as a function, the runs land in a database you choose, and there is no HTTP in between. Your app keeps its own login and its own users. The agents become a feature of it.

From your project’s directory, copy the runtime in and install it:

agent bundle # writes lib/agents
npm install ./lib/agents ai zod

Then a script like this runs an agent and reads the result back:

import { createRuntime, createAgent, runAgent, getStore, toolRegistry } from "@upship/agent-core";
import { tool } from "ai";
import { z } from "zod";

toolRegistry.register("clock", "Report the current time. Use it when asked what time it is.", () =>
 tool({ description: "The current time as ISO 8601.", parameters: z.object({}), execute: async () => ({ now: new Date().toISOString() }) }),
);

const rt = await createRuntime({ timers: false });
const agent =
 (await getStore().getAgent("timekeeper")) ??
 (await createAgent({ name: "timekeeper", description: "Tells the time", systemPrompt: "Answer using the clock tool.", tools: ["clock"] }));
const run = await runAgent(agent, "What time is it?", rt.ctx, rt.models);
const row = await getStore().getRun(run.runId);
console.log(row?.status, row?.output);
await rt.stop();

Set OPENROUTER_API_KEY and STORE_DRIVER=sqlite, then run it with node example.ts on Node 24 or later.

createRuntime does what the server does at startup. It opens the store, sets up tools and models, and starts the cleanup timers. A script that runs once turns the timers off. A server that stays up leaves them on and calls rt.stop() on shutdown.

Every feature works the same way here. Graphs, gates, memory, secrets and cost tracking all live in the runtime, not in the server. The one part that does not come along is the web UI, which is a static page over the HTTP API. Read runs out of the store and show them your own way.

To upgrade, run agent bundle again after updating the CLI. The Embedding page in the web UI walks through this example a line at a time and says what each one commits you to.

]]>

agents: features

mazzarelli@gmail.com (Joey Mazzarelli) — Tue, 15 Sep 2026 00:00:00 -0600

Authoring and versioning

Feature	What it does	Why you want it
Agents as rows	Name, prompt, tier, tools, and an optional pipeline. Edit from the browser, the CLI, or the API	Change a prompt or add a step without a deploy
Built-in authoring	`agent new` interviews you and drafts an agent. Or install a skill so your coding agent can	Go from install to a working agent without writing JSON
Versions and replay	Every save keeps a version. Any run can be replayed against another version or different tools	A/B test a prompt or a tool description on the same input
Swap models globally	Agents ask for `fast`, `default`, or `reasoning`. You decide what those point at	Move every agent to a new or cheaper model in one place
Cost tracking	Tokens and tool spend down to the microdollar, added up across the whole run	See what a pipeline cost, not just the first call

Pipelines

Feature	What it does	Why you want it
Agents as tools	An agent can list other agents alongside its tools	Build pipelines out of agents you already have
Pipelines (DAG)	Ordered steps, explicit connections, parallel branches, merges	Fixed sequences are cheaper and faster, and a failure points at one step
Visual composer	Drag to connect, click to edit, validation as you type	Build and fix a pipeline without hand-editing config
Conditional routing	A connection can carry a condition on the previous step’s output	One classifier, four handlers, only one branch runs
Merges	Join branches by concatenating, listing, summarizing, or picking the best	Fan out to several agents and get one answer back
Gates	A step that checks the work and either passes it on or sends it back	Retry the step that produced bad output, with the complaint attached
Checked at save time	Loops, missing steps, and conditions that do not parse are rejected on save	The pipeline fails in the editor, not three steps into a run

Getting a better answer

Feature	What it does	Why you want it
Reflection loops	Draft, critique, revise, until a critic signs off	Quality passes that do not need you in the loop
Quality gate	A critic reviews the finished output and flags the run if it is not good	Catch bad answers without anything silently rewriting them
Debate and consensus	Run it N times or ask a panel, then pick by vote, weight, or judge	Better answers on questions where one sample is a coin flip
Plan then execute	The model writes the pipeline before anything runs, and you can approve it first	Review the plan while it is still free to change
Guaranteed JSON	Put a schema on an agent and its output is validated against it	Route on a field, or hand the value to the next step as data

People in the loop

Feature	What it does	Why you want it
Human in the loop	A step can stop and ask a person, with typed options	Approvals and sign-offs inside an otherwise automatic run
Multi-turn interviews	A conversation where each question depends on the last answer	Gather requirements from a person mid-run
Durable pauses	A paused run keeps its place with no process waiting on it, and picks itself back up if the server restarts while the answer is coming in	A webhook, a build, or a person can answer hours later, and a deploy in the middle of it does not lose the run
A pending inbox	One list of every run waiting on somebody, in the UI and the CLI	Nothing sits parked because you forgot about it

State and memory

Feature	What it does	Why you want it
Shared scratchpad	Steps read and write a shared key/value store for the run	Parallel branches contribute to one result without threading it through every step
Long-term memory	Namespaced values that outlive the run, safe when two runs race	Jobs that pick up where the last run stopped
Agents that talk	Agents running in parallel can message each other	Negotiation and critique between siblings, with stalls detected

Tools and integration

Feature	What it does	Why you want it
Tool config and A/B	Tool descriptions and settings are editable data on top of the code	Test two wordings of a tool, or point two copies at different accounts
Encrypted secrets	Credentials are stored encrypted and referenced by name	Point a tool at your account without pasting a key into config
Call any HTTP API	A step can fetch a URL, or be pinned to one API with the key stored encrypted and hidden from the model	Connect to a service you already pay for without writing a tool
Run code it wrote	A step can write Node, Python, or shell and run it in a capped subprocess with none of your keys in it	Arithmetic, parsing, and charts get computed instead of guessed at
Filesystem limits	Tools get scoped paths instead of raw disk access	A run writes in its own directory and cannot reach outside it
Bring your own tools	Drop a file in a `tools` folder, install a tool package, or connect an MCP server	Add a tool without forking or rebuilding anything

Operations

Feature	What it does	Why you want it
Storage that fits	SQLite, Postgres, plain files, or memory	Start on a laptop, move to a real database when it matters
Nothing gets stuck	Runs check in, dead ones get cleaned up, answered ones that never got restarted are picked back up, and cancel stops the run	No run sits waiting forever because something crashed at the wrong moment
Web UI, CLI, API	One engine, three ways to use it	Click through it, script it, or call it from your own app
Embed the runtime	`agent bundle` puts the runtime in your tree and `runAgent` becomes a function call	Ship agents inside your product with no separate service to run

The control panel

An agent: its prompt, model tier, step limit, and the pipeline that says what it does. Every save keeps a version, and each run links back to the version that produced it.

Run history, like a git log. Sub-agent calls nest under the run that made them, each with its own tokens, cost, and time. A pipeline's total is the sum of its parts.

One run in full: what it cost, what it called, and what each part said.

When a run needs a person it pauses and waits. No process is held open. The form is built from the question, so a step that offers three choices cannot get a fourth.

Agents ask for fast, default, or reasoning. You decide what those point at, prices included. Every agent picks up the change on its next run.

Tools are code, but their descriptions and settings are editable data on top. Two entries can share one implementation with different wording or different accounts.

What agents wrote down to remember between runs. A watermark, a last-seen id, a decision that should not get made twice.

Runs, cost, tokens, average duration, and recent errors for the last 24 hours.

Under the hood

TypeScript throughout. A small HTTP server, a React UI, and a runner you can embed in your own app.
One key, every provider. Models come through OpenRouter. Switching from Claude to GPT to Gemini is a setting, not an integration.
Laptop or cluster. SQLite by default with nothing to install. Postgres when you need more than one machine. Every storage option passes the same test suite, so behavior does not change with the backend.
Conditions are parsed, not evaluated. The expression language in routing conditions is a fixed whitelist. Nothing arriving over the API can reach past it.
Your tools are not second class. A tool you write in the tools folder gets the same schema handling, the same validation, the same catalog entry, and the same settings-on-top-of-code as one that shipped.

]]>

agents: getting started

mazzarelli@gmail.com (Joey Mazzarelli) — Tue, 15 Sep 2026 00:00:00 -0600

You need one API key and one npm install. There is no database to set up, no queue, and no broker. About five minutes from nothing to a working agent.

Get a model key

Sign up at openrouter.ai and copy an API key. One key covers every provider, so Anthropic, OpenAI, Google and the rest all work from it. It is the only credential you need.
Install it
```
npm install -g @upship/agents
agent serve
```
Paste the key in when it asks. That starts the API and the web UI on localhost:2137. Storage is a SQLite file under ~/.agents. You can point it at Postgres later if you outgrow that.

Make your first agent

Two ways, and neither needs a copy of the source. The first is to let the platform interview you. Open a second terminal, since the server is running in the first:

agent new

It asks what you want to build, follows up on the vague parts, then writes a draft and shows it to you:

What do you want to build?
(take as many lines as you like — blank line when you're done)

> something that watches my RSS feeds and summarizes new posts

draft
 Name: rss-summarizer
 What: Summarizes new posts across a list of feeds.
 Model: default
 Tools: web_search, write_file

 System prompt
 You are handed a list of feed URLs. Fetch what is new since the
 last run, and write one short paragraph per post: what it says,
 not that it exists.

 Notes
 Give it a durable memory namespace if you want it to remember
 where it stopped between runs.

Create it? [y/N]

Nothing is saved until you say yes.

The second way is to hand the job to the coding agent you already use:

agent skill install # writes the /new-agent skill
claude # then: /new-agent

Both read the same brief, and that brief is generated from your install. It lists the tools you have, including ones you wrote and ones that came from a package or an MCP server, and it explains how to add one when nothing fits. Run agent brief to print it if you want it somewhere else.

Run it
```
agent rss-summarizer "catch me up on this week"
```
Or open the web UI and click Run. Either way the run lands in history with its cost, its steps, and every sub-agent it called.

What you just installed

Everything lives under ~/.agents. That directory holds the .env with your key and settings, the SQLite database, and the folders tools read from and write to. Back up that one directory and you have backed up the install. Set AGENTS_HOME to put it somewhere else.

The server is a single Node process. It serves the HTTP API, the web UI, and nothing else. The CLI talks to it over that same API, so anything the CLI does you can also do over HTTP.

Where to go next

The agent you just made runs a freeform loop: the model picks tools until it is done. If you want fixed steps, branches, or a human approval in the middle, that is a pipeline.
If you want it to reach one of your own services, look at tools before you write any code. An HTTP API with a key is usually a config change, not a module.
If you want it to compute rather than estimate, give it run_script.

]]>

agents: operating it

mazzarelli@gmail.com (Joey Mazzarelli) — Tue, 15 Sep 2026 00:00:00 -0600

Which port does it use?

agent serve listens on port 2137, on 127.0.0.1 only. You can change it. For one start:

agent serve --port 3000

To change it for good, set PORT where the server will see it. Either of these works:

# in ~/.agents/.env, which the server reads on every start
PORT=3000

# or in your shell profile (~/.bashrc, ~/.zshrc)
export PORT=3000

The CLI finds the server through a separate variable, so if you move the port, move that too:

export AGENT_API_URL=http://localhost:3000

It says the port is already in use

Most likely another agent serve is still running, possibly in a terminal you forgot about. If so, use that one. Otherwise pick a different port as above. The error message names the port and gives the same options.

Can I reach it from another machine?

By default, no. The server binds to 127.0.0.1, and nothing on it asks for a password, so opening it up is a decision you make on purpose. Set HOST to listen wider, and put it behind something that authenticates first:

# ~/.agents/.env
HOST=0.0.0.0

There is no login, no bearer token, and no notion of a caller anywhere in the system. Treat reachability as the whole security boundary.

Where does everything live?

Under ~/.agents. The .env with your key and settings, the SQLite database, and the directories tools read from and write to. Back up that directory and you have backed up the install. Set AGENTS_HOME to put it somewhere else.

Running it against Postgres

SQLite is fine for one machine. Postgres is for when more than one process, or more than one machine, needs the same agents and history.

The database has to exist. The tables do not. They get created the first time the server starts, and a database from an older version picks up any columns it is missing the same way.

Set the driver and the connection in ~/.agents/.env, then restart:

# ~/.agents/.env
STORE_DRIVER=postgres
PGHOST=db.example.internal
PGPORT=5432
PGUSER=agents
PGPASSWORD=...
PGDATABASE=agents

agent serve
# Agent platform running on http://127.0.0.1:2137 (storage: postgres)

Everything lands in a schema named agents inside that database, so it can share a database with other things. Set DB_SCHEMA to use a different name. The user needs to be able to create the schema and its tables on the first start. After that, ordinary read and write is enough.

Two servers pointed at the same database see the same agents, runs, secrets and memories. The SQLite file under ~/.agents stays where it was, so switching back is a matter of changing STORE_DRIVER again.

A run is stuck at “running”

It should not stay that way. Runs check in on a heartbeat, and a reaper closes out the ones that stopped checking in. A crashed run gets recorded as an error rather than left hanging, and cancel stops the run.

What the reaper does not do is resume anything. A dead run is closed, not continued. If that matters for your workload, read the durability section of the Flue comparison, which says where this falls short.

A paused run is not the same as a stuck run

A run waiting on a person holds no process. It sits in the database with a token, and it will wait as long as it takes. agent pending and GET /api/runs/pending list everything in that state.

The one thing the server does resume is a paused run that already got its answer. Answering is a write to the row, and restarting the run is a second step; if the server goes down between the two — a deploy landing at the wrong second — the run would otherwise sit there answered and unfinished forever. So every server sweeps for that on startup and every thirty seconds after, and picks those runs back up. It waits a minute first, so it adopts a run nobody is holding rather than racing a restart already under way.

Upgrading

npm install -g @upship/agents@latest

Restart the server. Schema changes apply on start. If you vendored the runtime with agent bundle, run that again after updating the CLI.

]]>

agents: running code

mazzarelli@gmail.com (Joey Mazzarelli) — Tue, 15 Sep 2026 00:00:00 -0600

Give an agent the run_script tool and it can write Node, Python, or shell and run it. This is for work you want computed instead of estimated. Arithmetic over a lot of numbers, reshaping a file, checking a pattern against real input. It is not a box for code you have a reason to distrust.

How safe is it

Safer than running it in the server process. Not as safe as a container.

A script gets its own process with an empty environment. None of your keys, none of your secrets. It gets a private working directory, a wall clock time limit, and a cap on how much it can print.

On Linux it also loses the network and gets a memory limit, if the kernel allows it. On a Mac it gets neither. A Node script is held to an interpreter heap limit and that is all.

What no host gets is a filesystem boundary. A script can still read whatever the user running the server can read.

The important part is that it says so. The tool tells the model what it managed on this machine, and the Tools page prints the same line for you. It does not claim isolation it does not have.

What can a script do on my machine

Ask the install instead of guessing from the operating system. What it locked down is probed against the real kernel at startup, so the answer is different on your laptop and on your server.

agent brief | grep -A2 run_script
# - **run_script** — Run a short program you wrote in a sandboxed subprocess...
# on this host: node (node), python (python3), sh (bash); subprocess (isolation
# from accidents, not from intent: this host has no namespaces); network NOT
# blocked — this host cannot drop it; memory NOT capped — this host ignores the rlimit

The same line is on the Tools page, and over HTTP:

curl -s localhost:2137/api/tools/implementations \
 | jq '.[] | select(.name=="run_script") | .hostNote'

It reports three things:

Which languages exist here. Node, Python 3, and a shell are looked for on PATH. The model is only offered the ones that were found.
Whether the network was taken away. That needs Linux with unprivileged user namespaces. Anywhere else it says so.
Whether the memory cap is real. A kernel rlimit on Linux, the interpreter’s own heap limit for Node, and nothing at all on macOS, which ignores the rlimit.

Every run records it too. A run_script result carries a sandbox field with the same sentence, so a run from six months ago still says what it was running under.

Turning it on

Add run_script to an agent’s tools, like any other tool. There is nothing else to switch on. Out of the box it gets thirty seconds, a 512 MB memory cap, 64 KB of output per stream, and no network.

curl -X POST localhost:2137/api/agents \
 -H 'content-type: application/json' \
 -d '{"name":"analyst","description":"Answers questions about data files",
 "systemPrompt":"Compute answers with a script rather than estimating them.",
 "tools":["read_file","run_script"]}'

The script runs in the run’s own output directory, which is where read_file and write_file already point. So it can read what an earlier step wrote, and anything it leaves behind comes back attached to the run. A chart it drew shows up as an image on the run page.

Changing the limits, or pinning a language

The limits are deliberately not parameters the model can set. They live on a tool definition, next to the description:

curl -X POST localhost:2137/api/tools \
 -H 'content-type: application/json' \
 -d '{"name":"run_python","implementation":"run_script",
 "description":"Run a Python script over the files in this run.",
 "parameterOverrides":{"language":"python","timeoutMs":120000,
 "maxMemoryMb":2048,"maxOutputBytes":262144,
 "network":false}}'

Then give the agent run_python instead of run_script. The Tools page does the same thing without the curl.

language pins one of node, python, sh. Pinned, it stops being a question the model answers. If that interpreter is not installed here, the tool refuses to build and names what is, rather than failing on the first call.
network: true is the only way a script gets the network, and it means nothing on a host where the network could not be dropped in the first place.
timeoutMs, maxMemoryMb and maxOutputBytes cap out at ten minutes, 8 GB, and 4 MB. A typo above the ceiling is rejected when the tool is built, not after a run has been parked for a day.

Two definitions can point at the same implementation with different limits. A quick one for arithmetic, a longer one for a large file. Each is versioned.

Turning it off

It is off until you ask for it. run_script only runs for an agent that lists it, so there is no global switch to throw. Turning it off means taking it out of the agents that have it. To find them:

curl -s localhost:2137/api/agents \
 | jq -r '.[] | select((.tools // []) | index("run_script")) | .name'

Then edit those agents and remove it, in the browser or with a PUT. That is a save like any other, so the version that had it is still in the history.

If what you want is a stronger boundary rather than no scripts, isolate the server. Run agent serve as its own user, or in a container, or on a machine you do not mind it reading. A script cannot see your keys or call a model, but it can read what the server’s user can read, and no setting here changes that.

Python is not in the list

Only what was found on PATH when the server started gets offered, and that discovery happens once per process. Installing Python and expecting the running server to notice will not work. Install it, then restart:

python3 --version # make sure the server's PATH will find it
# restart agent serve, then:
agent brief | grep -A2 run_script

A sh that is there and a python that is not is the usual shape of this on a slim container image.

]]>

agents: tools

mazzarelli@gmail.com (Joey Mazzarelli) — Tue, 15 Sep 2026 00:00:00 -0600

Agents are data. Tools are code. That is the one line you have to cross to add a capability, and most of the time you do not have to cross it. Pointing an agent at an HTTP API is a config change.

What ships

About twenty tools come with it. Files, search, HTTP fetch, OCR, image generation, shared state, durable memory, peer messaging, human gates, self-critique, and a sandboxed script runner. An agent gets the ones you list in its tools array and nothing else.

agent tools

That prints every tool an agent can name, which ones need to be configured first, and where each one came from. It also lists the files that failed to load and what went wrong in them. The Tools page in the browser shows the same thing.

Tool definitions are data too

The implementation is code. The description, the settings, and the bound credentials are a row on top of it. That means two definitions can share one implementation:

The same fetch tool pointed at two different accounts.
Two wordings of a description, A/B tested against the same input.
A script runner capped at thirty seconds and another one allowed ten minutes.

Anything a model should not be choosing belongs there rather than in the parameters the model fills in. A question’s wording, a sandbox’s limits, a namespace, an API key. If the model can set the timeout, the timeout is not a limit.

Definitions are versioned like everything else, so an old run still records the description that was live when it ran.

Calling an HTTP API

Before you write a tool, check whether you need one. If the thing you want is an HTTP API with a key, the built-in fetch tool plus an encrypted secret gets you there with no code.

Pin a definition to one host, put the credential in the headers, and the model never sees it. A tool that can call one service cannot be talked into calling another with your key attached.

It will not touch your network by default

The fetch tool refuses anything that is not a public address. Your own machine, your home or office network, and the ranges cloud providers reserve for themselves are all turned down. It checks the hostname and the addresses that name resolves to, and it re-checks every redirect hop, so a public URL cannot bounce an agent somewhere private.

That default exists because the platform itself sits on one of those addresses. Without it, an agent could ask its own server for your stored secrets and read them back to you in an answer.

If you do want an agent to reach something on your network, you say so on a tool definition. You can pin it to a single host while you are there.

Secrets

Credentials go in an encrypted store and get referenced by name. The write API is write-only, so a secret goes in and never comes back out over HTTP. Tool config refers to it by name, the runtime resolves it at call time, and the model sees neither the name nor the value.

Rotating a key is a save. Nothing redeploys.

Writing your own tool

Write one file and restart. Everything in the tools folder next to where you start the server loads at startup. Putting a file there is the whole installation. There is no list to add it to.

// tools/whatsapp.ts
import { z } from "zod";
import { defineTool } from "@upship/agents/tools";

export default [
 defineTool({
 name: "parse_whatsapp",
 description:
 "Parse a WhatsApp export into messages. Pass `after` to get only what is newer " +
 "than a previous call. Use this instead of reading the file, since an export is " +
 "far too big to pass through a tool call.",
 parameters: z.object({
 path: z.string().describe("Path to the export."),
 after: z.string().optional().describe("Cursor from last time. Omit for the whole file."),
 }),
 async execute({ path, after }, ctx) {
 return parseExport(await ctx.files.read(path), after);
 },
 }),
];

The description is what the model reads to decide whether to call it, so write it for the model. What it does, when to use it instead of something else, and what it will not do. Every parameter gets a .describe().

The schema gets used twice. Once to tell the model what the arguments are, and once to check them when a pipeline step supplies them. A tool you write behaves like one that shipped.

A file cannot take a name that already exists: the platform keeps the original and tells you it did. Changes need a restart, because there is no reliable way to unload code that is already running. npm run dev restarts on its own.

Packages and MCP servers

A tool package installs like any dependency and registers the same way. An MCP server connects over stdio or HTTP at boot and its tools show up with a prefix. Both land in the same registry as the built-ins, which means they get catalog entries, tool definitions, config binding, and a line in the authoring brief without any extra work.

When not to write a tool

An HTTP API with a key. Use the fetch tool and a secret.
A one-off calculation or a parse. Let the model write a script and run it.

Both of those are settings. Neither is a file.

]]>

KHTDR – agents

agents: how it compares

The short version

Against Flue

The disagreement

Side by side

What Flue does better

What this project does better

Pick Flue if

Pick this if

Bottom line

Against Sapiom

Side by side

What Sapiom does better

What this project does better

Pick Sapiom if

Pick this if

Bottom line

What I would have to build to close the gaps

agents: CLI, API, embedding

The CLI

The HTTP API

Embedding it in your own app

agents: features

Authoring and versioning

Pipelines

Getting a better answer

People in the loop

State and memory

Tools and integration

Operations

The control panel

Under the hood

agents: getting started

Get a model key

Install it

Make your first agent

Run it

What you just installed

Where to go next

agents: operating it

Which port does it use?

It says the port is already in use

Can I reach it from another machine?

Where does everything live?

Running it against Postgres

A run is stuck at “running”

A paused run is not the same as a stuck run

Upgrading

agents: running code

How safe is it

What can a script do on my machine

Turning it on

Changing the limits, or pinning a language

Turning it off

Python is not in the list

agents: tools

What ships

Tool definitions are data too

Calling an HTTP API

It will not touch your network by default

Secrets

Writing your own tool

Packages and MCP servers

When not to write a tool