Home  /  Apps  /  Virtual secretary

App

Your own AI secretary, running on your own computer

Reads your email, replies to people you know, says no politely to people you don't, emails you a summary at end of day. The AI runs locally. Nothing leaves your machine except to talk to your mail provider.

Install

0. Pick which Gmail the secretary will use

Recommended: create a new dedicated Gmail account (e.g. yourname-secretary@gmail.com) at accounts.google.com/signup, then forward your personal mail to it. The secretary works entirely through this mailbox — your original inbox, contacts, and calendar stay out of reach.

Your existing Gmail works too, but the secretary then has full access to everything in it. A dedicated mailbox is simply zero-trust thinking taken one step further: most apps assume your computer is safe — Enclawed doesn't, so even a compromised machine can't reach your real accounts.

1. Get a Google app password

Open myaccount.google.com/apppasswords in your browser. In the App name box type Enclawed Secretary. Click Create. Google shows you a 16-letter password in a yellow box — copy it.

If Google says "the setting you are looking for is not available," turn on 2-Step Verification first — Google guides you through it in about two minutes. Works on Gmail, iCloud, Fastmail, Yahoo, Proton. Microsoft 365 / Outlook / Hotmail do not work.

2. Open a terminal and paste the install command

On Windows: press the Windows key, type PowerShell, press Enter.
On macOS: press Cmd + Space, type Terminal, press Enter.

A black window opens. Click inside it, copy the matching command below, paste it into the window, press Enter.

macOS / Linux / WSL Copy

bash <(curl -fsSL https://www.enclawed.com/enclawed-apps/install.sh) secretary

Windows (PowerShell) Copy

irm https://www.enclawed.com/enclawed-apps/install.ps1 | iex; Install-EnclawedApp secretary

The installer downloads Node, Ollama, and the AI model. About 15 minutes, about 25 GB of disk.

3. Answer the prompts

The installer asks you, in order:

1. Your email address.
2. The 16-letter password from step 1.
3. What the secretary should be called (default: Secretary).
4. An optional one-sentence persona (e.g. "Cheerful, decisive, never apologetic."). Press Enter to skip.
5. How it should ask you for approval — popup (easiest), email, auto-detect, or terminal. Press Enter to pick popup.

That's it. The secretary is now running in the background. It will start by itself every time you log in.

For the fellow nerds

Everything below assumes you want the deep version: how the agent stays secure, what protocols it speaks, which tools it admits, how the audit chain works, every command to manage the running service, and the troubleshooting catalog. None of it is required to use the secretary — the install flow above is self-contained.

Hardware requirements

The default Ollama model is qwen2.5:32b-instruct at Q4_K_M — about 19 GB on disk, about 21 GB in memory at runtime. That model is the realistic floor for the secretary's tool-call + multi-step reply discipline to work reliably (tool calls actually fire, dates resolve correctly, reply branches don't blend, the deferral / placeholder / hedge-filler quality guards rarely trigger). What you need to run it smoothly:

All tiers: 25 GB free disk for model weights + cache. Below the Workable line, set ENCLAWED_SECRETARY_DRAFT_MODE=review and --hitl-channel=email so every outbound write asks before executing.

Smaller models, if you have to

The model size affects only the LLM accuracy, not the runtime guardrails. You can drop to a smaller model by editing the llm.model field in app.config.json:

• 14 B (qwen2.5:14b-instruct, ~9 GB) — works. Slight drop in reply quality vs. 32 B; tool selection is still correct in the majority of cases. The deferral / placeholder / hedge-filler quality guards will trigger more often than at 32 B but generally recover on the one retry.
• 7–8 B (llama3.1:8b, qwen2.5:7b-instruct, ~5 GB) — will compose readable English, but routinely ignores calendar tools when it should call them, hallucinates dates, and the quality guards trigger frequently. Acceptable for "auto-refuse strangers + EOD summary only" deployments; not recommended if you want actual calendar bookings to land correctly.
• 70 B+ (llama3.3:70b, ~40 GB) — behaves like a frontier hosted model, at the cost of two 24 GB GPUs or a Mac Studio with 64 GB+ unified memory.

GPU acceleration probe

The installer probes Ollama right after the model pull and reports whether it landed on the GPU or fell back to CPU. You will see one of these lines near the end of the install run:

