Sidekick

Autonomous Agent Platform

Sidekick is a self-hosted platform that gives AI assistants and agents durable infrastructure: a remote machine they can operate, persistent project memory and knowledge that survive any single session, a governed and dynamically discoverable MCP tool catalog, an autonomous task runner, and distributed model compute. The connected assistant or agent is replaceable — you can switch clients, models, or vendors — while the projects, memory, tools, policy, and history stay on your machine, under your control.

See the privacy policy. A running HTTP instance also exposes it at /privacy for directory and integration review.

Why use it? Because most AI work loses everything between sessions. With Sidekick, one session's decisions, handoffs, and stored facts are retrievable by the next session — or by a completely different agent. Typical uses that the current implementation supports:

• keeping project continuity across AI sessions and across different agents/models;
• software development and project work on a persistent remote machine (shell, files, git, GitHub API, CI inspection, databases);
• durable autonomous tasks through the Agent Bridge (structured goals, bounded profiles, governed tools, checkpoints, verification, artifacts, follow-ups, and restart-aware recovery);
• self-hosted AI infrastructure and homelab/system administration (services, processes, networking, monitoring, incident capture);
• scheduled and event-driven automation (cron, one-shot delays, watches, runbooks);
• routing local/distributed model workloads (chat, generation, embeddings) across enrolled compute workers.

How? Connect a compatible MCP client to Sidekick, then optionally adapt the included AGENTS.md template so the client knows how to use its persistent tools and knowledge.

For a local installation, configure the client to launch the packaged runtime:

{
  "mcpServers": {
    "sidekick": {
      "command": "npx",
      "args": ["-y", "github:geoffmcc/sidekick"]
    }
  }
}

See docs/local-deployment.md for persistent state locations, CLI commands, client notes, security, Compute, capability packs, and troubleshooting. Dedicated HTTP/SSE deployment remains documented in docs/installation.md.

Note: This project was developed using its own remote execution tools — the AI assistant used Sidekick's infrastructure to help build and test the very system it runs on.

Refactor Status and Compatibility Disclosure

Full disclosure: Sidekick's tool runtime uses a canonical descriptor registry, centralized dispatcher, request-scoped context, schema validation, source-aware policy, approval enforcement, redaction, and audit logging as its authoritative production path. All built-in handlers are owned by descriptor families, the data-utilities module, or the Compute subsystem; src/tools-legacy.js owns zero production handlers and is retained for policy/approval/audit compatibility machinery and re-exports. TOOL_DEFS and TOOLS are derived compatibility projections, not competing sources of truth. The broader platform convergence campaign remains in progress — see docs/platform-roadmap.md and docs/tool-architecture.md.

Canonical MCP tool names are unprefixed, such as bash, knowledge, and compute_jobs. The runtime still recognizes older sidekick_-prefixed names as compatibility aliases, but new documentation, policies, and integrations should use the bare names.

Quick Start

What you need: Node.js 22+, a remote Ubuntu/Debian machine with SSH access (VPS, home server, Raspberry Pi), Git, ~15 minutes.

# Clone the repo
git clone https://github.com/geoffmcc/sidekick.git
cd sidekick

# Copy env template and edit
copy .env.example .env
# Edit .env with your API key and settings

# Deploy to your remote machine (Windows)
.\deploy.ps1 -IP "YOUR_REMOTE_IP"

# Or deploy (Linux/Mac)
./deploy.sh -IP YOUR_REMOTE_IP

First deploy to a fresh VM: The script will automatically:

• Prompt for the initial SSH user (e.g., ubuntu, admin, root)
• Prompt for the initial user's password (once)
• Create the sidekick user and install Node.js 22
• Configure sudo permissions for service management
• Install and enable systemd services
• Install your SSH key for passwordless access
• Open firewall ports (if UFW is active)
• Deploy the application as a Git checkout at /home/sidekick/sidekick and start services

Optional: Install full infrastructure (Docker, databases, media tools, etc.):

# SSH into your remote machine
ssh sidekick@YOUR_REMOTE_IP

# Run the setup script
sudo bash scripts/setup-tools.sh

This installs PostgreSQL, Redis, Qdrant, InfluxDB, Grafana, and many other tools. See Optional Infrastructure for details.

Subsequent deploys are fully automated — no password required. Normal online deployments fetch origin/main from GitHub, fast-forward the remote main checkout, and verify that Git push is disabled with git remote set-url --push origin DISABLED.

For automation/CI, specify the initial user with -InitialUser:

# Windows
.\deploy.ps1 -IP "YOUR_REMOTE_IP" -InitialUser "ubuntu"

# Linux/Mac
./deploy.sh -IP YOUR_REMOTE_IP -InitialUser ubuntu

Airgap/Offline Deploy — If your remote server cannot reach GitHub (firewall, air-gapped network, etc.), explicitly use the --scp flag to sync files individually via SSH:

# Windows
.\deploy.ps1 -IP "YOUR_REMOTE_IP" -Scp

