Architecture
Zyx is a TypeScript system that runs on the company’s own server, a macOS or Linux machine. Every part below runs on that machine. What goes out: the text sent to a hosted AI model (a local model keeps it in), and the calls to connected apps and the web that the kernel allows.
The parts
Section titled “The parts”Browser, phone, AI tools, webhooks │ ▼┌──────────────────────────────────┐│ Workspace (Next.js 16) ││ screens, API, login gate, ││ MCP server, schedule tick │└────────────────┬─────────────────┘ ▼┌──────────────────────────────────┐│ eve runtime ││ CLI seat: Claude, Codex ││ own loop: Ollama, Bedrock EU, ││ Mistral, OpenRouter, Anthropic │└────────────────┬─────────────────┘ ▼ every tool call┌──────────────────────────────────┐│ Kernel: decide() ││ privacy gate, private paths, ││ folders, sandbox, approvals, ││ undo │└────────────────┬─────────────────┘ ▼ Postgres 17 event log Weaviate local search Langfuse traces Bugsink errors| Part | What it does |
|---|---|
| Workspace | Next.js 16 app: every screen, the API, the one login gate, the MCP server and the REST API. Renders and calls; holds no business rules |
| eve (0.70.2) | The one runtime. Runs sessions and the model’s loop, keeps held approvals durable across restarts, fires the minute clock for schedules. Listens on loopback only |
| Kernel | Plain TypeScript, no AI framework. decide() rules on every tool call; decideResult() on every result. Approvals, folder confinement, undo, the autonomy ladder |
| Datagate | The kernel’s privacy gate: gitleaks token rules, Zyx’s own personal-data rules, and a local GLiNER name check on web calls |
| Postgres 17 | The one store, in Docker on loopback. One event log is the source of truth: a restart rebuilds every chat and job from it |
| Weaviate + bge-m3 | Local hybrid search (keyword and meaning). Embeddings by bge-m3 through Ollama on the server |
| Docker sandbox | One per session. Every shell command runs here, with no credential and nothing of the server |
| Langfuse | Self-hosted traces, cost, scores and evals |
| Bugsink | Self-hosted error tracker, fed in the Sentry protocol by a small sender, plus an optional heartbeat ping |
| MCP client and server | The official MCP TypeScript SDK. Client toward connected apps; server toward AI tools |
| agent-browser | The one browser: a session per chat, logins per person, a live view with takeover |
Design choices
Section titled “Design choices”- One runtime for every model. A change of model or provider changes where the loop runs, never what governs it.
- Human-gated changes, fail-closed. Unknown means hold.
- No business process in code. How work is done is a
SKILL.mdthe operator can read and edit. - No workflow engine. A job is a fold over rows in the event log, so a restart loses at most the model turn in flight, never a chat, a card or a file.
- Build only what makes Zyx different. The safety kernel, the rights model and the skills are Zyx’s own. Runtime, search, tracing and error tracking are proven open tools.
How it is run
Section titled “How it is run”- One server, one company. A service manager (launchd on macOS, systemd on Linux) keeps Zyx running and restarts it after a crash.
- Updates build the new version beside the running one, check it with Zyx’s own health check, and switch only when it is green. If the new version does not start, Zyx switches back. The previous version stays for a one-click roll back, unless the operator chooses at the terminal not to keep it.
- The health check (“doctor”) reports the database, the schema, backups, the secrets file and more, on a screen or in a terminal.
- Before any change is pushed, a local check runs lint, type checks, layer rules, a build and the test suite. The layer rules fail the build if the kernel imports the runtime, the AI SDK, the web framework or the database driver.