• ✓ Ollama is using the GPU for inference (100% GPU). — you are good; expect first-reply latency under a second.
• ! Ollama is using CPU only (100% CPU) — inference will be 10–50× slower. — the install continues, but replies will take ~1–2 minutes each. The installer prints platform-specific remediation hints (NVIDIA driver update, ROCm install, WSL2 bridge install, etc.).
• ✓ Ollama processor split: X% GPU, Y% CPU — the model is partially on GPU because your VRAM cannot fit the whole thing. Acceptable; first-reply latency will be a few seconds. Drop to a smaller model (see above) if you want fully-GPU.

If the probe itself failed (e.g. Ollama daemon down at probe time), the installer prints the exact command to re-check manually: ollama run <model> 'hi' && ollama ps. The PROCESSOR column on the second command tells you which backend it loaded on.

Re-running the installer

The installer is idempotent. Re-running the one-liner against an existing install does not wipe your credentials, audit log, or service registration — it picks up where the last run left off. Every step is a no-op when already done: pnpm install reuses the lockfile, the Ollama install short-circuits when present, the app-password prompt is skipped if the OS-keyring entry exists, and the scheduled task / launchd agent / systemd unit is replaced in place. The audit hash chain stays unbroken across upgrades.

If you want a clean wipe-and-reinstall, run the --uninstall command from the Stopping section below first.

What it talks to

The secretary's egress allowlist is closed. Every other host is denied at the dispatch layer; the audit log records the deny. There are exactly five outbound destinations — four IETF-protocol endpoints (one per service) and one loopback address:

All four external endpoints authenticate with the same 16‑letter app password — OAuth is not on the wire. The closed tool surface inside each bridge is narrower than the protocol's full API. From the provider block of enclawed-apps/secretary/app.config.json on through mcp-attested's admission gate, only these tools admit:

• mcp-imap-smtp: search_threads, get_thread, create_draft, send_draft, modify_thread_labels, mark_thread_seen, get_attachment. Notably absent: delete_message, every other IMAP command.
• mcp-caldav: list_events, get_event, create_event, update_event, delete_event. Full CRUD; every mutation is routed through the bicriterion broker with cap=publish and gated on HITL before it touches the calendar.
• mcp-carddav: search_contacts, list_contacts, add_contact. Read + minimal write (vCard PUT) for the "save this person to my contacts" path; broker-gated.
• Web tools (in-process, not MCP bridges): web_search (DuckDuckGo HTML default, Brave with API key when present), read_url (via r.jina.ai reverse proxy), read_attachment (pdfjs-dist + UTF-8 / Latin-1 text), schedule_followup (persisted reminder store + daily-loop dispatcher).

The provider is host-agnostic by design. Pointing the secretary at Fastmail, iCloud, Yahoo, Proton via Bridge, or a self-hosted Dovecot + Radicale is a one-line config change — nothing in the runtime code is Gmail-specific.

Supported mail providers

The current imap-caldav-carddav provider authenticates over IMAP / SMTP / CalDAV / CardDAV with a single 16-letter app-specific password. Every consumer mail host that still accepts that kind of authentication works out of the box:

If your mail lives on a provider that’s not in this table and accepts IMAP+SMTP basic auth (rare in 2026, but possible), point provider.imap, provider.smtp, provider.caldav, and provider.carddav in app.config.json at their endpoints and try it. The runtime is provider-agnostic; only the credential-acquisition flow is specialised to Google’s app-passwords URL today.

If you want Outlook / Hotmail support specifically, the cleanest path is to forward your inbox into a Gmail or iCloud account that the secretary already handles. That keeps the existing app-password auth intact while letting your existing Microsoft inbox flow in.

Troubleshooting

What to do when the install does not get you to a running secretary on the first try. Each entry below names the exact symptom so you can search this page for the message you see.

Test-EnclawedApp secretary

How it stays secure

In plain English: the secretary cannot lie to you about what it did, cannot be tricked by a strange email into doing something it isn't supposed to, and cannot send mail to the wrong person. Five rules enforce this, called F1 through F5 in the technical paper:

Managing the running secretary

Five operations — status, probe, stop, start, uninstall — symmetric across all three platforms. Status / probe / stop / start keep your credentials and audit log intact; only uninstall wipes everything (service registration, env file, audit log, OS-keyring entry).

Windows (PowerShell)

The PowerShell functions are sourced into the current session by the install one-liner. If you closed the window since installing, re-source them once:

irm https://www.enclawed.com/enclawed-apps/install.ps1 | iex

Get-EnclawedAppStatus secretary

Test-EnclawedApp secretary

Stop-EnclawedApp secretary

Start-EnclawedApp secretary

macOS · Linux · WSL (Node CLI)