# Linux/Mac
./deploy.sh -IP YOUR_REMOTE_IP --scp

This copies files one-by-one from your local machine and does not create a Git working tree. No internet access is required on the remote server, but ops deploy_current_main requires the normal Git deployment model and will not silently fall back to SCP.

Open http://YOUR_REMOTE_IP:4098/ in a browser. That's it — Sidekick is live.

How It Works

Sidekick exposes its tool catalog through the Model Context Protocol and supports two deployment topologies:

Sidekick
├── Local deployment
└── Dedicated deployment

The intended local mode launches the full runtime through the packaged sidekick executable and stdio, without a dedicated Sidekick server. The packaged stdio entry point is under active maintenance, so run the local handshake tests before depending on it. Dedicated server installations continue to expose Streamable HTTP and legacy SSE with their existing authentication and service layout. Both topologies use the same governed registry, dispatcher, persistence, memory, workflows, capability packs, and Compute paths. The included AGENTS.md file is an optional, portable bootstrap template for clients that support persistent project or agent instructions.

1. An MCP client connects — it authenticates to the Sidekick MCP server on port 4097.
2. Sidekick publishes the available tool catalog — policy, risk, and approval rules are applied for the request source.
3. The assistant or agent calls tools — it can operate the remote machine, query knowledge, store durable context, or submit work to the Agent Bridge.
4. State persists — approved memories, project data, workflows, logs, and knowledge remain available after the client session ends.

Sidekick provides the persistent infrastructure; the connected assistant or agent decides when and how to use it. Exact prompting and automatic instruction-file loading depend on the MCP client.

Capability packs extend Sidekick with focused areas of competence without requiring every future feature to be part of Core. Packs can contribute modules, tools, workflows, knowledge, and configuration, and can be bundled with Sidekick or supplied by compatible third parties.

Usage

Exact invocation syntax varies by MCP client. At the protocol level, a direct call identifies a tool and supplies its arguments. For example:

{
  "name": "knowledge",
  "arguments": {
    "action": "search",
    "query": "debugging"
  }
}

Complex Multi-Step Tasks

A connected agent can combine multiple Sidekick tools to complete longer tasks. For example, an agent updating a stored project roadmap could:

1. Recall the current plan from persistent storage.
2. Inspect recent commits and CI results.
3. Update the plan with completion status and remaining work.
4. Store a handoff or revised plan for the next session.

The same workflow can emit notifications, create durable task records, or run through the Agent Bridge when autonomous execution is appropriate.

Project Continuity Across Sessions and Agents

The core continuity workflow: one agent or session does the work and leaves a durable handoff; a later session — possibly a different client or model entirely — retrieves it and continues without rebuilding context by hand.

1. Session A works on a project, storing durable facts with store, tracking decisions with context, and optionally opening an explicit envelope with session action="begin".
2. Before stopping, it leaves a handoff: resume action="set" project="myproject" with the summary, next step, and branch (or a richer handoff action="create" record).
3. Session B — hours or weeks later, on any compatible MCP client — starts with resume action="check" project="myproject", recalls context with project name="myproject" or context action="recall", and continues the work.

Retrieval is explicit: the connected agent has to ask for the handoff (the AGENTS.md template teaches it to check at session start). Sidekick stores and serves the state; it does not inject it automatically into a new client session.

Conversational Planning

Sidekick supports continuity across ordinary conversations because project facts, decisions, procedures, and handoffs can be retrieved in later sessions:

you: "We stored a plan, but it is now out of date."
agent: "I found the current project roadmap and recent implementation history. I can reconcile the completed work and revise the remaining steps."
you: "Update it."
agent: [reviews current evidence, updates the roadmap, and stores the revised handoff]

Debugging

Sidekick can combine source inspection, logs, database queries, service health, incident captures, and evidence-backed analysis to diagnose issues across the stack. Tool calls still pass through the same validation, policy, approval, redaction, and audit boundary.

Dashboard

Open http://YOUR_REMOTE_IP:4098/ for:

• System health monitoring
• Tool usage analytics and activity inspection
• Agent task submission and streaming
• Persistent data and structured memory management
• Approvals, tool catalog, Compute workers, jobs, and artifacts

What Makes Sidekick Different?

Most MCP servers are just tool wrappers—they give AI access to specific APIs or services. Sidekick is fundamentally different:

🧠 Persistent Memory Across Sessions

Sidekick provides durable project memory through SQLite-backed KV, context, and structured memory tables. Agents can explicitly store decisions, project facts, problems, patterns, and summaries, then retrieve them in later sessions by key, project, or context query. The Agent Bridge also records bounded, redacted structured memories for completed tasks and useful tool calls, then loads relevant remembered context before planning a new task.

📚 Knowledge Base

All documentation, best practices, and project context stored in a searchable database. The AI can query the knowledge base instead of re-reading files, saving tokens and improving accuracy.

📊 Built-in Metrics & Monitoring

Comprehensive metrics collection with Grafana dashboards:

• System health (CPU, memory, disk, load)
• Tool