Self-hosted platform for running autonomous AI agents on your own machine.
Overview · Features · Install · Architecture · Status · Documentation
AI17Z runs AI agents that keep their identity, memory and configuration independently of the language model behind them. Each agent has a persona, long-term memory, relationships, knowledge sources, goals and a policy, all stored in a local Postgres database. The model provider can be changed at any time without losing any of it.
Agents connect to channels such as X through a real Google Chrome session, decide whether and how to respond, and record why. Everything runs locally: the database, the browser profile, provider keys and agent memory never leave the machine.
Durable job pipeline. Every inbound event is stored and processed as a job. Each step commits before the next starts, so a restart resumes work instead of repeating it.
No duplicate actions. Events, jobs and outbound actions are deduplicated by unique database constraints, and the target is verified again immediately before anything is sent.
Full audit trail. Each response stores its prompt, the memories retrieved and why, every model attempt, and the verification before the action. Decisions not to respond are recorded with their reasons too.
Any model provider. OpenAI, Anthropic, OpenRouter, Ollama, any OpenAI-compatible endpoint, and a deterministic mock, behind one gateway with fallback. Local models are fully supported.
Real browser sessions. Browser-backed channels drive installed Google Chrome over CDP with a persistent profile. CAPTCHAs, two-factor prompts and other security challenges are always handed to a person; AI17Z never attempts to solve or bypass them.
Dry run by default. The full pipeline runs and verifies its target, then stops before taking any real action.
Plugins and permissions. Capabilities are granted per agent and checked both when work is queued and again before it executes.
Portable agents. Any agent can be exported to a single file and imported into another installation.
AI17Z runs on Windows 10 and 11, macOS 13+ and Ubuntu 22.04+. It uses Docker for the database. Git is not required, and the macOS and Ubuntu packages include their own Node runtime. Google Chrome is optional and enables browser-backed channels.
| Platform | Recommended | Also available in each release |
|---|---|---|
| Windows 10 and 11 | The command below | AI17Z-Setup-<version>.exe |
| macOS 13+ (Apple silicon and Intel) | The command below | AI17Z-macos-arm64-<version>.tar.gz, AI17Z-macos-x64-<version>.tar.gz |
| Ubuntu 22.04+ (amd64 and arm64) | The command below | ai17z_<version>_amd64.deb, ai17z_<version>_arm64.deb |
The installers download from GitHub releases,
and from AI17Z Code, AI17Z's own
server, when GitHub cannot provide a file. Both carry the same files, and every
download is checked against the release's
SHA256SUMS.txt
before it is used. Release names such as beta-v9.7 correspond to semver tags
such as v1.0.0-beta.87.
Open Windows Terminal and run:
irm https://raw.githubusercontent.com/ShiftAboveCtrl/ai17z/main/install.ps1 | iexThe installer checks the system, installs any missing prerequisites, installs AI17Z, starts it, confirms it is working and opens it in your browser.
Open a terminal and run the line for your system. Each downloads a short shell script you can read before running it.
curl -fsSLO https://raw.githubusercontent.com/ShiftAboveCtrl/ai17z/main/install-ai17z-macos.sh && bash install-ai17z-macos.shcurl -fsSLO https://raw.githubusercontent.com/ShiftAboveCtrl/ai17z/main/install-ai17z-ubuntu.sh && bash install-ai17z-ubuntu.shThe same installers are on AI17Z Code. Use these instead:
irm https://code.ai17z.io/AI17Z/ai17z/raw/branch/main/install.ps1 | iexcurl -fsSLO https://code.ai17z.io/AI17Z/ai17z/raw/branch/main/install-ai17z-ubuntu.sh && bash install-ai17z-ubuntu.shInstall AI17Z only with the command published here or from the release pages linked above. Nowhere else distributes it. The Windows command downloads
install.ps1from this repository, verifies the setup script against the release'sSHA256SUMS.txtbefore writing anything, and verifies it again immediately before running it.The installer does not disable SmartScreen, Defender, UAC or the PowerShell execution policy. docs/SETUP_AUDIT.md lists every host it contacts and every change it makes, including what the checksum does not protect against.
AI17Z releases are not code-signed at this time. We will never ask you to disable SmartScreen, Smart App Control or your antivirus. We will never ask you to click past a warning. See Windows trust and SmartScreen and the code signing policy for details.
Full instructions, building from source, updating, running several copies and troubleshooting are in docs/INSTALL.md.
apps/api Fastify HTTP API. Owns no browsers.
apps/worker Job worker, channel poller and browser runner.
apps/web React web interface.
packages/shared Shared contracts, crypto, logging and environment.
packages/database Postgres pool, migrations and repositories.
packages/jobs Postgres-backed job queue with leases and recovery.
packages/models Model gateway and provider adapters.
packages/memory Memory scopes, retrieval and write policy.
packages/prompts Layered prompt engine.
packages/channels Channel contract, mock channel and X adapter.
packages/browser Chrome session management over CDP.
packages/persona Persona corpus processing and trait derivation.
packages/tools Capability contract and built-in capabilities.
packages/runtime Validation, policy, ingest and the pipeline state machine.
Each action follows the same pipeline:
inbound event → stored event → job → context and memory
→ prompt and model → validation and policy
→ target verification → action or recorded decision not to act
→ outcome → learning
Platform-specific details stay inside packages/channels. Everything else
works on normalised contracts.
AI17Z is in beta and under active development.
| Area | Status |
|---|---|
| Job pipeline, recovery and deduplication | Available |
| Memory, relationships, beliefs and knowledge | Available |
| Model gateway with provider fallback | Available |
| Browser-backed channels with Google Chrome | Available |
| Owner chat, Agent Foundry and Response Lab | Available |
| Plugins and capability permissions | Available |
| Agent export and import | Available |
| Windows, macOS and Ubuntu packages | Available |
| Agent wallet (owner-approved, read-only to models) | Available, off by default |
| Hosted runtimes | In development (details) |
| Trading | In development, no live funds (details) |
Every release must pass the full test suite, typecheck, lint, a production web build, a dependency audit, ShellCheck, database migrations from empty and from the previous release, a privacy and secret scan, and a clean install and upgrade test that confirms no data is lost.
- No telemetry. AI17Z sends no usage data anywhere.
- Encrypted keys. Provider API keys are encrypted with AES-256-GCM under a master key that stays on your machine, and never appear in API responses, logs or traces.
- Your choice of services. The only outside services contacted are the model providers and channels you configure. docs/PRIVACY.md lists them.
Getting started
- Installing and running AI17Z
- Setup audit: every host contacted and change made by the installer
- Windows trust and SmartScreen · Code signing policy
- Uninstalling · Privacy
- Local setup · Docker · Browser sessions
Architecture
- Overview · Data model · Jobs · Data flow
- Memory · Channels · Models · Pipelines
- Social layer · Deliberation · Response Lab
- Cadence · Capabilities · Easy Mode
- Sign-in and security challenges · Persona sources
- Browser runtime · Reading channels · Notifications
- Agent packages · Security · Updates
- Engineering notes
Issues and pull requests are welcome. See CONTRIBUTING.md, CODE_OF_CONDUCT.md, and SECURITY.md for reporting vulnerabilities privately.
npm install # install dependencies
npm run db:up # start Postgres in Docker
npm run migrate # apply migrations
npm run dev # run api, worker and web
npm test # unit and integration tests
npm run typecheck # typecheck every packageThe only official AI17Z token contract address is:
0x16CB7cBb26295b60DF7f4B3B39a99a9A3c585E81
Any other address claiming to be AI17Z is not official. The token is not required to install or use AI17Z.
AI17Z is released under the MIT License. The terms of any service an agent connects to remain between you and that service.