npm package: @architect-engine/daemon
Description: Architect Engine Daemon — local process execution, workflow engine, connector dispatch
Latest version: 1.0.12

# @architect-engine/daemon

The Architect Engine Daemon — a native background service that gives SDK applications access to OS-level capabilities the browser cannot provide: local process execution, workflow engine, connector dispatch, and real-time database sync.

[![npm version](https://img.shields.io/npm/v/@architect-engine/daemon.svg)](https://www.npmjs.com/package/@architect-engine/daemon)
[![npm downloads](https://img.shields.io/npm/dw/@architect-engine/daemon.svg)](https://www.npmjs.com/package/@architect-engine/daemon)
![Platforms](https://img.shields.io/badge/platforms-macOS%20%7C%20Linux%20%7C%20Windows-blue.svg)
![Binary](https://img.shields.io/badge/binary-native_Rust-orange.svg)

## Install

```bash
npm install -g @architect-engine/daemon
```

The `postinstall` script automatically registers the daemon as a system service (launchd on macOS, systemd on Linux). The daemon starts immediately and restarts automatically at every login — no further configuration needed.

## Commands

```bash
architect-engine status    # Check if daemon is running (pid, port)
architect-engine stop      # Stop the running daemon (service registration preserved)
architect-engine restart   # Restart the daemon
architect-engine install   # Register as system service (auto-start on login)
architect-engine uninstall # Remove system service registration
architect-engine run       # Run daemon directly in the foreground (dev mode)
```

## What the Daemon Provides

| Capability | Description |
|-----------|-------------|
| **Local process execution** | Spawn and manage OS processes on behalf of SDK workflows |
| **Workflow engine** | Multi-step workflow execution with retry, timeout, and failure handling |
| **Connector dispatch** | Route SDK `executeAction()` calls to local processes and external services |
| **Database sync** | Real-time replication between local SQLite and Turso cloud |
| **WebSocket API** | SDK connects via `ws://127.0.0.1:3002` — works from any browser tab or process |
| **Unix Domain Sockets** | Local IPC for managed subprocess orchestration (macOS/Linux only) |

## Supported Platforms

| Platform | Architecture | Binary |
|----------|-------------|--------|
| **macOS** | Apple Silicon (arm64) | `@architect-engine/daemon-darwin-arm64` |
| **macOS** | Intel (x64) | `@architect-engine/daemon-darwin-x64` |
| **Linux** | x64 (musl static) | `@architect-engine/daemon-linux-x64` |
| **Windows** | x64 | `@architect-engine/daemon-win32-x64` |

npm automatically selects the correct platform package via `optionalDependencies`. The `bin/architect-daemon.js` shim resolves the native binary and delegates all args — no platform-specific install steps needed.

## Architecture

The daemon is the OS-capabilities layer of the Architect Engine stack:

```
Your App
  └─ @architect-engine/sdk         TypeScript SDK — all API calls go here
       └─ DaemonAdapter            WebSocket client (ws://127.0.0.1:3002)
            └─ architect-engine    Native Rust binary running as system service
                 └─ bridge crate   Process runner, connector dispatch, UDS IPC
```

**SDK without daemon** — works, but no local process execution or connector dispatch.
**Daemon without SDK** — useless server with nobody to call it.

## What's in the npm Package

The platform package (`@architect-engine/daemon-{platform}`) contains:
- A compiled Rust binary (~24MB) — the complete daemon, zero source code
- The binary cannot be reverse-engineered to Rust source

The wrapper package (`@architect-engine/daemon`) contains:
- `bin/architect-daemon.js` — 40-line Node.js shim that finds and exec's the correct binary
- `scripts/postinstall.js` — registers the system service after `npm install -g`

Zero source code. Zero Rust. Zero database schemas. Zero engine logic.

## Files

| File | Purpose |
|------|---------|
| `package.json` | npm manifest — optionalDependencies selects the correct platform package |
| `bin/architect-daemon.js` | Platform-agnostic shim — resolves native binary and delegates all argv |
| `scripts/postinstall.js` | npm postinstall — runs `architect-engine install` to register system service |

## Dependencies

**Depends on:** `@architect-engine/daemon-{platform}` (optionalDependencies — npm selects correct one at install time)

**Depended on by:** Any machine running apps that call `executeAction()` through `@architect-engine/sdk`