AI17Z

A local-first platform for persistent autonomous AI agents.

The model is replaceable. The agent is durable.

Install · What makes it different · Architecture · Status · Documentation

---

The idea

Most agent frameworks are a wrapper around a model call. Change the model and you have changed the agent, because the model was the agent.

AI17Z splits those apart. The provider supplies replaceable intelligence; AI17Z supplies the part that persists:

identity · persona · memory · relationships · beliefs and stances · commitments · knowledge and its provenance · goals · policy · learning

An agent keeps that across restarts, across model changes, and across providers. Swap the model and the same agent answers in the same voice from the same memory, because none of that lived in the model.

It runs on your own machine. The database, the browser profile, the keys and every memory stay there.

---

What makes it different

Durable by construction, not by convention. Every inbound event becomes an immutable record and a job. Jobs survive restarts and resume from the last completed step, because each step commits before the next begins.

The same event cannot act twice. Not by careful coding: by unique index. Three layers of idempotency, enforced by the database, plus exact-target verification immediately before anything irreversible.

Answerable behaviour. Every generation stores its prompt layers, which memories it retrieved and why, every model attempt, and the verification that preceded the action. "Why did it do that?" and "why did it stay silent?" both have recorded answers.

Silence is a result. An agent that decides not to act records the decision and its reasons. A correctly quiet agent does not look broken.

A real browser, honestly. Browser-backed channels drive actual installed Google Chrome over CDP with a persistent profile, with both the chosen executable and what the browser reported about itself stored and shown. A CAPTCHA, a second factor or a device challenge stops the agent and waits for a person: there is no solver and no bypass, and no setting that changes it.

Replaceable models. OpenAI, Anthropic, OpenRouter, Ollama, any OpenAI-compatible endpoint, and a deterministic mock, behind one gateway with a fallback chain. Local models work; nothing requires a cloud provider.

A safe default. Dry run executes the whole pipeline, verifies the target, and stops before touching anything real.

---

Install

AI17Z installs on Windows, macOS 13+ and Ubuntu 22.04+. None of them needs Git, and the macOS and Ubuntu packages carry their own verified Node runtime. All three use Docker for the database. Google Chrome is optional and enables browser-backed channels.

Windows

Open Windows Terminal and paste:

irm https://code.ai17z.io/AI17Z/ai17z/raw/branch/main/install.ps1 | iex

That is the whole installation: it checks the machine, installs what is missing, installs AI17Z, starts it, verifies it works, and opens it.

macOS and Ubuntu

Download the short installer from the latest release, read it, and run it. Both are plain shell scripts, deliberately short enough to audit.

Install AI17Z only with the command published here. Nowhere else distributes it. The command fetches code.ai17z.io/AI17Z/ai17z/raw/branch/main/install.ps1, checks the setup script against the release's own SHA256SUMS.txt before writing anything, and re-checks it immediately before running it.

AI17Z is not code-signed, so where it came from is the whole of the answer to who wrote it. Nothing in the install path disables SmartScreen, Defender, UAC or the PowerShell execution policy, and docs/SETUP_AUDIT.md lists every host it may contact and every change it may make, including what the checksum does not protect against.

Code signing

AI17Z is not signed, and is not about to be. Free certificates for open-source projects are granted on the strength of an existing user base; we applied and were turned down for not having one yet. Saying signing is coming would be a nicer sentence and not a true one.

That is why the ordinary way in is a command rather than a download. We will never ask you to disable SmartScreen, Smart App Control or your antivirus, or to click past a warning. Windows trust and SmartScreen explains what those warnings actually mean, and docs/CODE_SIGNING_POLICY.md is where this stands.

Full instructions, from-source builds, updating, running several copies and troubleshooting: docs/INSTALL.md.

---

Architecture

apps/api         Fastify HTTP layer. Owns no browsers.
apps/worker      Job worker, channel poller, browser runner. Owns all browsers.
apps/web         React single-page app.

packages/shared     Isomorphic zod contracts, crypto, logging, environment.
packages/database   Postgres pool, migrator, one repository per domain.
packages/jobs       Postgres-backed queue: claim, lease, recover, back off.
packages/models     Model gateway and provider adapters.
packages/memory     Six memory scopes, retrieval, write policy.
packages/prompts    Layered prompt engine.
packages/channels   Channel contract, mock channel, X adapter.
packages/browser    Playwright session manager, real Chrome over CDP.
packages/persona    Corpus normalising, scoring, trait derivation.
packages/tools      Capability contract and built-in capabilities.
packages/runtime    Validator, policy gates, ingest, pipeline state machine.

The pipeline every action goes through:

inbound event → immutable event → durable job → context and memory
  → prompt, model, capability decisions → validation and policy
  → exact-target verification → remote action or deliberate silence
  → verified outcome → learning

Nothing downstream of a channel adapter knows what any particular platform looks like. No selector, no cookie and no vendor payload leaves packages/channels; everything else operates on normalised contracts.

---

Status

AI17Z is in beta and under active development. It is used daily against real accounts by its authors.

