
vps-mcp
io.github.navid72m/vps-mcp
Autonomous Digital Secretary and VPS MCP platform with Executive Web Cockpit
Documentation
VPS-MCP & Digital Secretary
An enterprise-grade Model Context Protocol (MCP) platform and autonomous Executive Digital Secretary that bridges AI models (Claude, Groq, DeepSeek, Qwen, Nemotron) with real-world infrastructure, enterprise databases, Git workflows, knowledge libraries, and personal productivity channels.
The system runs locally on your machine, communicating over secure SSH to remote servers without requiring persistent background daemons on target hosts.
The Executive Web Cockpit running on http://127.0.0.1:8765 with real-time tool execution, live model switching, responsive GFM table rendering, and server telemetry.
Core Platform Pillars
- Executive Web Cockpit & Telegram Assistant (
assistant): A local dark-mode command center (http://127.0.0.1:8765) and always-on Telegram bot with multi-model routing (Groq, DeepSeek, local Qwen via LM Studio, Nemotron), multi-step tool execution loops, GFM Markdown tables, and human-in-the-loop action approval guardrails for sensitive actions. - Remote Infrastructure & Services (16 tools): Zero-footprint management of systemd services and Docker/Podman containers over SSH. Features live telemetry, journalctl log inspection, restart/stop/boot controls, and declarative configuration deployment with syntax diff previews and automatic rollback on health-check failure.
- Database & Migration Rehearsal (13 tools):
Deep PostgreSQL and Odoo schema inspection, database-to-database diffing with automated risk verdict generation (
safe_to_promote,review_warnings,do_not_promote), and deterministic upgrade rehearsals on disposable copy databases. - GitLab CI/CD & Production Deployments (15 tools): Direct integration with self-hosted or cloud GitLab instances. Inspect commits, merge requests, branches, and pipeline jobs; verify deployment targets; and trigger zero-downtime ref rollouts to production with automatic health verification.
- Knowledge Base Dense Semantic RAG (6 tools):
Dedicated vector library for indexing technical books (e.g. Designing Data-Intensive Applications), research papers, and documents using FAISS and SentenceTransformers (
all-MiniLM-L6-v2) with page-level citations. Completely isolated from operator profile memory. - Google Workspace Integration (8 tools):
OAuth 2.0 integration for Google Calendar (
calendar__events,calendar__create) and Gmail (email__inbox,email__send,email__draft), with interactive phone and desktop approval gating for outgoing communications. - Personal Telegram MTProto Client (5 tools): Telethon-powered user client integration for searching personal chats, reading incoming messages, and sending direct messages under approval gating.
- Shared Agent Memory (
agent-memory, 5 tools): Cross-client and cross-project knowledge store holding facts, architectural decisions, procedures, and operator profiles with confidence scores, provenance tracking, and expiration policies. - Modular Lazy Tool Catalog (90+ Tools):
Over 90 tools organized into modular toolsets (
services,db,migration,gitlab,jobs,files,kb,calendar,email,memory,telegram) to keep prompt token counts minimal and prevent LLM rate-limiting.
What It Gives Your Agent
- Structured JSON Answers instead of Fragile Shell Sessions: "Is Odoo healthy?" is a single, typed tool call returning compact telemetry, eliminating raw SSH shell scraping and keeping token usage minimal for smaller models.
- Guaranteed Safety & Human-in-the-Loop Approvals: Sensitive write operations (service restart, file modification, database copy drops, outgoing emails) pause for explicit confirmation via the phone messenger or Web Cockpit.
- Zero-Footprint Server Architecture: Nothing runs permanently on target servers. Only an SSH key, a dedicated unprivileged user, and a minimal sudoers profile are required.
- Deterministic Upgrade Confidence: Run full migration rehearsal pipelines on isolated clone databases before touching production data.
- Multi-Model Flexibility: Switch models on the fly between lightning-fast cloud APIs (Groq
gpt-oss-120b, DeepSeek) and completely private offline local weights (Qwen 2.5 via LM Studio).
Design documents: specs/001-vps-service-mcp/ (services),
specs/002-odoo-migration-analysis/ (migration),
specs/003-declared-jobs/ (jobs),
specs/004-agent-memory/ (memory),
specs/005-gitlab-integration/ (GitLab),
specs/007-assistant-runtime/ (personal assistant),
specs/008-lazy-tool-loading/ (lazy tool loading),
specs/009-knows-me/ (operator profile & recall),
specs/010-web-and-media/ (web, photos, documents),
specs/011-email-and-calendar/ (Google Workspace),
specs/012-personal-telegram/ (personal Telegram account MTProto), and
specs/013-knowledge-base-rag/ (knowledge base RAG).
Contents
- The 90+ Tool Ecosystem
- Requirements
- Quick start
- Connect your MCP client
- Using it
- Service tools
- Migration analysis
- Declared jobs
- GitLab
- Memory
- Personal assistant
- Security model
- Configuration reference
- Troubleshooting
- Development
The 90+ Tool Ecosystem
The platform exposes over 90 specialized tools divided across VPS/GitLab MCP services and Digital Secretary built-ins, orchestrated with token-saving lazy loading:
| Domain | Tools | Primary Tools | Capabilities |
|---|---|---|---|
| VPS Infrastructure & Systemd | 16 | list_services, get_resource_usage, restart_service, configure_service | CPU/RAM/Disk metrics, journalctl logs, state mutation, declarative config rollback |
| PostgreSQL & Odoo DBs | 5 | db_list, db_overview, db_modules, db_table, db_compare | Schema introspection, installed modules, table row counts, live database comparisons |
| Migration Rehearsals | 8 | rehearse, rehearsal_status, run_check, get_report | Automated upgrade pipelines on disposable copy databases, finding analysis, risk verdicts |
| GitLab CI/CD & Deploy | 15 | gitlab_commits, gitlab_pipelines, deploy_from_gitlab | Inspect repos, branches, MRs, CI jobs, verify targets, zero-downtime production deployments |
| Declared Background Jobs | 4 | list_jobs, run_job, job_status, cancel_job | Script integrity verification, background execution tracking, automated final reports |
| Knowledge Base Semantic RAG | 6 | kb__search, kb__ask, kb__list, kb__add | Dense vector search across technical books (DDIA) and PDFs with exact page-level citations |
| Local Machine Filesystem | 8 | files__read, files__write, files__edit, files__search | Safe local file management with directory traversal protection and size caps |
| Google Workspace | 8 | calendar__events, calendar__create, email__inbox, email__send | Calendar agenda tracking, meeting links, unread emails, and gated draft sending |
| Personal Telegram MTProto | 5 | tg_user__inbox, tg_user__search, tg_user__send | Search personal dialogs, read incoming messages, interact under confirmation gating |
| Persistent Agent Memory | 8 | memory__search, memory__save, me__remember | Cross-agent facts, procedures, decay policies, operator profile cards ("Knows Me") |
| Background Cadences & Web | 7 | schedule__list, schedule__add, web__search, web__read | Cron routines, automated morning briefings, live web research with domain filtering |
Requirements
| Where | What |
|---|---|
| Laptop | Python ≥ 3.12, uv, an MCP client |
| VPS | Linux with systemd (≥ 248 recommended: Ubuntu 22.04+, Debian 12+, RHEL 9+), apt or dnf, SSH; optionally Docker or Podman |
| Migration tools | PostgreSQL ≥ 14 on the VPS (for the pg_read_all_data role) |
Quick start
git clone https://github.com/navid72m/vps-mcp && cd vps-mcp
uv sync
1. Create a dedicated SSH key and VPS user. Run the ssh root@… part with any account that
already has root on the VPS.
ssh-keygen -t ed25519 -N "" -f ~/.ssh/vps_mcp_ed25519
ssh root@<vps> "useradd -m -s /bin/bash vpsmcp && passwd -l vpsmcp && \
install -d -m 700 -o vpsmcp -g vpsmcp /home/vpsmcp/.ssh && \
echo 'restrict,pty $(cat ~/.ssh/vps_mcp_ed25519.pub)' > /home/vpsmcp/.ssh/authorized_keys && \
chown vpsmcp: /home/vpsmcp/.ssh/authorized_keys && chmod 600 /home/vpsmcp/.ssh/authorized_keys"
2. Install the least-privilege sudoers profile. Review the generated file first.
uv run vps-mcp bootstrap --print-sudoers --runtime docker --pm apt > vps-mcp.sudoers
scp vps-mcp.sudoers root@<vps>:/tmp/
ssh root@<vps> "visudo -cf /tmp/vps-mcp.sudoers && install -m 0440 /tmp/vps-mcp.sudoers /etc/sudoers.d/vps-mcp"
3. Pin the VPS host key. Compare the printed fingerprint with one you already trust, for
example from ssh-keygen -lF <vps>.
mkdir -p ~/.config/vps-mcp
uv run vps-mcp trust-host --host <vps> --known-hosts ~/.config/vps-mcp/known_hosts
4. Write the policy file. Start in read-only mode.
cp examples/vps-mcp.toml ~/.config/vps-mcp/myvps.toml # set host, key, services; read_only = true
uv run vps-mcp check-config --config ~/.config/vps-mcp/myvps.toml
5. Connect your MCP client (next section). Once you trust it, set read_only = false.
check-config also prints where the memory folder will be. It's created the first time a
client starts the server.
Connect your MCP client
The server is a stdio program. Clients start it on demand and stop it when they're done, so
seeing no vps-mcp process between sessions is normal. Use absolute paths, because GUI apps
don't inherit your shell PATH.
Claude Code (available in every new session):
claude mcp add --scope user vps -- "$(which uv)" run --directory "$PWD" \
vps-mcp serve --config ~/.config/vps-mcp/myvps.toml
Optionally, let the read-only tools run without approval prompts. Add this to
~/.claude/settings.json under permissions.allow:
"mcp__vps__list_services", "mcp__vps__get_service_status", "mcp__vps__get_service_logs",
"mcp__vps__get_resource_usage", "mcp__vps__get_service_config", "mcp__vps__get_audit_log",
"mcp__vps__list_revisions",
"mcp__vps__db_list", "mcp__vps__db_overview", "mcp__vps__db_modules", "mcp__vps__db_table",
"mcp__vps__db_compare", "mcp__vps__get_report", "mcp__vps__list_reports",
"mcp__vps__rehearsal_status", "mcp__vps__pipeline_last_run",
"mcp__vps__list_jobs", "mcp__vps__job_status",
"mcp__vps__memory_search", "mcp__vps__memory_get",
"mcp__vps__gitlab_projects", "mcp__vps__gitlab_refs", "mcp__vps__gitlab_tree",
"mcp__vps__gitlab_file", "mcp__vps__gitlab_commits", "mcp__vps__gitlab_compare",
"mcp__vps__gitlab_list_items", "mcp__vps__gitlab_read_item", "mcp__vps__gitlab_pipelines",
"mcp__vps__gitlab_job_log", "mcp__vps__deploy_targets"
The migration and job lines only apply if you enabled those features.
Keep the state-changing tools on "ask".
LM Studio (~/.lmstudio/mcp.json) or Claude Desktop
(~/Library/Application Support/Claude/claude_desktop_config.json):
{
"mcpServers": {
"vps": {
"command": "/absolute/path/to/uv",
"args": ["run", "--directory", "/absolute/path/to/vps-mcp",
"vps-mcp", "serve", "--config", "/absolute/path/to/.config/vps-mcp/myvps.toml"]
}
}
}
In LM Studio, turn on mcp/vps in the chat's Program panel, and pick a model with
tool-calling support.
OpenCode (~/.config/opencode/opencode.json, or opencode.json in a project):
{
"$schema": "https://opencode.ai/config.json",
"mcp": {
"vps": {
"type": "local",
"command": ["/absolute/path/to/uv", "run", "--directory", "/absolute/path/to/vps-mcp",
"vps-mcp", "serve", "--config", "/absolute/path/to/.config/vps-mcp/myvps.toml"],
"enabled": true
}
}
}
Every client that uses the same --config shares the same memory, so a note written
in one client can be found by the next session in all of them.
Using it
Ask in plain language. The assistant picks the tools.
The full set of examples, covering every tool, is in docs/USAGE_EXAMPLES.md.
- "What's running on my VPS?"
- "Show the last 100 lines of odoo19's logs containing 'error'"
- "Which service uses the most memory?"
- "Restart worker", or for a protected service, "restart nginx, I confirm"
- "Deploy redis:7 as a container named cache", which shows a preview first and asks you to confirm
- "Update api to ghcr.io/myorg/api:1.2", which rolls back automatically if it comes up unhealthy
- "Compare db_before with db_after and tell me if it's safe to promote" (migration tools)
- "Plan the full-rehearsal job", then "start it", then later "how is the rehearsal going?" (jobs)
- "Where are we with the migration?" in a brand-new session, answered from memory
- "Remember as a decision: promote only when the verdict is safe_to_promote" (memory)
- "What changed in the addons since v1.4? Did the pipeline pass? Then deploy v1.5" (GitLab)
- "Open an issue in addons with the blocking findings of the last rehearsal" (GitLab)
- "Show the audit log"
Service tools
| Purpose | Tools |
|---|---|
| Look | list_services, get_service_status, get_service_logs, get_service_config, list_revisions, get_resource_usage, get_audit_log |
| Control | start_service, stop_service, restart_service, set_boot_start |
| Lifecycle | deploy_service, update_service, configure_service, rollback_service, remove_service |
- Previews: deploy, update, configure, rollback and remove return a preview unless
confirm=true. - Rollback: changes are health-gated and roll back automatically on failure.
- Compact output: results are compact JSON, and logs are returned as plain
YYYY-MM-DD HH:MM:SS messagelines to keep token usage low.
The full contract is in
specs/001-vps-service-mcp/contracts/mcp-tools.md.
Deploying your own code
The server deploys images and packages from approved sources. It never uploads or builds code on the VPS. To ship your code:
- Build an image, ideally in CI (e.g. GitHub Actions).
- Push it to a registry.
- Add the registry prefix to
approved_sources.image_prefixes. - Ask the assistant to deploy or update that image.
Example: Odoo with PostgreSQL
Containers that share a networks entry reach each other by service name, so the database never
needs a published port:
deploy_service name="odoo-db" kind="container" confirm=true
container={ image:"postgres:16", networks:["odoo-net"],
env:{POSTGRES_USER:"odoo", POSTGRES_PASSWORD:"…", POSTGRES_DB:"postgres"},
volumes:["odoo-db-data:/var/lib/postgresql/data"] }
deploy_service name="odoo" kind="container" confirm=true
container={ image:"odoo:18", networks:["odoo-net"], ports:["8069:8069"],
env:{HOST:"odoo-db", USER:"odoo", PASSWORD:"…"},
volumes:["odoo-data:/var/lib/odoo"] }
This requires docker.io/library/ in approved_sources.image_prefixes. Networks the server
creates are removed automatically once no managed container uses them.
Docker Compose stacks: restarting them and reading their logs through the server is fine, but change their configuration or version with
docker compose.configure_serviceandupdate_servicerecreate the container from their own spec, which would detach it from Compose.
Migration analysis (optional)
Add a [migration] section to the policy file to enable 13 more tools. They're designed for
an Odoo version upgrade (e.g. 17 → 19) where upgrade dumps and test databases live on the VPS
and production lives elsewhere.
| Purpose | Tools |
|---|---|
| Understand | db_list, db_overview, db_modules, db_table |
| Compare + risk | db_compare, get_report, list_reports |
| Rehearse on a disposable copy | rehearse, rehearsal_status, cancel_rehearsal |
| Your own runs and checks | pipeline_last_run, run_check |
| Cleanup | drop_copies |
Comparison. db_compare snapshots both databases. Each difference becomes a finding,
classified blocking / warning / info:
- Schema: tables and columns removed or added, type narrowing and widening, and constraints and indexes.
- Rows: row losses. The largest tables are always counted exactly, because statistics can be stale after an upgrade.
- Odoo state: modules not upgraded or stuck in "to upgrade", and deactivated or orphaned views.
The report ends with a verdict: safe_to_promote, review_warnings or do_not_promote.
Rehearsal. rehearse without confirm returns a plan: the copy name, each step with a
fingerprint of its file, and free disk before and after. Confirming with the plan's plan_hash:
- creates an HMAC-marked copy of the source;
- runs your declared steps (SQL files, scripts,
odoo-bin -u all, re-upgrade of stale modules) against the copy only, in a background systemd unit that keeps running if your client disconnects; - produces a source-vs-copy report.
Copies expire after copy_retention_h (default 24 h).
Setup on the VPS (as root, after reviewing each output):
uv run vps-mcp bootstrap --print-sudoers --with-migration --config ~/.config/vps-mcp/myvps.toml
uv run vps-mcp bootstrap --print-migration-sql | ssh root@<vps> "sudo -u postgres psql -p <port>"
ssh root@<vps> "setfacl -m u:vpsmcp:rx /opt/odoo" # lets the module-code check list addons
The [migration] schema (targets, Odoo profile, pipelines, checks, thresholds) is documented in
contracts/migration-config.md
and in the commented section of examples/vps-mcp.toml.
How it stays safe:
- Analysis runs as a database role with
pg_read_all_dataonly, in read-only sessions. Queries come from a fixed catalogue, and no tool accepts SQL. - SQL step files are scanned before a rehearsal. Anything that could reach another
database, the cluster, the filesystem or a shell is refused (
\c,\!,dblink,DROP DATABASE,GRANT,pg_read_file, dynamic SQL inDOblocks, …). - Script steps are detected, not confined. Write counters on every other allowlisted database are checked around each step, and a write aborts the rehearsal with a blocking finding.
- Copies can only be dropped if both the local record and the database's HMAC marker match.
- Disk: a rehearsal needs about 1.3× the source size free plus
max(min_free_gb, min_free_pct%). It is refused up front otherwise.
Declared jobs (optional)
Some long scripts can't be rehearsed on a copy, for example a full rehearsal that drops and
rebuilds a test database from a dump, runs the deploy script, then compares the result. You can
declare such a script as a job under [[migration.job]]. Four tools then let the assistant
run it safely: list_jobs, run_job, job_status and cancel_job.
[[migration.job]]
name = "full-rehearsal"
script = "/root/full_rehearsal.sh" # root-owned, not group/other-writable
progress_file = "/root/rehearsal_logs/STEPS.txt"
report_file = "/root/rehearsal_logs/compare.md"
may_modify = ["shop_19_test"] # may be dropped and rebuilt
services = ["odoo-test"] # may be stopped
source = "shop_17_dump" # compared with result at the end
result = "shop_19_test"
How a job runs:
- Plan:
run_jobwithoutconfirmshows a plan: the script's fingerprint, owner and mode; which databases it will rebuild and which services it may stop; parameters; and free disk. Nothing runs yet. - Run: confirming with the plan's
plan_idre-checks everything, then starts the script as-is in a transient systemd unit. The job has a runtime cap, and if it's cancelled its whole process tree is killed. It keeps running if your client disconnects. Only one job or rehearsal runs at a time. - Status:
job_statusreads the job's progress file. It only reads lines written since this run started, because many scripts append to the same file across runs. It recognises outcomes such asEXIT n,rc=n,ok,FAILED,STOP…, and the success marker (ALL DONEby default). - Guard: writes to any database the job doesn't declare, an undeclared database disappearing, or a change to any undeclared managed service are all reported as blocking findings.
- Report: when the job ends, one report combines its step outcomes, an excerpt of its own
report file and a
db_compareofsourceagainstresult, and gives a verdict.
Parameters are declared with a name and a validation pattern, and are passed only as
environment variables. For example, RUN_NAME must match ^[a-z0-9_]{1,40}$ and defaults to
rehearsal_{date:%Y%m%d_%H%M}.
Limits:
- Not confined. A job is your own script running as root. The server controls what may start and when, and detects undeclared changes; it doesn't prevent them.
- Cancel has limits. Cancelling stops the job's process tree, but not work it handed to other services. For example, a query already running in PostgreSQL, or a
docker execinside a container.
Optional keys:
run_as: defaults toroot.log_globsmin_free_gb: defaults to 5.max_runtime_h: defaults to 24, at most 168.success_markeroutcome_patterns: regexes withstep/statusgroups, for progress lines the built-in rules don't recognise.
All of them are commented in examples/vps-mcp.toml. The full schema
is in contracts/job-config.md, and the
tools are in contracts/job-tools.md.
Setup on the VPS: regenerate and reinstall the sudoers file with jobs enabled. This adds
stat, used for the script owner/mode check.
uv run vps-mcp bootstrap --print-sudoers --with-migration --with-jobs \
--config ~/.config/vps-mcp/myvps.toml > vps-mcp.sudoers
GitLab (optional)
Add a [gitlab] section and the assistant can work with your GitLab, using your own token.
It only reaches the projects you allowlist, and only with the permissions you give each one.
1. Store the token in the macOS Keychain. This prompts for the token, so it never appears on a command line or in shell history:
security add-generic-password -U -s vps-mcp-gitlab -a <account> -w
| What you declare | Minimum token scope |
|---|---|
read (and deploy, which only downloads archives) | read_api |
write_issues, write_mrs, ci | api |
Prefer a project or group access token with the lowest role that works. The token can do whatever GitLab allows it to; vps-mcp only limits what assistants can do through vps-mcp.
2. Declare the projects and deploy targets in the policy file. See the commented block in
examples/vps-mcp.toml and
contracts/gitlab-config.md. Then
check that everything resolves:
uv run vps-mcp gitlab-check --config ~/.config/vps-mcp/myvps.toml
gitlab-check prints:
- the token's user and scopes;
- its expiry date, with a warning when that's under 14 days away;
- whether each project is reachable;
- what each deploy target currently has on the VPS.
It never prints the token.
| Purpose | Tools | Permission |
|---|---|---|
| Read | gitlab_projects, gitlab_refs, gitlab_tree, gitlab_file, gitlab_commits, gitlab_compare | read |
| Issues and MRs | gitlab_list_items, gitlab_read_item; gitlab_write (create issue, comment, open MR, close an issue vps-mcp created) | read; write_issues / write_mrs |
| CI | gitlab_pipelines, gitlab_job_log; gitlab_ci (retry, cancel, trigger on trigger_refs) | read; ci |
| Deploy | deploy_targets, deploy_from_gitlab, rollback_deploy | deploy |
Assistants address projects by the alias you give them, never by GitLab path or ID, so
projects you didn't declare are unreachable. There is no merge tool at all. Closing issues needs
close_issues = true, and by default only covers issues vps-mcp created; they carry a
_Posted via vps-mcp_ footer. Every write previews first, needs confirm=true, is audited, and
is refused in read-only mode.
Deploying. deploy_from_gitlab without confirm returns a plan with:
- the exact commit;
- the version currently deployed and any files edited on the VPS since;
- the files that change;
- the pipeline status;
- the services that will restart;
- free disk space.
Confirming with the plan's plan_id deploys exactly that commit:
-
Your laptop downloads the commit's archive from GitLab. The VPS never contacts GitLab, and the token never leaves your laptop.
-
The laptop rebuilds it as a clean tar. Unsafe paths, links leaving the tree, special files and excluded paths are dropped, and ownership and modes are normalised.
-
The tar is streamed over SSH into a new release directory on the VPS:
/var/lib/vps-mcp/deploys/<target>/releases/<time>-<sha12>/ files + MANIFEST.sha256 + marker <destination> -> symlink to the active release -
The symlink is switched in one step, so readers see either the old version or the new one.
-
The declared services are restarted and health-checked, including
health_urlif you set it. If anything is unhealthy, the previous release is switched back automatically.
Releases you didn't deploy through vps-mcp are moved aside to releases/pre-vps-mcp-<time>/,
never deleted. The last keep_releases versions are kept, and rollback_deploy switches back to
one of them. Deploys are refused:
- while another deploy of the same target is running;
- while a declared job that uses the same services is running;
- while a rehearsal is running.
The deployed version of each target, and recent GitLab activity, appear in the memory, as facts that are kept up to date.
VPS setup (as root, after reviewing the output):
uv run vps-mcp bootstrap --print-sudoers --with-gitlab > gitlab.sudoers # tar, ln, mv, rm, ...
Add the result to /etc/sudoers.d/vps-mcp. These binaries are root-equivalent. As with the
rest of vps-mcp, the guarantee is that the server only issues its own validated commands, on
paths under /var/lib/vps-mcp/deploys and the destinations you declared.
Memory
Memory is agent-memory, a managed knowledge store rather than a conversation log. It ships in
this repo as its own package and command (agent-memory). Every agent and every project can
share it. vps-mcp uses it as a library.
What a memory is. One concise piece of knowledge, stored as one Markdown file with structured front matter:
| Field | Meaning |
|---|---|
type | semantic (what is true), decision (why; with rejected alternatives), procedural (how to do something), episodic (what happened; open/done for issues and next steps) |
scope | user, project:<name>, environment:<name> or task:<id>; a session sees its own scopes plus user |
subject | a dotted key such as postgres.version, used for duplicates and conflicts |
| provenance | the source (client, task, file, web, issue, tool_output, tool_generated, operator, …), the client, created/updated/last-confirmed times and a confirmation count |
confidence | verified, inferred or unverified |
| lifecycle | active, superseded (linked to its successor), expired, invalidated or archived; an optional expiry; live_state facts carry a freshness window |
The write policy is enforced by code on every save, not left to the agent:
- Secrets are refused and never written. Store a reference to where a secret lives instead.
- Duplicates (same subject, nearly the same text) become a confirmation of the existing memory, not a second copy.
- Contradictions on the same subject are kept on both sides, linked, and flagged
needs verification. Decisions are only replaced by an explicitsupersedewith a reason, so nothing is overwritten silently. - Text from untrusted sources (READMEs, issues, web pages, tool output) is stored as
unverified. If it reads like an instruction ("ignore previous…", "always run curl …") it is refused as a procedure or decision. Only the operator can save such text, withagent-memory save --operator. Agents cannot raise trust through the tools. - Facts about live state (for example "web is running") always come back with a "verify live" flag, and a "possibly stale" flag once they are older than their freshness window.
Retrieval is task-aware. When a session connects it gets only a small pinned core
(~500 tokens): pinned procedures and decisions, plus open issues. Everything else is searched
for. memory_search ranks matches by keyword relevance, recency, importance, confidence and
scope (task > environment > project > user). It returns at most 8 by default, grouped as facts,
decisions, experiences and procedures, and says "nothing relevant" instead of padding. Superseded,
expired and invalidated memories stay out of results unless you ask for history.
| Tool | What it does |
|---|---|
memory_search | Ranked, scope-aware search, grouped by type, with flags (verify live, stale, conflict, inferred, open) |
memory_get | One memory with full provenance: history, what it superseded, conflicts, related memories |
memory_save | A validated save: created, confirmed (duplicate) or conflict (flagged) |
memory_update | update metadata, supersede, invalidate, expire, confirm, close, resolve_conflict |
memory_archive | Forget a memory. It previews first and moves the file to archive/ |
vps-mcp's own facts. vps-mcp writes generated, live-state facts into
environment:<vps name>: service states, the deployed version per GitLab target, the last
outcome of each job and rehearsal, and the latest report verdict. They are updated in place,
never duplicated. Agents can search them like any other memory. If the store can't be opened,
vps-mcp keeps working and says memory is unavailable.
The store. By default it lives in ~/.local/share/agent-memory/ (or $AGENT_MEMORY_HOME):
agent-memory/
├── memories/<scope>/ one .md file per memory: read, edit or delete by hand; noticed on next search
├── archive/ archived memories
├── events/ append-only history and audit (no memory content)
└── index.sqlite search index (SQLite FTS5), rebuilt from the files automatically
Use it from any agent, not only through vps-mcp:
claude mcp add --scope user memory -- "$(which uv)" run --directory "$PWD" \
agent-memory serve --project my-project --client claude-code
The same works in OpenCode, Antigravity or LM Studio (agent-memory serve --project …). Each
session sees its project's memories plus user scope, and never other projects' memories.
Operator commands:
uv run agent-memory search "database backup" --project my-project
uv run agent-memory save --operator --type procedural --scope project:my-project \
--subject deploy.order --title "Stop the app first" --content "…" --pinned
uv run agent-memory doctor # counts, malformed files, conflicts, stale facts, warnings
uv run agent-memory bench # recall / precision / stale hits / conflicts / token cost
uv run agent-memory migrate-004 ~/.config/vps-mcp/myvps.memory --project vps-myvps \
--environment myvps # dry run; add --apply to import feature-004 notes
Benchmark (built-in fixtures: 289 memories, 22 tasks). Compared with plain keyword search, ranked retrieval keeps recall and never returns an outdated memory:
| Configuration | Recall@8 | Precision@8 | Stale hits | Conflicts flagged | Tokens per result |
|---|---|---|---|---|---|
| naive keyword search | 0.95 | 0.36 | 100% | 0% | 25 |
| agent-memory | 0.97 | 0.80 | 0% | 100% | 208 |
The pinned core costs about 150 tokens.
Personal assistant
assistant is a background process that is its own agent. It runs on your laptop and talks
to you through a Telegram bot. It thinks with a language model (Claude, or a local model via LM Studio or Ollama,
or anything else with an OpenAI-compatible API), uses MCP servers such as vps-mcp as its tools, and shares agent-memory with your
other clients.
Where it runs. On your laptop, as a launchd user agent: it starts at login and is restarted
after a crash. It only makes outgoing connections (Telegram long polling, the model API, the MCP
servers), so there's no open port, domain or webhook. While the laptop sleeps it is offline. When
it wakes it sends one "missed" note instead of replaying schedules. Moving it to an always-on box
later only needs a different service definition (--systemd-user) and secrets provider (file).
Setup.
-
In Telegram, ask @BotFather for a bot token (
/newbot), and @userinfobot for your user id. -
Store the secrets in the Keychain. Run these in your own Terminal; each one prompts, so nothing is echoed:
security add-generic-password -U -s vps-mcp-assistant -a telegram_bot_token -w security add-generic-password -U -s vps-mcp-assistant -a anthropic_api_key -wThe second one is only needed for Claude. A local model needs no key: set
[model] provider = "openai"andbase_url = "http://localhost:1234/v1"(LM Studio's server) as shown in the example config. Tool use needs a model that is good at it: small models (4B to 8B) work for simple lookups but get multi-step tasks wrong more often.Several models.
[model]is the default; add[models.<name>]for others (see the example config). On the phone,/modellists them with a button each,/model geminiswitches at once, and "switch to gemini" makes the assistant send a confirm button (it never switches on its own, so text in a tool result can't move your chats to a cloud model). The choice survives restarts. Only the default model's key is needed at startup; a missing key for another model is reported when you switch. -
Copy
examples/assistant.tomlto~/.config/assistant/assistant.toml. Setallowed_user_ids,timezoneand the vps server'scommand. -
Check and install:
uv run assistant check uv run assistant service installStatus is
assistant service status; logs are in~/.local/state/assistant/logs/.
Using it. Write to the bot. Only your account gets answers: messages from anyone else are dropped before any model or tool call, and audited.
| Command | What it does |
|---|---|
| any text | Ask or instruct. It uses read-only tools directly and asks before anything else |
/new · /done | Start fresh / end the conversation, and get memory proposals to Save or Discard |
/status · /usage | Servers, schedules, pending approvals, heartbeat · today's tokens, calls and cost |
/schedules · /schedule add <name> <daily HH:MM|weekdays HH:MM|every Nh> <prompt> | Recurring prompts, e.g. a morning briefing; also pause / resume / remove |
/stop · /resume | Kill switch: cancels running work and voids approvals; nothing runs until /resume |
/forget | Delete stored conversation history (memory is not affected) |
/model [name] | List the models (with switch buttons) or switch to one |
/tools | Core tools, toolsets, which are loaded now, and the size of the tool list |
/me · /me all · /me export | What it knows about you, with edit/remove buttons · including sensitive facts · as a file |
/interview | Getting-to-know-you questions; /interview stop, /interview sensitive on |
/agenda [today|tomorrow|week] | Upcoming Google Calendar events and meetings |
/inbox | Unread emails from Gmail with sender, date, and summary snippets |
/tg [unread|chats|search <q>] | Personal Telegram inbox, recent chats, or search messages |
/kb [list|search <q>|add <path>] | Knowledge Base: search passages, list indexed books/papers, or ingest files |
/ls [path] · /cat <path> · /send <path> | Explore files on the laptop, inspect content, or send files to chat |
| a photo, document or link | Looks at it and answers (see Web, photos and documents) |
Approvals. Each tool has a policy: auto, ask or never. By default read-only tools are
auto and everything else is ask; tools that aren't allowlisted are never offered to the
model. For an ask tool you get a message showing the tool, its arguments and the tool's own
preview (vps-mcp's confirm=false plan), with Approve / Reject buttons.
- An approval is bound to that exact call, works once, and expires (10 min by default).
- Buttons are signed with a key that changes on every restart, so old or forged buttons do nothing.
- Scheduled runs always ask before a state-changing action, whatever the policy.
Knowing you. The assistant keeps a profile of you and the people in your life, and notes on your recent conversations, in the local agent-memory store:
- "Remember …" (also "note that", "merk dir", "یادت باشه") saves the fact right away. The bot itself confirms it ("📝 Saved: …") with an ↩️ Undo button that works for 24 hours. Correcting a known fact ("actually Sara moved to Munich") replaces it and shows what it was. Only your own message can do this: text from a tool, file, web page or memory can at most become a suggestion, and passwords, PINs and keys are never stored.
- Your profile (identity, work, people, interests, routines) is in every conversation, so
it knows your name and your sister's city without searching.
/meshows it with ✏️ Edit and 🗑 Remove buttons,/me allincludes sensitive facts,/me exportsends everything as a file. "Forget my address" lists the matches for you to confirm. - Sensitive facts (health and medication, finances, relationships, religion, politics) are kept only when you explicitly ask, never shown in the everyday profile, and never suggested.
- Recaps: when a conversation ends (
/done,/newor 30 minutes idle) it writes a short recap (topics, outcomes, open loops). The next conversation starts with the last few, so it remembers what you talked about. This uses the same model call as the suggestions below. - Suggestions: things it infers are proposed at the end of a conversation with 💾 Save / 🗑 Discard and a Save all button; anything it already knows is not proposed again.
/interviewasks you one question at a time (name, place, work, people, interests, answer style) to fill the profile quickly; skip or stop any time, it resumes where it left off. A thin profile gets one offer at most once a week.- Memories saved before this existed (
operator.*) are read as they are;assistant knowme migrate --applyre-files them under the new scheme.
Tools and context. Not every tool is sent to the model on every message: tool definitions alone were about 10,000 tokens per call. A few core tools are always there (memory search, schedules, service status). The rest are grouped into toolsets (gitlab, db, deploy, migration, jobs, services, files, …), and the model sees a one-line catalog of them. A toolset is loaded when:
- your message matches its keywords ("why did the pipeline fail?" loads
gitlabbefore the model even starts); - the model asks for it with
tools__load; - the model calls one of its tools directly.
A toolset that was loaded but not used goes after 2 messages; one that was used stays until 6
messages without use. /new starts again from the core. Loading never changes a tool's policy:
ask tools still ask and never tools are never shown. Groups, core tools and keywords are set per server in the
config (core = [...], [server.toolsets.<name>], see the example). [tools] lazy = false
sends everything as before, and lazy_tools on a model overrides it for that model, so a big
hosted model can get every tool while a local one stays lean. assistant check prints the size
with and without lazy loading.
Web, photos and documents.
- Web search and pages. It can search the web and read pages or PDF links, and answers
with the source links. Send it a link and it reads it. Search uses Tavily by default (free
plan, no card, 1,000 credits a month; one search is one credit): store its key once with
security add-generic-password -U -s vps-mcp-assistant -a tavily_api_key -w. Brave Search works too ([web] search_provider = "brave", keybrave_api_key). Without a key, reading links still works. It refuses links tolocalhost, your home network or cloud metadata addresses, including through redirects, so a page can't make it probe your network. - Photos and screenshots. Send one, with or without a question; several photos sent
together are one question. The image goes to the model once; later messages only see
"[photo]". If the current model can't see images (
vision = falsein its config), it says so and names one that can. - Documents. PDFs (with a text layer), Word
.docxand text files are read and answered about ("what does this letter want from me, and by when?"). Scanned PDFs aren't read yet — send photos of the pages instead. Files over 20 MB can't be downloaded by bots. - Everything from the web, a photo or a document is untrusted data: instructions inside it are never followed, and only your caption counts as your words for "remember".
- Privacy: search queries go to the search provider, pages are fetched from your laptop's IP, and photos and documents go to the model provider.
Executive Web Cockpit
In addition to Telegram, you can launch a local, dark-mode web control center:
uv run assistant ui
# or: uv run assistant web --port 8765
- Secretary Console: Full desktop chat with on-the-fly model switcher (
groq,deepseek,qwen,nemotron). - Action Guardrail: Review pending sensitive actions (emails, service restarts, file modifications) with syntax-highlighted previews, diffs, and 1-click Approve / Reject buttons.
- Agenda & Inbox: Live Google Calendar events timeline and Gmail executive inbox summaries.
- Knowledge Base RAG: Search ingested books (DDIA, research papers) with exact page citations and relevance scores.
- VPS Telemetry: Real-time CPU, RAM, and disk utilization, plus status for all 20 systemd services and Docker containers.
- Profile & Memory ("Knows Me"): Operator identity cards, working preferences, and memory explorer.
- Routines & Cadences: Pause / resume scheduled briefings, timers, and cron routines.
Google Calendar & Gmail
Connects your personal assistant to Google Workspace via standard OAuth 2.0 with minimal scopes (calendar.readonly, calendar.events, gmail.readonly, gmail.send).
- Setup: Place your Google OAuth client secrets at
~/.config/assistant/google_client.json. - Authorize: Run the interactive OAuth flow:
The refresh token is securely stored in the macOS Keychain (assistant google-authgoogle_refresh_token). - Usage:
/agendaor/agenda [today|tomorrow|week]: View upcoming calendar events with meeting links./inbox: Quick view of unread emails with sender, subject, and snippet.- Agent Tools:
calendar__events,calendar__create_event,email__inbox,email__send. - Safety Gating: Sending an email (
email__send) always pauses for approval, presenting a full draft preview and inline Approve / Reject buttons.
[google]
enabled = true
credentials_path = "~/.config/assistant/google_client.json"
token_secret = "google_refresh_token"
max_emails = 10
max_events = 20
Personal Telegram MTProto
Integrates the assistant with your own personal Telegram account via Telethon MTProto user sessions (separate from the bot API).
- Setup: Obtain your
api_idandapi_hashfrom my.telegram.org and store them in the Keychain:security add-generic-password -U -s vps-mcp-assistant -a telegram_api_id -w "<your_id>" security add-generic-password -U -s vps-mcp-assistant -a telegram_api_hash -w "<your_hash>" - Authorize: Authenticate via terminal session:
(Prompts for phone number and Telegram login code; session is stored inassistant tg-auth~/.config/assistant/telegram_user.session). - Usage:
/tg unread: View unread dialogs and message counts./tg chats: List recent personal chats, groups, and channels./tg search <query>: Full-text search across your personal Telegram history.- Agent Tools:
tg_user__inbox,tg_user__read,tg_user__search,tg_user__send,tg_user__save(Saved Messages). - Interactive Approval: Outgoing messages (
tg_user__send) always prompt for approval on your phone showing the recipient, body preview, and inline buttons before dispatching.
[telegram_user]
enabled = true
session_path = "~/.config/assistant/telegram_user.session"
max_messages = 15
Knowledge Base RAG (Books, Papers, PDFs)
A dedicated, isolated vector retrieval engine for reading and asking questions across your library of books, research papers, and technical PDFs.
[!IMPORTANT] Strict Memory Isolation: The Knowledge Base is completely separated from your personal memory (
agent-memory). Personal operator facts remain in~/.local/state/assistant/memory/, while large reference documents and dense vector embeddings reside exclusively in~/.local/state/assistant/knowledge_base/.
- Vector Engine: Cosine similarity powered by high-performance FAISS (
IndexFlatIP) with L2-normalized dense embeddings. - Embeddings: Uses
sentence-transformers(all-MiniLM-L6-v2, 384 dimensions) running locally on CPU. - Document Ingestion: Extracts text page-by-page from PDFs (
pypdf/fitz), Word.docx, Markdown, and plain text. Implements paragraph-aware chunking with customizable overlap (chunk_size=1000,chunk_overlap=200). - Exact Citations & Grounding: Every retrieved chunk retains its source document, title, author, and exact page number (
page 346,chunk 329). - Prompt Injection Envelope: All retrieved reference excerpts are wrapped inside
<reference_content>untrusted envelopes, protecting the model from indirect prompt injections. - Terminal CLI Management:
# Ingest a book or paper assistant kb add ~/Downloads/paper.pdf --title "Attention Paper" --author "Vaswani et al." # List indexed library assistant kb list # Semantic vector search assistant kb search "multi-head self attention" --top-k 3 # Remove document and its vectors assistant kb remove "Attention Paper" - Telegram Chat Usage:
/kbor/kb list: View all indexed library books with chunk counts and sizes./kb search <query>: Search passages across all literature./kb add <path>: Ingest documents directly from the chat.- Natural Q&A: Ask questions naturally ("According to DDIA, what is the difference between B-trees and LSM-trees?"); the assistant automatically calls
kb__ask/kb__searchand quotes page citations.
- Interactive Approval: Deleting documents (
kb__remove) requires Telegram inline button approval before vectors are wiped.
[knowledge_base]
enabled = true
storage_dir = "~/.local/state/assistant/knowledge_base"
embedding_model = "all-MiniLM-L6-v2"
chunk_size = 1000
chunk_overlap = 200
top_k = 5
Limits and audit.
- Per-turn and per-day caps on model calls, tool calls, tokens and estimated cost stop runaway loops, and the message says which limit was hit.
- Every model call, tool call, approval, refusal, schedule run and command is audited (no message
text or tool output):
assistant audit --since 1d.
Privacy.
- The model provider sees your conversation and the tool results it is given. With a local model, nothing leaves the laptop except Telegram messages.
- Secrets never leave the Keychain except to authenticate. Anything outgoing to Telegram is scrubbed of known secrets, including text the model writes.
- Tool output and memory are given to the model as labelled, untrusted data. An instruction hidden in them can't bypass the policy or an approval, and the approval message always shows the real call.
Security model
- No arbitrary commands. Every remote command is a fixed template, and every input is validated and shell-quoted.
- Allowlist. Only declared services, services deployed through the server, and allowlisted
databases can be touched. Anything else returns
not_permitted, without revealing whether it exists. - Confirmations and protected services. Destructive actions preview first. Protected services need confirmation to stop or restart, and can never be removed.
- Read-only mode refuses every state change.
- Lock-out guard. The SSH service can never be stopped, disabled, changed or removed.
- Strict host-key pinning. There is no trust-on-first-use, and a changed host key stops everything.
- Least privilege. A dedicated VPS user with a narrow sudoers profile.
- Audit trail. Every state-changing attempt (including refused, failed and timed-out ones)
is recorded locally in SQLite (mode 0600). Credentials and secret-looking values
(
*PASSWORD*,*TOKEN*, …) are masked in output, logs and the database.
Access to the container runtime, the package manager,
psqlas postgres andsystemd-runis root- or superuser-equivalent by nature. The guarantees above come from the server only ever issuing its own generated, validated commands, so protect the SSH key accordingly.
Configuration reference
See examples/vps-mcp.toml. Every key is commented, and unknown keys
are errors. The main sections:
| Section | Purpose |
|---|---|
[vps] | host, port, user, key_path, known_hosts_path, container_runtime, package_manager |
[policy] | read_only, min_free_disk_mb, secret_keys, remote_access_units, health_stabilize_s |
[policy.timeouts] | control_s, deploy_s, query_s |
[policy.approved_sources] | apt_origins, dnf_repos, image_prefixes |
[[service]] | name, kind (os/container), protected, package, config_files, validate, data_paths |
[migration] | optional; see Migration analysis |
[[migration.job]] | optional, up to 10; see Declared jobs |
[gitlab] | optional: url, keychain_service, keychain_account, ca_bundle, timeout_s, max_archive_mb, plus [[gitlab.project]] and [[gitlab.deploy]]; see GitLab |
[memory] | optional: enabled, store (default agent-memory's store), project (default vps-<name>), writable, pinned_chars; see Memory |
Validate with vps-mcp check-config --config <file>. The local audit/state database lives in
~/.local/state/vps-mcp/<vps-name>.db.
Troubleshooting
| Symptom | Cause / fix |
|---|---|
connection_failure/identity_mismatch | The VPS host key changed. Verify it out-of-band, then trust-host --replace. |
connection_failure/auth_rejected | The key isn't in /home/vpsmcp/.ssh/authorized_keys, or key_path is wrong. |
connection_failure/timeout | Port 22 is blocked or the host is down. |
permission_denied | /etc/sudoers.d/vps-mcp is missing or out of date. Regenerate it with bootstrap --print-sudoers. |
read_only on every action | read_only = true in [policy]. The change applies the next time the client starts the server. |
| Logs return 0 lines for nginx | nginx logs to /var/log/nginx/*.log, not the journal. Only journal and container logs are read. |
| Tools missing in Claude Code | Start a new session after claude mcp add, then check with /mcp. |
insufficient_disk on rehearse | Free space on the VPS, or lower [migration] min_free_gb / min_free_pct knowingly. |
permission_denied mentioning stat on run_job | The jobs sudoers rule is missing. Reinstall with --with-migration --with-jobs. |
conflict on run_job: "something is already running" | Only one job or rehearsal runs at a time. Check job_status / rehearsal_status. |
conflict on run_job: plan unknown/older than 30 min, or script changed | The error includes a fresh plan. Review it and confirm with its plan_id. |
gitlab_token_missing | Store the token: security add-generic-password -U -s vps-mcp-gitlab -a <account> -w. |
gitlab_auth | The token expired or was revoked. Store a new one with the same command. |
gitlab_scope | The token lacks a scope or role for that action. gitlab-check lists scope gaps. |
gitlab_rate_limited | GitLab's rate limit was hit. Retry after the given number of seconds. |
A deploy reports rolled_back | A service failed its health check after the switch. The previous release is active again; the response includes the service's last log lines. |
| A new session doesn't seem to know the memory | Memory is searched, not injected: ask it to "search memory for …". Only pinned items and open issues arrive at connect. |
Memory unavailable in the instructions | Run agent-memory doctor. The store may be unwritable or a symlink, which is refused. |
check-config mentions migrate-004 | You have feature-004 notes; import them with the command it prints. |
| Job tools missing | No [[migration.job]] is declared, or the client hasn't restarted the server since you added one. |
Development
uv run pytest # unit, contract and negative suites: no VPS needed (1,102 tests)
uv run ruff check && uv run ruff format --check && uv run mypy
- Fakes: tests run against a simulated VPS (
tests/fakes.py) and a simulated PostgreSQL cluster (tests/fakepg.py). - Planted defects: one suite plants defects and checks every one is caught with the right severity.
- Negative suites: over 300 disallowed requests, each asserting that nothing was changed remotely.
Integration tests run against a disposable VM. Never use them on a production server.
tests/integration/provision.sh # creates a Multipass VM with nginx, Docker and PostgreSQL
uv run pytest -m integration --vps-config tests/integration/vps-mcp.test.toml
Project layout:
src/vps_mcp/
├── server.py # MCP tools (services) + migration/jobs/memory registration, pinned core
├── cli.py # serve | check-config | trust-host | bootstrap | gitlab-check
├── config/ # policy file models and loader
├── remote/ # SSH connection, fixed-template executor, redaction
├── backends/ # systemd + apt/dnf, docker/podman
├── core/ # guard (allowlist, confirm, audit), actions, deploy, changes, queries
├── store/ # SQLite: audit, revisions, deployed services, migration tables
├── migration/ # catalogue, snapshot/diff/risk, copies, runner, rehearsal, checks
├── jobs/ # declared jobs: integrity, params, launcher, progress, guard, report
├── memory/ # adapter onto agent-memory: generated facts, tool registration
└── gitlab/ # GitLab: Keychain token, client, access, read/items/ci, archive, deploy
src/assistant/ # personal assistant runtime (daemon, CLI, Telegram bot):
│ # config, secrets, state, telegram, providers (OpenAI/Anthropic/local),
│ # toolhub (policy + previews), approvals, memory, budget, agent loop,
│ # scheduler, commands, app, service, cli,
│ # google_auth, calendar, gmail (Google Workspace),
│ # telegram_user (Telethon MTProto personal account),
│ # knowledge_base (FAISS vector store RAG for books & papers)
src/agent_memory/ # standalone memory: model, files, index (FTS5), policy, ranking, store,
# pinned core, MCP tools/server, CLI, migrate-004, bench
specs/ # speckit spec, plan, research, contracts, tasks per feature
No installation packages available.