# Hostkeep

> Hostkeep is an MCP (Model Context Protocol) server for Windows machines and VMs. It lets an AI assistant diagnose failed jobs, collect logs and outputs, and run pre-defined tasks without remote desktop. Projects are walled off, access is read-only by default, and every tool call is recorded in a hash-chained activity log. Founder: Fay. Status: early access (October 2026).

Tagline: "Ask your machines what happened last night."

## Summary

- Problem: small technical teams and agencies run unattended workloads (trading and automation bots, scrapers, client servers) on Windows machines and VMs. When something fails, someone must open remote desktop, find logs, read code and check recent changes by hand, machine by machine.
- Product: a small program that runs on each Windows machine as a standard user (no admin rights). AI assistants connect to it over MCP (streamable HTTP, protocol 2025-11-25) with an access token. The assistant works only inside named project folders and only runs commands the owner defined.
- There is no Hostkeep cloud service. Data read by the assistant goes only to the AI provider the user connected.
- Origin: built by the founder for her own Windows trading VM. The earlier private version handled about 4,400 tool calls in one week (24-30 September 2026); 799 of them were unrestricted PowerShell versus 4 fixed tasks, which is why Hostkeep is designed around fixed tasks and human approvals.

## Capabilities

- 63 tools, 38 enabled by default: files and search (list, read, read range, search, glob, stat, hash, compare, write, edit, copy, move, delete), Git (status, diff, log, safe checkpoint), data and documents (CSV, JSONL, read-only SQLite, PDF text, OCR, media info, archives), tests and fixed commands with typed parameters.
- Opt-in families, off by default: isolated analysis jobs, outbound fetch, single-use exports, host processes, desktop automation.
- Every tool carries MCP annotations (read-only, destructive, idempotent, open-world).

## Security model (enforced in code; each claim has a named test)

1. Gate: loopback by default; access token (constant-time compare), host-name allowlist and rate limits are checked before a request body is parsed.
2. Only enabled tool families are advertised.
3. Project containment on Windows: a fixed worker pins every folder by handle and opens each next component relative to the held handle (NtCreateFile with RootDirectory). Stress test: 100,000 operations while folders are swapped for links, zero outside reads or writes, zero residue. Median contained read: 0.57 ms.
4. Read-only by default; per-project write permission; control paths such as .git protected even in writable projects.
5. Fixed commands with typed parameters; option-like values rejected; Git runs with repository-defined hooks and programs disabled.
6. Child processes receive an allow-listed environment without credentials; outbound fetch off by default, HTTPS only, private ranges refused, connects to the vetted address.
7. Content-free, SHA-256 hash-chained activity log; if logging fails, new mutations are refused before they run.

Known gaps (published): no human approval gate yet; running tests on a writable project executes project code; one static access token; listing/search/archive/data tools use an identity-check mitigation rather than the pinned worker.

## Engineering evidence

- 192 automated tests; every fix test-first (failing test recorded before the fix).
- Containment stress suites: 100,000 fast operations and 20,000 paused operations, zero outside access.
- One-hour soak test: 17,766 calls, zero errors, flat memory (258-260 MB). A memory leak of 89 KB per request was found and fixed.
- Process: Claude acts as architect and security reviewer (specs, decisions, review of every diff); coding agents implement against written specs; decisions and evidence are logged.
- Stack: Windows 11, Node.js 22 LTS, MCP SDK v1 (protocol 2025-11-25), Express, zod; native file layer via NT handle APIs in a fixed PowerShell/.NET worker; pinned dependencies.

## Roadmap

- Done: foundations (reproducible builds, CI), stability (leak fix, watchdog, rate limits, soak), hardening (activity log, typed commands, protected paths, handle-pinned containment).
- Next: human approval before changes and tasks run (local approval page, optional phone notification); a separate access key per client; activity viewer.
- Planned: OAuth sign-in so web assistants such as claude.ai and ChatGPT can connect; verified compatibility matrix; installer, setup page, doctor command, signed releases; pilot with 3-5 teams.

## Demo scenarios on the home page (illustrative sessions with real tool names and refusal codes)

1. Diagnose a failure: the assistant searches logs, reads a log range, checks git log and diff, finds a timeout introduced by a recent commit, runs the fixed test task (48 passed). The project is read-only, so it leaves the edit to the owner.
2. Collect outputs: glob, dataset profile, CSV and JSONL queries summarise a scraper run; one summary file is written inside the only writable folder (reports/).
3. A file tries to trick it: a hidden instruction in DEPLOY.md asks the assistant to read another client's .env; the read is refused with PATH_OUTSIDE_ROOT and recorded.
4. Ask for a shell: an arbitrary Remove-Item command is refused (COMMAND_NOT_ALLOWED); host access is off, so no shell tool exists.

## Boundaries (what Hostkeep does NOT do)

- No Hostkeep cloud, no telemetry: the software sends nothing to Hostkeep.
- Does not act on its own: it only answers tool calls from an assistant the owner connected. No autonomous monitoring or alerts yet.
- No shell: arbitrary commands are refused unless the owner enables the separate advanced host module (off by default).
- Never reads or writes outside named project folders, including via links or junctions.
- Needs no administrator rights; listens on 127.0.0.1 only; remote access is through a tunnel the owner runs.
- Includes no AI model and stores or trains on no data; content read by the assistant goes to the assistant's provider.
- No human approval gate yet (next phase). One access token per installation today.
- Windows 11 only today; macOS and Linux are not supported.

## Company

Independent, self-funded project founded in 2026 by Fay. Not affiliated with Anthropic, OpenAI or Microsoft. Contact: fay@hostkeep.tech (early access, security reports, everything else).

## Links

- [Home](https://hostkeep.tech/): product overview, interactive demo, workflows, roadmap
- [What it does and doesn't](https://hostkeep.tech/scope): exact scope, boundaries, audience, data flow, limits, comparison
- [Security model](https://hostkeep.tech/security): trust model, seven walls, claims with code and test references, known gaps
- [About](https://hostkeep.tech/about): story, principles, how it is built (Claude as architect and reviewer), founder
- [Contact](https://hostkeep.tech/contact): early access, security reports, general questions
- [Privacy](https://hostkeep.tech/privacy): no cookies, no analytics, no telemetry; third parties; retention; rights
- [Terms](https://hostkeep.tech/terms): early-access terms, responsibilities, acceptable use, warranty, liability