Area	State
Durable pipeline, jobs, idempotency	Shipped
Memory, relationships, beliefs, knowledge	Shipped
Model gateway and provider fallback	Shipped
Browser-backed channels with real Chrome	Shipped
Owner chat, Agent Foundry, Response Lab	Shipped
Plugins and capability permissions	Shipped
Agent packages: share, move, export	Shipped
Windows, macOS and Ubuntu packaging	Shipped
Agent wallet: owner-approved, read-only to models	Shipped, disabled by default
Hosted runtimes	Runtime proved, not sold: see below
Agentic trading	Complete to the signing boundary, no funded order

Hosted runtimes, specifically. The runtime a customer would rent exists and runs: AI17Z boots inside its own virtual machine, from a plan this repository renders, with its own kernel, database, key, disk and unprivileged user. Two tenants run side by side and neither can reach the other's runtime while that runtime is answering its own. Six run at once at about 531 MB each. A tenant killed as hard as a power cut comes back with everything it had. A tenant is provisioned end to end by the step machine in tenantProvisioning.ts.

It is not sold, and the reason is the whole point. The offer would be that whoever runs the machine cannot read your agent. On ordinary hardware that is false: tenants are isolated from each other and not from an administrator. What changes it is confidential hardware with attestation-gated key release, and none has been provisioned, so the attestation verifier, the measurement policy, the key-release interface and both cloud adapters are built and tested against fixtures rather than against a machine. Phase 1 contracts are frozen as a candidate with that canary outstanding. CONFIDENTIAL_COMPUTE.md is the research, the costs and the provider comparison; HOSTING.md is what was measured and what has deliberately not been claimed.

Releases are versioned with strict semver and every one is gated on the full test suite, a cold typecheck, lint, a production web build, a production dependency audit, ShellCheck, fresh and existing database migrations, a privacy and secret scan, and a clean-room install verification that installs twice, upgrades over itself, and asserts no data was lost.

---

Your data

Everything an agent knows stays on the machine running it: the Postgres database, the browser profile, the signed-in sessions, the keys and every memory.

• No telemetry. AI17Z phones no home. There is no analytics endpoint.
• Provider keys are sealed with AES-256-GCM under a master key that never leaves the installation, and are readable only by the code that calls a provider. They never appear in an API response, a log line, an audit row or a trace.
• What does leave is what you point an agent at: the model provider you chose, and the services you connected it to. docs/PRIVACY.md itemises it.
• It is yours to leave with. Any agent exports to a single portable document that any other AI17Z installation can import.

---

Documentation

Getting it running

• Installing and running AI17Z — all three platforms, from source, updating, troubleshooting
• Auditing AI17Z Setup — every host it may contact and change it may make
• Windows trust and SmartScreen · Code signing policy
• Uninstalling and removing your data · Privacy
• Local setup · Docker · Driving a real browser

How it works

• Engineering notes — the invariants, and what broke to produce each one
• Architecture overview · Data model · Jobs and the runtime
• End-to-end data flow — where each responsibility lives
• Memory · Channels · Models · Pipelines
• The social layer — identity, relationships, voice
• Persistent autonomous deliberation — what an agent thinks about between the things it is asked
• The Response Lab — what an agent would say to a real post, and everything that fed the answer
• Cadence · Capabilities · Easy Mode
• Connecting an account and security challenges · Persona sources
• Browser runtime · Reading a channel · Owner notifications
• Agentic trading · in development: what a model may propose, and the generic transaction verbs it can never reach
• Confidential compute · in development: what would actually protect a hosted agent from the machine's operator, and what has not been proved
• Hosted runtimes · in development: the isolation boundary, key custody, and what has deliberately not been claimed
• Agent packages · Growth · Security · Updates

AI17Z can read these itself: attach docs/ as a knowledge source and an agent can answer questions about the exact version you are running.

---

Contributing

Issues and pull requests are welcome, on AI17Z Code. CONTRIBUTING.md covers the workflow and what the gates expect, CODE_OF_CONDUCT.md covers the project's own spaces, and SECURITY.md is how to report a vulnerability privately.

npm install          # install dependencies
npm run db:up        # Postgres in Docker
npm run migrate      # apply migrations
npm run dev          # api + worker + web
npm test             # unit and integration suites
npm run typecheck    # tsc across every package

---

Token

AI17Z has an associated token. The only contract address is:

0x16CB7cBb26295b60DF7f4B3B39a99a9A3c585E81

Any other address claiming to be AI17Z is not. The token is not required to install, run or use anything in this repository: AI17Z is MIT-licensed software that runs locally and needs no token, wallet or payment.

---

License

MIT. Use it, change it, ship it; keep the copyright notice.

Nothing in the dependency tree argues with that. Of 372 installed packages: 305 MIT, 23 ISC, 13 Apache-2.0, 7 BlueOak-1.0.0, 6 BSD-3-Clause, 1 CC-BY-4.0, 1 0BSD, and 16 that declare nothing. No GPL, AGPL, SSPL or BUSL anywhere.

The licence covers this code. It does not cover what you do with it: the terms of any service an agent acts on are between you and that service.