Digital Secretary
by navid72m
README.md
# VPS-MCP & Digital Secretary
[](https://www.python.org/downloads/)
[](https://glama.ai/mcp/servers/navid72m/vps-mcp)
[](https://registry.modelcontextprotocol.io)
[](#the-90-tool-ecosystem)
[](LICENSE)
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.
---
<p align="center">
<img src="docs/images/cockpit-demo.png" alt="Executive Web Cockpit Demo" width="95%">
</p>
<p align="center">
<em>The Executive Web Cockpit running on <code>http://127.0.0.1:8765</code> with real-time tool execution, live model switching, responsive GFM table rendering, and server telemetry.</em>
</p>
---
### Core Platform Pillars
- **Executive Web Cockpit & Telegram Assistant (`assistant`)**:
A local dark-mode command center ([`http://127.0.0.1:8765`](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/`](specs/001-vps-service-mcp/) (services),
[`specs/002-odoo-migration-analysis/`](specs/002-odoo-migration-analysis/) (migration),
[`specs/003-declared-jobs/`](specs/003-declared-jobs/) (jobs),
[`specs/004-agent-memory/`](specs/004-agent-memory/) (memory),
[`specs/005-gitlab-integration/`](specs/005-gitlab-integration/) (GitLab),
[`specs/007-assistant-runtime/`](specs/007-assistant-runtime/) (personal assistant),
[`specs/008-lazy-tool-loading/`](specs/008-lazy-tool-loading/) (lazy tool loading),
[`specs/009-knows-me/`](specs/009-knows-me/) (operator profile & recall),
[`specs/010-web-and-media/`](specs/010-web-and-media/) (web, photos, documents),
[`specs/011-email-and-calendar/`](specs/011-email-and-calendar/) (Google Workspace),
[`specs/012-personal-telegram/`](specs/012-personal-telegram/) (personal Telegram account MTProto), and
[`specs/013-knowledge-base-rag/`](specs/013-knowledge-base-rag/) (knowledge base RAG).
---
## Contents
- [The 90+ Tool Ecosystem](#the-90-tool-ecosystem)
- [Requirements](#requirements)
- [Quick start](#quick-start)
- [Connect your MCP client](#connect-your-mcp-client)
- [Using it](#using-it)
- [Service tools](#service-tools)
- [Migration analysis](#migration-analysis-optional)
- [Declared jobs](#declared-jobs-optional)
- [GitLab](#gitlab-optional)
- [Memory](#memory)
- [Personal assistant](#personal-assistant)
- [Executive Web Cockpit](#executive-web-cockpit)
- [Google Calendar & Gmail](#google-calendar--gmail)
- [Personal Telegram MTProto](#personal-telegram-mtproto)
- [Knowledge Base RAG (Books, Papers, PDFs)](#knowledge-base-rag-books-papers-pdfs)
- [Security model](#security-model)
- [Configuration reference](#configuration-reference)
- [Troubleshooting](#troubleshooting)
- [Development](#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](https://docs.astral.sh/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
```bash
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.
```bash
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.
```bash
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>`.
```bash
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.
```bash
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):
```bash
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`:
```json
"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`):
```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):
```json
{
"$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](#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`](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 message` lines to keep token usage low.
The full contract is in
[`specs/001-vps-service-mcp/contracts/mcp-tools.md`](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:
1. Build an image, ideally in CI (e.g. GitHub Actions).
2. Push it to a registry.
3. Add the registry prefix to `approved_sources.image_prefixes`.
4. 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:
```text
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_service` and
> `update_service` recreate 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`:
1. creates an HMAC-marked copy of the source;
2. 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;
3. 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):
```bash
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`](specs/002-odoo-migration-analysis/contracts/migration-config.md)
and in the commented section of [`examples/vps-mcp.toml`](examples/vps-mcp.toml).
**How it stays safe:**
- **Analysis** runs as a database role with `pg_read_all_data` only, 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 in `DO` blocks, …).
- **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`.
```toml
[[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:
1. **Plan**: `run_job` without `confirm` shows 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.
2. **Run**: confirming with the plan's `plan_id` re-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.
3. **Status**: `job_status` reads 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 as `EXIT n`, `rc=n`, `ok`, `FAILED`, `STOP…`, and the success marker
(`ALL DONE` by default).
4. **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.
5. **Report**: when the job ends, one report combines its step outcomes, an excerpt of its own
report file and a `db_compare` of `source` against `result`, 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 exec`
> inside a container.
Optional keys:
- `run_as`: defaults to `root`.
- `log_globs`
- `min_free_gb`: defaults to 5.
- `max_runtime_h`: defaults to 24, at most 168.
- `success_marker`
- `outcome_patterns`: regexes with `step`/`status` groups, for progress lines the built-in rules
don't recognise.
All of them are commented in [`examples/vps-mcp.toml`](examples/vps-mcp.toml). The full schema
is in [`contracts/job-config.md`](specs/003-declared-jobs/contracts/job-config.md), and the
tools are in [`contracts/job-tools.md`](specs/003-declared-jobs/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.
```bash
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:
```bash
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`](examples/vps-mcp.toml) and
[`contracts/gitlab-config.md`](specs/005-gitlab-integration/contracts/gitlab-config.md). Then
check that everything resolves:
```bash
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**:
1. Your laptop downloads the commit's archive from GitLab. The VPS never contacts GitLab, and
the token never leaves your laptop.
2. 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.
3. The tar is streamed over SSH into a new release directory on the VPS:
```text
/var/lib/vps-mcp/deploys/<target>/releases/<time>-<sha12>/ files + MANIFEST.sha256 + marker
<destination> -> symlink to the active release
```
4. The symlink is switched in one step, so readers see either the old version or the new one.
5. The declared services are restarted and health-checked, including `health_url` if 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](#memory), as facts that are kept up to date.
**VPS setup** (as root, after reviewing the output):
```bash
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 explicit `supersede` with 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, with
`agent-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`):
```text
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:
```bash
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:**
```bash
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.**
1. In Telegram, ask **@BotFather** for a bot token (`/newbot`), and **@userinfobot** for your user
id.
2. Store the secrets in the Keychain. Run these in your own Terminal; each one prompts, so nothing
is echoed:
```bash
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 -w
```
The second one is only needed for Claude. A local model needs no key:
set `[model] provider = "openai"` and `base_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, `/model` lists them with a button each, `/model gemini`
switches 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.
3. Copy [`examples/assistant.toml`](examples/assistant.toml) to
`~/.config/assistant/assistant.toml`. Set `allowed_user_ids`, `timezone` and the vps server's
`command`.
4. Check and install:
```bash
uv run assistant check
uv run assistant service install
```
Status 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. `/me` shows it with ✏️ Edit and
🗑 Remove buttons, `/me all` includes sensitive facts, `/me export` sends 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`, `/new` or 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.
- **`/interview`** asks 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 --apply` re-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 `gitlab` before 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"`, key `brave_api_key`). Without a key, reading
links still works. It refuses links to `localhost`, 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 = false` in its config), it says
so and names one that can.
- **Documents.** PDFs (with a text layer), Word `.docx` and 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:
```bash
uv run assistant ui
# or: uv run assistant web --port 8765
```
<p align="center">
<img src="docs/images/cockpit-demo.png" alt="Digital Secretary Executive Web Cockpit" width="95%">
</p>
- **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`).
1. **Setup**: Place your Google OAuth client secrets at `~/.config/assistant/google_client.json`.
2. **Authorize**: Run the interactive OAuth flow:
```bash
assistant google-auth
```
The refresh token is securely stored in the macOS Keychain (`google_refresh_token`).
3. **Usage**:
- `/agenda` or `/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.
```toml
[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).
1. **Setup**: Obtain your `api_id` and `api_hash` from [my.telegram.org](https://my.telegram.org) and store them in the Keychain:
```bash
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>"
```
2. **Authorize**: Authenticate via terminal session:
```bash
assistant tg-auth
```
(Prompts for phone number and Telegram login code; session is stored in `~/.config/assistant/telegram_user.session`).
3. **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.
```toml
[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**:
```bash
# 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**:
- `/kb` or `/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__search` and quotes page citations.
- **Interactive Approval**: Deleting documents (`kb__remove`) requires Telegram inline button approval before vectors are wiped.
```toml
[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
1. **No arbitrary commands.** Every remote command is a fixed template, and every input is
validated and shell-quoted.
2. **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.
3. **Confirmations and protected services.** Destructive actions preview first. Protected
services need confirmation to stop or restart, and can never be removed.
4. **Read-only mode** refuses every state change.
5. **Lock-out guard.** The SSH service can never be stopped, disabled, changed or removed.
6. **Strict host-key pinning.** There is no trust-on-first-use, and a changed host key stops
everything.
7. **Least privilege.** A dedicated VPS user with a narrow sudoers profile.
8. **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, `psql` as postgres and `systemd-run`
> is 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`](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-analysis-optional) |
| `[[migration.job]]` | optional, up to 10; see [Declared jobs](#declared-jobs-optional) |
| `[gitlab]` | optional: `url`, `keychain_service`, `keychain_account`, `ca_bundle`, `timeout_s`, `max_archive_mb`, plus `[[gitlab.project]]` and `[[gitlab.deploy]]`; see [GitLab](#gitlab-optional) |
| `[memory]` | optional: `enabled`, `store` (default agent-memory's store), `project` (default `vps-<name>`), `writable`, `pinned_chars`; see [Memory](#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
```bash
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.
```bash
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:
```text
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
```
Maintenance
ActivityMaintained
ResponsivenessNo recent community issues