The installer’s flag interface is the single entry point on Unix. The full path to the installer is printed at the end of the install run; ~/.enclawed/enclawed-oss/enclawed-apps/install.mjs is the default location.

node ~/.enclawed/enclawed-oss/enclawed-apps/install.mjs secretary --status

node ~/.enclawed/enclawed-oss/enclawed-apps/install.mjs secretary --probe

node ~/.enclawed/enclawed-oss/enclawed-apps/install.mjs secretary --stop

node ~/.enclawed/enclawed-oss/enclawed-apps/install.mjs secretary --start

What status reports

The status output answers “is the secretary actually running?” with four lines:

• Service state — loaded / running / not loaded / pid, read from launchctl list on macOS, systemctl --user is-active on Linux, or Get-ScheduledTask on Windows.
• Env file — whether ~/.enclawed/enclawed-apps/secretary/.env exists.
• Keyring entry — whether the OS keyring still has the app password under the right service+account pair.
• Audit log — record count, and a tail of the last few service-log lines so you can see whatever the runtime printed last.

If you suspect the agent is not running, status is the first command to reach for. A missing service, an empty audit log after a day of activity, or a service-log tail with an error message all answer the question without guesswork.

What probe reports

Probe answers a different question: “are the bridges actually reaching Gmail / Calendar / Contacts?”. It loads each of the three bridges with the credentials currently in your .env + keyring and runs ONE live tool call against each, printing either:

• ✓ Connected. INBOX sample returned N thread(s). — plus the subject of each. Proves IMAP+SMTP auth works and Gmail responds.
• ✓ Connected. Default window returned N event(s). — plus summary, start, end of each. Proves CalDAV auth works and Google Calendar responds.
• ✓ Connected. Primary address book has at least N contact(s). — plus name + email of each. Proves CardDAV auth works AND that emails are being extracted (the most common silent-failure mode is contacts found but emails dropped due to a vCard format edge case).
• ✗ Bridge returned error: <reason> — the wire-level error from the server. Definitive signal about which bridge is broken and why.

If the secretary is replying to known contacts with the refusal message, the probe is the right command to run — an empty CardDAV result or an email-less contact entry will jump out immediately.

Uninstall (wipes state)

The --uninstall path on the installer does all four things in one call: stop the service, unregister it from the OS, delete the OS-keyring entry holding the app password, and delete ~/.enclawed/enclawed-apps/secretary/ (which includes the audit log).

Run:

