Lot 7 of acme-web is ready to prepare.
Agents that cannot reach each other
Each harness has its own session and no shared mailbox. ameesh gives every agent a durable mailbox on Postgres, with hooks that keep the v0 interface.
- Open source · AGPL-3.0-only
- v1.0.0
- Python 3 · Postgres
Humans and AI agents, working as one accountable team.
ameesh coordinates mixed teams of humans and AI agents across agent harnesses. Every agent has a human responsible for it, runs where its humans decided, talks in threads anyone can read, and cannot merge, send or spend anything irreversible without a receipt a human signed on their phone.
Runs agents in Claude Code Codex DeepSeek Harness
thread · acme-web
Lot 7 is ready: review PR acme/acme-web#7 before the merge.
$ ameesh action execute act_…
[receipt_required]
$ ameesh action fetch-receipt act_…
receipt from human:alice · webauthn · verified
The problems it solves
Once several agents from several vendors work on the same project, alongside humans, a terminal per agent stops being enough.
Sessions that die with the terminal
Orchestrators glued to an interactive session lose their watch when it closes. ameesh runs agents by turns under leases, resumes the same session, and still lets a human attach.
Chatter nobody can audit
Agent-to-agent messages vanish into private context. In ameesh every message that goes through it is written, verbatim, into a readable thread.
An agent that merges or spends on its own
A prompt injection or a mistake should not reach production. Irreversible and costly actions wait behind a gate for a human-signed receipt.
Nobody knows who answers for an agent
Responsibility, placement and credentials live in a reviewed canon. An agent without a responsible human, or placed against a host's policy, is never started.
Costs that run away
Each turn is accounted for. A budget guard pauses agents before an hourly cap or a subscription's pace is exceeded.
Key ideas
Declarations in git, state in the database, secrets on the host, authority on the human's phone.
Teams declared in OKF, in git
Members, hosts, agents and placements are OKF cards in a git repository, changed by reviewed pull request. ameesh reads only the merged canonical commit, through git objects, and fails closed when it cannot.
ameesh canon check | sync
One runner per host, with leases
A single runner per machine claims its agents under exclusive leases, wakes on LISTEN/NOTIFY, and resumes each agent's harness on the same session. Lose the lease, and the harness is killed.
ameesh run · ameesh attach <agent>
Every message, in clear
Messages, action transitions and session summaries are appended to a Markdown thread per project or lot. Bodies that are not readable text are refused.
ameesh fil show <project>
Irreversible actions need a receipt
An action has a stable id and a digest. It runs only with a receipt bound to that digest, single use, with expiry. An unknown outcome is reconciled, never retried blindly.
ameesh action propose | execute | reconcile
Signed with a passkey, out of reach
ameesh-approve runs under its own Unix user, shows the action recomputed from the database, and has the human sign it with a passkey. Passkeys are enrolled by canon pull request. One instance per team, in a strict profile: its own host name is its WebAuthn identity, and approve-check keeps every verifier consistent with it.
ameesh-approve serve · ameesh approve-check
Humans decide where agents run
The project's responsible human places agents; each host's responsible human sets which harnesses, providers and credential modes it admits. ameesh never moves an agent by itself.
ameesh placement check
Per-turn accounting, guarded turns
Cost per turn for each harness, subscription gauges read from the harnesses' own logs and kept as history, the provider's balance and real spend, an hourly cap on pay-per-token usage, and model, effort and tier set per agent.
ameesh cost turns | gauges | balance
Lots, agents and budget at a glance
A timeline of lots (requested, frozen, verdict, merged), what each agent is doing, and spend, as text, versioned JSON, or a standalone HTML page readable on a phone.
ameesh progress --html progress.html
One persistent agent per pod
A runner image and example Kubernetes manifests: read-only canon, no inbound network, non-root, plus read-only Postgres roles for an external supervisor.
kubectl apply -k deploy/k8s
Architecture
ameesh reads the canon and writes to it only by proposal. State lives in the database. Secrets are in neither. The approval service shares nothing with ameesh but receipts.
- CanonDeclarations only. ameesh reads the merged commit of the canonical branch; local edits and unpushed commits are reported, never used. An unreadable or invalid canon closes new claims.
- Runner and registryOne runner per host claims agents under exclusive, fenced leases. Postgres holds leases, sessions, mail, work items, actions and spend.
- Readable threadsThe mailbox is a delivery queue; the thread is the reference a human reads. One Markdown file per project or lot.
- Action gateThe state
launchedand the consumed nonce are committed before the external call, which receives the action id as its idempotency key. - ameesh-approveA separate service under its own Unix user. It recomputes what it shows from the database, and its token can request receipts, never sign them.
How an approval works
The end-to-end scenario of v1, as the demo plays it: an agent wants to merge a pull request.
- agentgate
The agent proposes a
git-mergeaction. ameesh gives it a stable id and a digest of exactly what will happen. Its class isirreversible. - gate
Execution is refused with
[receipt_required]. The action now waits in the human's queue:ameesh decisions --for human:alice. - ameeshameesh-approve
ameesh requests an approval. The service recomputes the summary from the action in the database, never from the agent's text, and a single-use link is written to the thread.
- humanphone
The human opens the link on their phone, sees the action, amount and short digest, and signs with their passkey. User verification is required, and only the approver's enrolled credentials are allowed.
- ameeshameesh-approve
ameesh fetches the receipt and verifies it itself: the digest, the origin and RP ID, the signature against the passkey registered in the canon, the expiry.
- gateconnector
The action is launched. The nonce is consumed and
launchedis committed before the call; the connector receives the action id as idempotency key. - gate
If the answer is lost, the outcome is
unknownand never retried automatically.ameesh action reconcileasks the connector what happened. Replaying the receipt fails with[replay].
Quickstart on the bench
The whole v1 scenario on your machine: a local Postgres container, a fictitious organisation, fake harnesses, a fake gh and a software passkey. Nothing real is called, and the temporary database is dropped at the end.
$ git clone https://github.com/manaty/ameesh.git && cd ameesh
$ export AMEESH_PG_PASSWORD='choose-a-local-password' PGPASSWORD="$AMEESH_PG_PASSWORD"
$ scripts/pg-up.sh # postgres:17 on 127.0.0.1:55432 only
$ scripts/demo-v1.sh # canon → runner → thread → gate → receipt → reconciliation
$ scripts/test.sh # the full suite, with the psql and psycopg driversRequirements: Python 3.9 or later, git, Docker, and the psql client or psycopg. Next: Getting started, then write your own canon. Moving a running team from the v0 scripts is covered step by step, with rollback, in Switch from a v0 setup.
Security, stated honestly
What v1 guarantees, and what it does not yet. Straight from the specification.
Guaranteed in v1
- An agent without a responsible human, or misplaced against its host's policy, does not run.
- No irreversible action without a valid receipt when it goes through ameesh's gate.
- Receipts are bound to the digest, single use, and expire.
- The registry of authenticators changes only by reviewed pull request to the canon.
- A readable thread of every message that goes through ameesh.
Not yet
- Isolation of agents from each other: locally they share the same Unix user.
- The gate protects against mistakes and prompt injection, not against a malicious agent sharing ameesh's Unix user, which could read business credentials or modify ameesh and its database.
- Gate and business credentials under a separate user, network sandbox, MCP proxy.
- Strong non-repudiation for synced passkeys (the high level means a hardware key).
- Provenance signatures on agents' messages; messages exchanged outside ameesh are not captured.
Read the full security model, including the lease invariant and the limits of the cluster profile.
Status and roadmap
v1 runs on a test bench today; the switch of a real team is documented step by step. No dates are promised.
Done v1.0.0
- Canon reading, validation and sync; responsible humans; ephemeral agents
- Governed placement in the claim predicate
- Readable threads
- Actions, gate, reconciliation,
git-merge - Receipts (WebAuthn, device ES256; Ed25519 for tests and agent provenance, refused for human approval by default) and ameesh-approve
- Events, coalescing,
ameesh attach - Storage interface; suite green on two drivers
Built since v1.0.0
- Turn interruption, session rotation with summary
- Per-turn cost accounting and budget guard
- Review classes by file scope, delay metrics per lot
- Model catalogue and discovery
- Real-time progress view
- Cluster hosting profile
- Operations: session per lot, alerts, restart on a brief, provider balance
- ameesh-approve per team: strict profile,
approve-check, local TLS
Planned next
- Provisioning of hosted ameesh-approve (relay, dedicated page)
- Model evaluation; harness descriptors and catalogue
- Signal intake and a bounded self-repair loop
- More thread transports; the gate as an MCP proxy
- SQLite driver; one Unix user per agent
Details: status and roadmap. The design (specification, decisions, studies) is in docs/design/, in French.
License and contributing
Open source from the first public release, with the design written down in the open.
Free software, AGPL-3.0-only
ameesh is released under the GNU Affero General Public License v3, only variant. Anyone who runs a modified ameesh as a network service must offer its source code to its users.
Contributing
External contributions are accepted under a contributor license agreement, which is being prepared: open an issue first to discuss your proposal. Tests run on a real Postgres with both drivers.