--- language: "en" title: "Operations" canonical: "https://akno.tenphi.me/operations/" source: "docs/operations.md" version: "0.18.16" index: true --- # Operations Akno can run for one command at a time or as a long-lived macOS or Linux user service. The service is the normal agent integration: it keeps the index warm, watches the knowledge base, owns the single write handle, and exposes the same operation registry through several transports. ## Run in process ```bash akno index akno recall "Zephyr QX-100 warranty" ``` Without a service, most CLI commands open Akno in the current process. With a service, commands that need the writer are forwarded to it. `--connect` requires a live service and disables the in-process fallback. Akno verifies the service handshake against the resolved knowledge-base path before forwarding anything. A command with `--akno-path`, `--state-dir`, `AKNO_CONFIG`, `AKNO_PATH`, or `AKNO_STATE_DIR` therefore cannot silently use a conventional socket owned by another memory. If the requested memory has its own service, pass the matching state directory; otherwise stop that service or let the command run in process. An invalid explicit config remains a configuration error even when another Akno service is available. For foreground integrations: ```bash akno serve akno serve --mcp akno serve --http 127.0.0.1:7777 ``` * The Unix socket is the default local door. Owner-only filesystem permissions are its authentication. * MCP is a stdio adapter for agent hosts. `server.mcp_allow` controls which operations the agent receives, including when the adapter forwards through an already-running service. `--allow` can narrow that policy; it cannot widen it. * HTTP is for a containerized or remote agent that cannot open the host socket. Unauthenticated loopback callers receive only `server.http_public_allow`, which may narrow but cannot widen the read-only public surface. A non-loopback bind requires at least one resolved bearer identity in `server.http_access`; each credential owns its actor and allowlist. For authenticated HTTP, keep the credential in the environment and only name it in config: ```jsonc { "server": { "http": "0.0.0.0:7777", "http_access": [ { "name": "vulpine-agent", "token": { "env": "AKNO_HTTP_AGENT_TOKEN" }, "actor": "agent", "allow": ["recall", "answer", "read"], }, ], }, } ``` The typed client passes that credential with `connect({ http, token })`. HTTP rejects `x-akno-actor` and client actor overrides, because identity is assigned by the server credential. The built-in listener is plain HTTP; put a non-loopback deployment behind a trusted tunnel or TLS reverse proxy so the bearer token is encrypted in transit, and restrict access from that proxy to Akno. ## Install the background service ```bash akno service install --no-dream akno service install akno service install --dream-hour 2 akno service status akno service uninstall ``` `service install` writes background user-service definitions: | Unit / label | Behavior | | ----------------------- | -------------------------------------------------------------------------- | | `dev.akno` | KeepAlive service for the index, watcher, models, socket, and write handle | | `dev.akno.dream` | One due nightly pass; default 03:00 local time, with missed-login catch-up | | `dev.akno.dream-health` | Checks for a missed cycle after a two-hour grace window | On macOS these are launchd agents. On Linux they are systemd user service/timer units under `$XDG_CONFIG_HOME/systemd/user` (or `~/.config/systemd/user`). Installation reloads the user manager, enables the nightly timers, starts or restarts the main service, and waits until its socket accepts connections. `--no-dream` disables and removes any previously installed timers. The generated commands retain explicit `--akno-path` and `--state-dir` targets. The scheduled command resolves `maintenance.profile` and policies at run time. Changing authority therefore does not require reinstalling the schedule. Re-run installation after an Akno upgrade when release notes say the launchd or systemd definition changed. On macOS the dream agent runs both at its calendar time and when launchd loads it. The internal `--scheduled --if-due` guard starts work only when the current expected window has no full-cycle receipt, so a login or reboot after 03:00 catches up without duplicating an on-time, running, or already-failed attempt. Linux systemd timers use `Persistent=true` for the equivalent catch-up. This is one nightly window, not a retry queue: a recorded failed attempt remains visible for review and is not silently rerun. During the initial planner wave, the service holds one index revision. Watcher and explicit index passes that reach the shared indexer are queued, not discarded, then drained before curator decisions and apply. Filesystem edits themselves remain available and are handled by stale-input and whole-tree verification after the barrier. A foreground memory mutation instead takes priority: its structural index completes immediately, invalidates the planner revision, and makes the dream stop before curator decisions or writes. Post-response model derivation may finish later without delaying the foreground result. `service uninstall` stops and removes Akno's launchd or systemd user definitions, then reloads the relevant user manager. It does not remove the knowledge base or state directory. ## Nightly status and notifications ```bash akno dream status akno dream status --last 10 akno dream status --run akno dream status --pending akno plan list --status awaiting_review akno plan prune ``` Status includes the next expected schedule, recent durable runs, policy, typed model degradation, decisions, item verification, final run verification, and budget use. Final verification rechecks each path's last applied sealed disk/index outcome, surviving paths of earlier managed-item repairs, budget and model accounting, and the complete indexable knowledge-base diff. An unrelated concurrent add, edit, or removal is preserved but fails certification as an aggregate `unattributed_file_change`; paths never enter the run receipt. Inspect exact private planned changes only with `akno plan diff `. Schedule health and launch-time catch-up use the latest non-dry-run full cycle. A later `--dry-run` remains visible in run history but cannot replace a healthy nightly result with a diagnostic failure. Use `--mode audit` when you want a durable, realistic no-write maintenance cycle that does count as a full attempt. If a newer run makes queued work obsolete, retire the old plan without touching the knowledge base: ```bash akno plan supersede --reason "Replaced by a newer review." ``` Only work that has not begun applying can be superseded. Interrupted apply and verification states stay in the queue so recovery cannot be hidden as cleanup. For an automated review client, make response-loss retries explicit: ```bash akno plan decide --item --approve \ --idempotency-key review:PLAN_ID:ITEM_ID:approve akno plan apply --idempotency-key apply:PLAN_ID ``` The key is bound to the exact request and survives service restarts. An exact retry is a no-op; reuse for a different decision or action is rejected as a conflict. Completed apply retries report `replayed: true` and no new file changes. `akno plan prune` is a content-safe preview of the configured two-stage retention boundary, including exact private bytes eligible for removal. Add `--apply` for an immediate manual pass. Every writable dream run also enforces the same policy: terminal exact operations/evidence expire before compact audit receipts, while active or recovery-relevant plans are retained without an age limit. This state cleanup never touches Markdown or the separate change journal. Writable dream runs also enforce retained-source evidence lifetime. Exact private frames from active support are never age-pruned. After a retraction or explicit forget, a frame becomes eligible only when the configured grace has elapsed and no nonterminal maintenance item names its managed memory. Cleanup securely removes the quote and checkpoints the local database while preserving replay hashes, compact receipts, and page/document source bindings. Dream output reports only counts and removed byte totals. Local notifications are off by default: ```jsonc { "maintenance": { "notifications": "actionable" }, } ``` `actionable` reports review backlog, failures, incomplete verification, exhausted budgets, repeated typed degradation, and missed schedules. `all` also reports healthy scheduled completion. macOS uses a local user notification; Linux writes to the local system log with `logger`, which is suitable for headless servers and journald-backed systems. If that command is absent, delivery reports a typed `backend_missing` outcome rather than silently succeeding. Notifications contain counts, states, timestamps, and run ids—not note text, paths, diffs, prompts, model output, or provider errors. ## Diagnostics Run these before changing configuration or deleting state: ```bash akno doctor akno doctor --no-probe akno doctor --no-probe --admission-preview akno doctor --no-probe --quarantine-details akno doctor --refresh-api akno config akno rules akno rules products/zephyr-qx-100.md akno service status ``` `doctor` reports: * knowledge-base and state locations; * whether this process can acquire the writer; * page, chunk, fact, event, document, and broken-link counts; * admitted, explicit read-only, and implicit read-only fact-injection counts; the opt-in admission preview adds top-level folder globs and authority-preserving `remember: deny` patches without page identities or content; * content-safe Markdown quarantine counts by reason; `--quarantine-details` explicitly adds private relative paths and known stable ids, but never source bodies; * storage-only lookup latency; * model-role availability, schema probes, latency, and the cost of each missing role; * extraction support; and * reserved-path collisions. Probe failures are operational evidence, not a reason to erase the index. Use `--no-probe` for an immediate configuration-and-index report without network model calls. `--refresh-api` ignores cached `api: auto` selections and repeats only the invented transport probes; it cannot be combined with `--no-probe`. Repairing the source files and running `akno index` is the complete Markdown-quarantine resolution path; there is no second conflict workflow to approve or synchronize. `config` shows every loaded source and the resolved configuration. API keys, authorization headers, passwords, tokens, and similarly named future secret fields are redacted recursively. `rules` explains effective path and maintenance policy, including why a transformation is off, audit-only, reviewable, or potentially automatic. ## State and recovery The default installed state lives under `~/.akno` on macOS and `$XDG_STATE_HOME/akno` on Linux (with the XDG fallback `~/.local/state/akno`); `state_dir` can move it. Its important contents are: ```text / akno.db derived index, journal, gates, plans, and run receipts akno.sock local service socket on macOS, Linux fallback, or an explicit state_dir akno.lock current writer metadata provider-capabilities.json content-free api:auto selections trash/ recoverable forgotten files logs/ service and scheduled-cycle logs ``` Recovery depends on what is wrong: | Symptom | First action | | -------------------------------------------- | -------------------------------------------------------------- | | Search is stale or derived state looks wrong | Run `akno index`, or `akno index --rebuild` for a full refresh | | A journalled write was wrong | Run `akno undo ` | | A page or document was forgotten | Undo it or recover it from `trash/` within retention | | A maintenance item is unclear | Inspect `dream status` and `plan diff` before applying | | A plan has the right scope but wrong result | Correct it with `plan revise`; then review it again | | Automatic apply is paused | Inspect status/plans, then use the displayed resume command | | Models changed behavior | Run `doctor`, then the relevant benchmark | | Service seems stale after a checkout edit | Run `pnpm akno redeploy` | Do not delete `akno.db` merely to refresh search: it also contains undo history, gated writes, retained-source receipts, maintenance plans, recovery state, and run receipts. `akno index --rebuild` re-hashes every file and recomputes reproducible page, chunk, embedding, derivation, and graph projections in place. It is safe through the running service and preserves every durable record. Database schema upgrades and new read projections are automatic and never rewrite Markdown. The intent-aware memory upgrade adds derived semantic rows and changes chunk boundaries around managed items, so its first full index pass re-reads pages and refreshes affected embeddings and graph edges. `akno migrate` is not needed unless the release notes separately name a Markdown marker migration. Akno's trash and journal are not backups. Keep the Markdown knowledge base under normal backup or version control. ### Automatic-apply recovery `akno dream status` reports durable recovery state separately from configured authority. Akno pauses the whole automatic profile when final verification cannot prove its live bytes, sealed plan, or journal receipt. Three distinct automatically rolled-back items of one transformation pause only that class; unrelated maintenance continues. A verified later attempt clears a pre-threshold streak, but a pause never silently clears itself. After inspecting the referenced run and private plan details, resume explicitly: ```bash akno dream resume --profile akno dream resume --transform merge ``` Resume clears the selected safety state; it does not alter configuration, approve a plan, or apply anything. Audit and review runs remain available while the autonomous profile is paused. Transient request retries stay bounded inside the model client, while ordinary nightly cadence supplies the later retry for model outages and fresh run budgets—Akno does not create a hidden multi-day retry schedule. ## Updating a checkout ```bash pnpm typecheck pnpm lint pnpm test pnpm akno redeploy ``` `redeploy` builds packages, continues in a fresh CLI process, restarts the launchd or systemd user service, and waits until the replacement socket is ready. It uses a 30-second fast readiness window and, when the platform service manager confirms that the replacement is still running, a bounded three-minute live-handoff window. `--timeout ` replaces both with an explicit hard deadline. Building matters: the service imports the compiled core package, and hosts import compiled core or client packages, so restarting without a build can silently keep old behavior. The fresh process ensures the restart itself resolves config and package exports from the artifacts that were just built. Use `pnpm akno redeploy --no-restart` for a checkout without an installed service, or `--no-build` only when no compiled package changed. ## Privacy boundaries Akno sends only the content needed by an invoked model role to the configured endpoint. A lexical-only setup sends nothing to a model. `doctor` uses invented probe text; opt-in live benchmarks use their own invented corpora rather than the configured knowledge base. Operational output is content-safe by default. Commands that deliberately display memory—such as `recall`, `read`, `answer`, and `plan diff`—are private-content surfaces and should not be copied into public logs or bug reports without inspection. The owner controls both the files and service. Akno currently has no per-user authorization, tenancy, or untrusted collaborative-write model. ## Platform Akno's core and CLI packages support macOS and Linux with Node 22.18 or newer. The protocol and client packages remain portable and do not carry Akno's native index dependencies. Windows is not a supported core/CLI runtime. | Capability | macOS | Linux | | ------------------------ | --------------------------------------- | ----------------------------------------------------------- | | Markdown indexing | Native | Native | | Config and private state | `~/.akno` | XDG config and state directories | | Default Unix socket | `~/.akno/akno.sock` | `$XDG_RUNTIME_DIR/akno/akno.sock` | | PDF text | PDFKit | Poppler (`pdfinfo`, `pdftotext`) | | PDF and image OCR | Vision | Poppler rasterization plus Tesseract | | Office text | `textutil` | LibreOffice | | Managed user service | launchd | systemd `--user` | | Scheduled notifications | Notification Center through `osascript` | Local system log through `/usr/bin/logger` or `/bin/logger` | If `XDG_RUNTIME_DIR` is absent or not absolute, the Linux socket falls back to the private XDG state directory. The corresponding state fallback is `~/.local/state/akno`, and the config fallback is `~/.config/akno`. On Debian or Ubuntu, install the complete Linux extraction toolchain with: ```bash sudo apt-get install poppler-utils tesseract-ocr libreoffice-writer ``` The tools are discovered independently. Missing LibreOffice affects supported office files; missing Tesseract affects image and scanned-PDF OCR; missing Poppler affects PDF extraction. `doctor` reports the selected backend and each command, while ingestion returns typed missing-dependency or partial-extraction degradation instead of claiming that the document was fully read. A systemd user manager is required only for `akno service`; foreground and in-process operation do not depend on it.