bash <(curl -fsSL https://www.enclawed.com/enclawed-apps/install.sh) secretary --uninstall

irm https://www.enclawed.com/enclawed-apps/install.ps1 | iex; Install-EnclawedApp secretary --uninstall

The --uninstall command above also deletes the app password from your OS keyring. To fully invalidate it on Google’s side, visit myaccount.google.com/apppasswords and delete the Enclawed Secretary entry from the list.

Structural guardrails (full list)

Hard guardrails sit on top of the model so small-model failure shapes don't reach the principal. These are policy code, not prompt instructions — the LLM cannot weasel past them by phrasing things differently.

• Two-stage reply composition. Stage 1 (tool-use loop) only dispatches actions; the reply text is composed in Stage 2 with NO tools and an explicit "Actions executed (you may acknowledge ONLY these)" block. The model cannot claim "I added it to your calendar" unless a calendar tool call returned ok=true in this turn's tool-result trail.
• Deterministic date extraction. chrono-node pre-parses every date/time reference in the inbound email and injects the parsed ISO timestamps into the Stage-1 prompt as a "copy from here, do NOT recompute" block. The model is no longer doing calendar math — just picking from a list. A post-dispatch validator rejects any tool call whose startsAtIso doesn't match the chrono candidates (or their date×time cross-product) and surfaces the rejection as a synthetic tool-error the model can recover from on the next iteration.
• Server-side write verification. create_event does GET after PUT against the CalDAV endpoint and refuses to report success unless the event reads back with the expected SHA-256 of (summary, start, end, attendees). Catches the silent-persistence-failure shape that would otherwise leave the principal with a polite "I scheduled it" reply and an empty calendar.
• Per-thread tool-call cache. If the LLM re-issues the same web_search / read_url / read_attachment within a thread, the dispatcher returns the cached result without re-fetching. Keyed on the deterministic signature name:JSON.stringify(args); lives in the SecretaryRuntimeState in-memory map for the lifetime of the process. Irreversible writes are deliberately not cached — the broker must always be re-consulted.
• NEW-MESSAGE / QUOTED-HISTORY body splitter. The inbound body is parsed into the principal's new message vs. the inline-quoted prior thread (handles Gmail's >-prefix blocks, Apple Mail "On <date>, <name> wrote:" attributions, Outlook underscore separators + header blocks, the mobile bare-date pattern). The Stage-1 prompt explicitly tells the model to respond to NEW only.
• Stage-2 quality retry. The composed reply is checked against three failure shapes: placeholder syntax ([insert X], <TBD>, "would go here", curly/dollar templates), deferral phrasing ("I'll follow up", "let me check", "circle back"), and vague hedge filler ("typical summer temperatures", "a mix of conditions", "based on available sources", "though specific details were limited"). A hit triggers one retry with both negatives spelled out in the system prompt; on a second hit the original goes through and the log flags stage-2 quality retry still contains the issue for triage.
• Deferral-and-no-follow-up enforcement. The Stage-1 system prompt has a hard rule: there is NO asynchronous follow-up mechanism unless schedule_followup was actually called this turn, so deferral language ("I'll follow up", "let me look into that") is forbidden in replies. The Stage-2 guard above is the enforcement.
• Framework DLP scanner (src/enclawed/dlp-scanner.ts) runs in both directions. Outbound drafts are scanned for the secrets / PII / classification-marker patterns (AWS / GCP / OpenAI / Anthropic / GitHub / Slack / Stripe key shapes; PEM private keys; credit-card / IBAN / SSN shapes; classification banners; distribution caveats). Inbound search snippets and r.jina.ai-fetched page bodies are scanned for the prompt-injection cluster (chat-template markers like <|im_start|> / [INST] / <|system|> from ChatML / Llama / Mistral / OpenAI formats; role-takeover prefixes like "system:" at line start; "ignore previous instructions" / "disregard above" / "forget all" variants; jailbreak markers like "DAN mode" and "do anything now"); critical hits are redacted with [REDACTED] before the LLM sees them.
• Bicriterion broker with HITL email channel. Every irreversible action (calendar write, contact add, email send) is classified by an explicit two-axis policy (severity from the DLP scan + origin from the sender identity). Auto-approves for principal-authored intent on routine ops; emails the principal for approval on anything ambiguous; refuses outright on critical DLP. The email-HITL prompt sends a request mail with a fresh correlation token, polls for the principal's reply, and resolves to approve/deny based on the first non-quoted line (YES/Y/approve = approve, NO/N/deny = deny, anything else within timeout = deny). Reminder mail fires at the 5-minute mark; timeout-confirmation mail fires at the deadline so the principal sees the lifecycle in one thread.
• Context-window management. Ollama defaults to num_ctx=2048, which truncates long threads. The secretary explicitly sets num_ctx=32768 and tracks message-array size; when Stage-1 crosses 80% of the budget, older iterations are collapsed into a deterministic textual "you already ran X and got Y" receipt that preserves the information without burning a second inference for summarization.
• Per-thread fresh context. Each thread starts with a brand-new messages array. The Ollama /api/chat endpoint is stateless — the model only sees what's in the current request — so processing thread B has zero context from thread A. The only cross-thread state is the persistent surface (calendar, contacts, audit log), and that's only accessed through broker-gated tool calls.

Egress allowlist (closed)

Every external destination the secretary touches is on a closed allowlist; every other host is denied at the dispatch layer and the deny is written to the audit log. The complete list:

Tool surface (closed list)

From the provider block of app.config.json through mcp-attested's admission gate, the secretary's bridges admit only the tools below. Everything else the underlying protocol could expose is closed at the registry.

• mcp-imap-smtp — search_threads, get_thread, create_draft, send_draft, modify_thread_labels, mark_thread_seen, get_attachment. Notably absent: delete_message and every other IMAP verb.
• mcp-caldav — list_events, get_event, create_event, update_event, delete_event. Full CRUD; every mutation goes through the bicriterion broker with cap=publish and is HITL-gated before it touches the calendar.
• mcp-carddav — search_contacts, list_contacts, add_contact. The write path is the minimum vCard 3.0 (FN + EMAIL + optional NOTE) that every major address-book server accepts; broker-gated.
• In-process web tools (not MCP bridges) — web_search (DuckDuckGo HTML default, Brave with API key when present), read_url (via r.jina.ai), read_attachment (pdfjs-dist legacy ESM build for PDF, UTF-8 with Latin-1 fallback for text/*), schedule_followup (append-only JSONL store at ~/.enclawed/enclawed-apps/secretary/followups.jsonl + daily-loop dispatcher).

Audit chain

The audit log at ~/.enclawed/enclawed-apps/secretary/audit.jsonl is the canonical record of what happened. Properties enforced by src/enclawed/audit-log.ts:

• One record per call. Every dispatch through the framework's SkillGate writes exactly one record: type ("irreversible.proposed" / "irreversible.executed" / "irreversible.denied" / "fs_read.executed" / "egress.deny" / ...), actor, ts, level, payload, prevHash, recordHash.
• Hash chain. recordHash = SHA-256(prevHash || "|" || canonicalize(record)), where canonicalize is deterministic JSON. Tampering with any record breaks the chain at that record. The EOD summary projector recomputes the chain on every run and the secretary refuses to send the digest until verifyChain returns clean.
• Windowed projection. projectAuditCounts takes an optional sinceMs lower bound so the EOD reconciliation (in-memory state vs. on-disk record) compares the same window and isn't tripped by restart-skew.
• Egress denies are records. If the model coerces the runtime into trying to reach a non-allowlisted host, the egress guard's onDeny hook writes an egress.deny record before throwing. There is no silent egress.

Identities + secrets at rest

Every operator-identity address (the mailbox the secretary signs in as, the human principal it acts on behalf of, every alias the operator considers principal-equivalent) lives in a single OS-keyring entry called secretary-identities — a JSON blob {mailbox, principal, aliases} encrypted at rest under macOS Keychain / Windows Credential Manager / Linux Secret Service. The .env file on disk holds only non-PII configuration (timezone, poll interval, flavor, hitl channel, persona). The app-specific password and the optional Brave Search API key live under separate keyring accounts keyed by mailbox. The launcher fetches the identities blob FIRST at start, parses it, sets the env vars in memory only, and then fetches the per-mailbox secrets — in-memory only, never written to disk, never visible in argv, never in a log line.

F1–F5 in detail

The five properties under How it stays secure are short summaries. The technical paper at arxiv.org/abs/2605.24248 formalises each one with the threat-model assumptions, the runtime invariants, and the audit-chain compositions. The enforcement code:

• F1 (Gate bypass) — the SkillGate is the single entrypoint for every external call. Every bridge dispatches through it; there is no fetch in the secretary's code path that doesn't go through the egress guard's wrapped globalThis.fetch. In enclaved flavor the guard freezes the wrapper after bootstrap so module code cannot reassign it.
• F2 (Audit forgery) — the hash chain above. The chain-hash short tag is included in the EOD summary so the principal can verify externally.
• F3 (Silent failure) — create_event does GET-after-PUT; send_draft verifies the appended draft's content-SHA matches the expected hash; add_contact checks the createVCard response for the Location header. Every bridge's ok=true path is conditional on an end-to-end echo of the requested mutation.
• F4 (Wrong target) — outbound writes bind the call to a hash of (cap, target, args). The broker's target patterns (gmail:send/<draftId>#sha256=<hash>;to=<recipient>, calendar:event/<uid>#sha256=<hash>, etc.) include the recipient in the target string. A target-recipient mismatch on the echo refuses the call.
• F5 (Wrong content) — the DLP scanner runs on every outbound body. Critical findings hard-deny via the broker. The same scanner runs on inbound search results and fetched page bodies to neutralize prompt-injection primitives before the LLM sees them.

Source, framework, extensibility

• Source. The secretary lives at enclawed-apps/secretary/ in the enclawed-oss tree. Meant to be readable end-to-end as the canonical example of building an enclawed application.
• Installer template. The installer is generic. Any future app with an app.config.json uses the same one-line install. Only the per-provider authorisation flow is provider-typed; today the only provider is imap-caldav-carddav (works against Gmail, Fastmail, iCloud, Yahoo, Proton via Bridge, or any self-hosted IMAP+CalDAV+CardDAV stack with one app-password). GitHub, Slack, and others are planned.
• Framework SDK. The enclawed/framework subpath the secretary imports is the same SDK any third party uses to build their own enclawed-backed application. Capability primitives (CAPABILITY, makeCall, SkillGate), broker shapes (BrokerRequest, BrokerDecision), DLP entry points (dlpScan, dlpRedact), and bridge loaders (loadImapSmtpBridge, loadCalDavBridge, loadCardDavBridge) are all exported.
• Paper. arxiv.org/abs/2605.24248 — "Architectural obsolescence in agentic-AI runtimes" formalises the threat model and the F1–F5 properties the secretary realizes.