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.

Related MCP server: hAIveMind MCP Server

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 usage analytics (call counts, success rates, average, p50, p95, p99, min, and max duration)

• Dispatcher phase latency (registry, resolution, validation, policy, approval, and handler timing) in redacted tool activity records

• Service status monitoring

• Database performance metrics

• Docker container stats

• Ollama LLM metrics

🔄 Evidence-Driven Workflow Learning

Sidekick can learn repeated successful workflows from redacted tool telemetry. teach stores reusable procedures composed from existing tools. evolve mines repeated bounded workflows, infers safe parameters, validates the procedure, and only after explicit approval exposes trial or active generated capabilities as namespaced MCP tools such as generated_<name>.

🤖 Durable Autonomous Operation

The Agent Bridge is a separate task execution surface with its own durable task projection. Submit a broad goal through the Agent tab or API and it normalizes the objective, records success criteria, selects capabilities from the live registry, plans and executes through the canonical dispatcher, records evidence, verifies the result, and returns a structured reusable product. Tasks support quick, standard, deep, persistent, and research profiles, pause, resume, cancel, guidance, approvals, follow-ups, governed child tasks, safe checkpoints, and conservative restart recovery. The Agent is separate from an MCP conversation, but it shares Sidekick's policy, approval, audit, redaction, Compute, capability, and dispatcher boundaries.

🖥️ Distributed Compute

Sidekick Compute enrolls authenticated worker agents and routes allowlisted chat, generate, and embeddings jobs (including certified OpenVINO NPU/CPU text-embedding jobs) across registered workers, providers, and models. It includes scoped worker credentials, job leases, progress, cancellation, retry/recovery, artifacts, health reporting, routing rules, and dashboard controls. It is intentionally not an arbitrary remote shell or a general-purpose GPU batch system.

🔒 Security-First Design

Every tool output is automatically scanned and redacted for sensitive data (API keys, tokens, passwords). The dashboard has rate limiting, CSRF protection, and audit logging. The agent bridge is isolated and only accessible through the dashboard.

🛠️ Governed Tool Catalog

Not just bash and file operations. Sidekick includes tools for:

• GitHub integration and read-only CI/check-run inspection

• Service and process management

• Scheduled tasks and monitoring

• Data transformation, validation, analytics, and evidence-backed reports

• Durable workflows, task sessions, handoffs, and orchestration

• Encrypted credential management

• Read-only configuration and secret exposure scanning

• Network diagnostics and troubleshooting

• Incident response and forensics

• Operational runbooks and procedures

• Dependency analysis and impact assessment

• Database operations (query, backup, restore, search, migrations)

• Media processing (OCR, transcription, video/audio conversion)

• Networking (Cloudflare tunnels, WireGuard, Nginx)

• Metrics collection and visualization

• Knowledge base and structured memory management

• Distributed allowlisted model jobs through enrolled Compute workers

• And much more

The result: Sidekick isn't just a tool server—it's an autonomous platform that learns, adapts, and grows with your workflow.

Self-Debugging in Action

Sidekick has used its own tools to test storage and recall behavior, investigate agent failure patterns with fresheyes, and diagnose Evolve workflow problems. These checks use the same public tool surface, dispatcher, policy, approval, redaction, and audit paths available to other connected clients.

What You Can Achieve

Architecture

┌──────────────────────────────────────────────────────────────┐
│  Local Machine (source of truth)                             │
│  git push → github.com/geoffmcc/sidekick                     │
│  ./deploy.ps1 → SSH into remote, git pull, restart           │
└──────────────────────────────────────────────────────────────┘
                           │
                           ▼
┌──────────────────────────────────────────────────────────────┐
│  Remote Machine (YOUR_REMOTE_IP)                             │
│                                                              │
│  ┌──────────────┐  ┌──────────────┐  ┌──────────────┐        │
│  │  MCP Server  │  │  Dashboard   │  │ Agent Bridge │        │
│  │  :4097       │  │  :4098       │  │  :4099       │        │
│  └──────┬───────┘  └──────┬───────┘  └──────┬───────┘        │
│         │                 │                 │                │
│         └─────────────────┼─────────────────┘                │
│                           │                                  │
│  ┌──────────────────────────────────────────────────────┐    │
│  │                    Data & Services Layer             │    │
│  │  ┌──────────┐  ┌──────────┐  ┌──────────┐            │    │
│  │  │  SQLite  │  │  Redis   │  │  Qdrant  │            │    │
│  │  │ (main DB)│  │ (cache)  │  │ (vector) │            │    │
│  │  └──────────┘  └──────────┘  └──────────┘            │    │
│  │  ┌──────────┐  ┌──────────┐  ┌──────────┐            │    │
│  │  │ InfluxDB │  │ Grafana  │  │  Ollama  │            │    │
│  │  │  :8086   │  │  :3000   │  │ :11434   │            │    │
│  │  └──────────┘  └──────────┘  └──────────┘            │    │
│  └──────────────────────────────────────────────────────┘    │
└──────────────────────────────────────────────────────────────┘

The Agent Bridge sends inference through Compute. Provider bootstrap can register Ollama, Groq, and OpenAI-compatible providers, but private conversations remain on eligible local/trusted providers by default and fail closed rather than silently reaching the cloud. Sidekick Compute workers are separate enrolled processes that connect to scoped /compute/worker/* routes on the MCP service; they are not additional always-on services inside the three-process core.

Data Layer

• SQLite — Primary database for KV store, tool logs, knowledge base, and metadata

• Redis — Session-scoped caching with TTL support

• Qdrant — Vector database for semantic search and embeddings

• InfluxDB — Time-series metrics collection (system health, tool usage, service status)

• Grafana — Metrics visualization with the dashboards provisioned in the repository

LLM Support

• Ollama (local) — Multiple models available:

  • qwen2.5-coder:7b — Default, optimized for code tasks

  • llama3.1:8b — General purpose reasoning

  • nomic-embed-text — Embedding model for semantic search

• Groq/OpenAI-compatible (cloud) — Available when configured and permitted by Compute placement policy

Services & Tools

All tools are exposed via the MCP server at http://YOUR_REMOTE_IP:4097/mcp.

Tool Categories

Core, module, capability-pack, and approved generated tools share one live registry. Use tools action="overview", tools action="search", or GET /api/tools for the current count, categories, schemas, risk, policy, and enabled state. Installing a capability pack adds its tools to the same registry. The repository includes these broad catalog families:

• Core — bash, tools, read, write, list, search, web_fetch, llm, respond

• Storage — store, get, delete, resume, list_projects, get_by_project, redis

• Database — db_schema, db_query, db_stats, db_backup, db_restore, db_export, log_query, db_search, db_migrate, db_diff, analytics

• Git & GitHub — git, github, ci_status

• Services — process, service, module, capability, workflow

• Scheduling — cron, delay

• Communication — notify, webhook

• Context & Learning — context, session, handoff, memory, teach, embed, ollama, memory_export, memory_import, memory_manage, sync_identity, sync_export, sync_import, sync_diff, knowledge

• Data Pipeline — transform, parse, diff, hash, validate, template, extract, anonymize, diff_files, insight_report

• Monitoring — health, status, watch, baseline, snapshot, timeline, black_box, netdiag, metrics

• Workflow — queue, retry, orchestrate, runbook, ops, mission

• Meta — evolve, predict, debug_tool, fresheyes

• Efficiency — batch, cache, summarize, filter, project, tail, find

• Security — secret, security_scan, sandbox

• Networking — tunnel, wireguard, nginx

• Development — changelog, depend

• Reliability — circuit

• Archive — archive

• Media — ocr, media, transcribe, download

• Compute — compute, compute_nodes, compute_providers, compute_models, compute_jobs, compute_route

Capability Packs

Sidekick Core does not have to absorb every future area of functionality. A capability pack is an installable area of competence — modules, workflow definitions, knowledge assets and configuration — installed, enabled, configured, upgraded and uninstalled through one lifecycle:

capability action="available"                    # bundled packs you can install
capability action="install"   name="developer"
capability action="enable"    name="developer"
capability action="health"    name="developer"
workflow   action="run" name="developer/repository-recon" inputs={ "path": "/srv/repo" }

or Dashboard → Capabilities.

The same lifecycle supports both bundled and compatible third-party packs. A third-party pack is installed from an approved server-local package path and is inspected before installation; its manifest identifies the publisher, provenance, version, contributed components and required permissions. Once installed, its modules and other contributions use the same registry, dispatcher, policy, approval, redaction and audit boundaries as built-in and bundled functionality. Installation and enablement execute package code inside the Sidekick process, so only install packs you trust and use the restricted tool policy plus approval requirements for shared or public-facing deployments.

For the package format, manifest requirements, inspection flow and lifecycle commands, see docs/capability-packs.md. To build your own compatible pack, follow the third-party capability-pack authoring guide.

Packs compose the subsystems Sidekick already has: pack tools are normal descriptors in the one registry with the one dispatcher, pack modules install through the module lifecycle, pack workflows register in the workflow definition registry, and pack knowledge lands in the ordinary knowledge base. There is no second plugin runtime and no remote marketplace.

The repository currently ships 27 bundled first-party packs, including Developer / Software Engineering, API Engineering, Backup and DR, Browser Automation, Container Operations, Database Administration, Documentation and Knowledge, Jellyfin, Network and Firewall, Proxmox VE, Security Research, and Testing and Quality. The exact installed, enabled, available, and healthy set is deployment-specific; use capability action="list" or capability action="catalog" rather than copying a fixed inventory. See docs/capability-packs.md, docs/developer-pack.md, docs/jellyfin-pack.md, docs/proxmox-pack.md and docs/container-operations-pack.md, docs/security-research-pack.md, plus docs/browser-automation.md.

Installing or enabling a pack activates executable module code inside the Sidekick process. Inspection never executes package code, and every installed package is integrity-verified before it loads — but there is no sandbox. Treat installing a third-party pack as equivalent to deploying code.

Semantic Repository Intelligence

The Developer pack includes a deterministic, hash-verifiable semantic repository index. semantic_repo and the enriched dev_repo_profile statically parse TypeScript, JavaScript, Ruby, Java, Go, Perl and Rust into a normalized, provenance-linked representation with bounded queries, incremental caching and semantic change summaries. Agent and Brain/context requests can retrieve the smallest relevant repository projection before governed source reads are needed. Repository content remains untrusted data, and indexing never executes target repository code. See docs/semantic-repository-intelligence.md for the IR, security model, limits and extension guidance.

Governed WSL Execution Node

Sidekick can run eligible canonical filesystem, Git, development, and semantic tools beside WSL-local repositories through an authenticated outbound execution node. The server retains canonical governance, approval, placement, audit, and recovery authority; the node independently validates descriptors, packs, workspaces, paths, and local limits. See docs/execution-node.md.

Black Box Incident Explorer

black_box stores profiled incident captures as structured SQLite records with source-level artifacts, observations, timelines, evidence-cited analysis, search, comparison, retention controls, and dashboard inspection. See docs/blackbox.md for profiles, schema, dashboard behavior, retention, export, and security notes.

Query the database for the complete tool list:

SELECT t.name, t.description, t.risk, tc.name as category
FROM tools t
LEFT JOIN tool_category_map tcm ON t.name = tcm.tool_name
LEFT JOIN tool_categories tc ON tcm.category_id = tc.id
WHERE t.enabled = 1 AND t.deprecated = 0
ORDER BY tc.sort_order, t.name

Understanding the Architecture

To avoid confusion, it's important to understand what each component is:

• Sidekick = The self-hosted agent platform: a governed live MCP catalog (core, module, pack, and approved generated tools) + persistent memory + knowledge base + Dashboard + Agent Bridge + metrics + Sidekick Compute + capability packs

• The assistant or agent = Any compatible MCP client, coding assistant, or automation agent that uses Sidekick's platform

• Tool runtime = The descriptor registry and dispatcher that validate, authorize, approve, execute, redact, and audit tool calls across MCP, dashboard, agent, scheduler, and generated-tool paths

• Agent Bridge = Sidekick's autonomous task runner, accessed through the Dashboard and API

• Knowledge Base = Structured documentation stored in SQLite, searchable via knowledge

• Sidekick Compute = The allowlisted worker/provider/model/job system for distributed inference workloads

• Module = A runtime implementation contributed to Sidekick: code that builds tool descriptors and reports health, managed through a full install/configure/enable/upgrade/uninstall lifecycle

• Workflow = A durable, reusable multi-step execution defined as data and run through the tool dispatcher, with checkpoints, project identity, cancellation and approval continuation

• Capability Pack = An installable area of competence composed from modules, workflows, knowledge and configuration. The repository currently bundles 27 first-party packs; use live capability discovery for exact installed state. See docs/capability-packs.md and docs/pack-proving.md.

• Connector = A managed relationship with an external service or system. GitHub is the current governed provider; broader connector health, mutation, dashboard coverage, and additional providers remain future work.

• Metrics System = InfluxDB + Grafana for system health, tool usage, and service monitoring

When a connected client calls Sidekick tools, the work executes through Sidekick on the remote machine. The assistant or agent chooses the operation; Sidekick supplies and governs the capability.

The Agent Bridge is a separate task system rather than another MCP collaborator. It is integrated with the platform kernel and canonical dispatcher, and is accessed through the Dashboard Agent tab or its API. Follow-ups and “Act on this” create fresh governed child tasks; stored model output never executes directly and prior approvals never transfer.

The Knowledge Base replaces the need for large markdown files. Instead of re-reading AGENTS.md or CONTEXT.md, the AI queries the database for specific information, saving tokens and improving accuracy.

Current boundaries:

• Sidekick Compute accepts only versioned, allowlisted model workloads; it is not arbitrary worker-side command execution.

• Evolve does not silently activate free-form code. Generated capabilities must pass validation and approval before trial or active exposure.

• The Agent Bridge acts only on submitted tasks, schedules, or watches and remains bounded by task profiles, model/tool budgets, wall-clock and idle limits, tool policy, approvals, checkpoint/recovery rules, verification, and the same dispatcher used by other execution paths.

• The module system's full lifecycle is implemented for first-party AND third-party modules: safe package inspection, a managed module store, verified entry-point loading with whole-package integrity, install/configure/enable/disable/upgrade/uninstall, and a derived health model. Installed module code is trusted executable code running in-process with Sidekick's privileges — there is no sandbox and none is claimed. The controls are integrity, provenance and lifecycle, not isolation. Treat installing a third-party pack as equivalent to deploying code.

• Capability packs compose existing subsystems; they are not a second plugin runtime, dispatcher or workflow engine. There is no remote marketplace: packs are installed from the bundled release copy or from an approved server-local path.

• Handler extraction out of src/tools-legacy.js is complete (zero production handlers remain there); the remaining platform convergence work is tracked in docs/platform-roadmap.md.

Security

Fresh .env.example configurations allow only loopback clients by default and use restricted tools with strict approval. Add explicit trusted client subnets to SIDEKICK_ALLOWED_IPS and SIDEKICK_DASHBOARD_ALLOWED_IPS before remote exposure. Dashboard identity bootstrap/login protects the UI and API; SIDEKICK_DASHBOARD_USER/SIDEKICK_DASHBOARD_PASS are optional legacy Basic Auth compatibility credentials. Existing installations keep their explicit environment values, including intentionally broad allowlists or open policy.

Capability Tool Warning: capability is critical-risk because installing or enabling a capability pack activates executable module code inside the Sidekick process. Inspection is safe and never executes package code, but installation and enablement are deployments. Packages are refused for path traversal, symlinks, escaping entry points, descriptor collisions, built-in tool shadowing and packaged secrets, and every installed package is integrity-verified before it loads — but none of that is a sandbox. For shared or public-facing deployments, set SIDEKICK_TOOL_POLICY=restricted and require approval for capability.

Evolve Tool Warning: evolve is critical-risk because it can approve and expose generated workflow tools. It does not treat free-text proposals as callable tools and generated capabilities must pass validation before trial activation. For shared or public-facing deployments, set SIDEKICK_TOOL_POLICY=restricted and require approval for evolve and high-risk generated tools.

Dashboard & Agent Bridge

Dashboard

Open http://YOUR_REMOTE_IP:4098/ in a browser.

• System — uptime, CPU, memory, disk, LLM status, service indicators (MCP, Agent, Ollama)

• Activity — operational telemetry for what Sidekick did. The default view groups tool calls into sessions using real session/task identifiers when present, with deterministic time/source fallback grouping when they are not available. Raw calls remain available for audit/debugging with filters for source, status, tool, project, session/task, duration, errors, and text search.

• Data — practical KV browser for what Sidekick stores. Entries include namespace, project, source, size, type, timestamps, previews, totals, and a persistent inspector with structured JSON/plain-text/Markdown-safe rendering plus guarded edit/delete actions.

• Memory — durable knowledge for what Sidekick learned and should remember. Facts, decisions, preferences, procedures, observations, unresolved items, and session summaries are separated from operational/tool-call records so telemetry does not dominate the default memory experience.

• Database — schema browser, query editor, full-text search, migration management

• Config — environment variables (sensitive values redacted)

• Agent — submit tasks for the AI agent to execute autonomously

• Approvals — review, approve, or reject queued risky actions when approval mode is enabled

• Tools — browsable catalog of built-in tools plus module-, pack- and approved generated tools, with search, category filtering, policy status, risk labels, and detailed argument info

• Capabilities — installed capability packs with version, publisher, provenance (first-party/third-party, bundled), state, health, integrity and configuration validity, plus contributed modules, tools, workflows and knowledge; available bundled packs; and inspection/installation from an approved server-local path. Actions: Details, Health Check, Enable, Disable, Upgrade, Uninstall. Every mutation dispatches the governed capability tool server-side.

• Compute — enrolled workers, providers, models, routing, jobs, artifacts, cancellation, retry, and lease recovery

• Metrics — embedded Grafana dashboards for system health, tool analytics, database performance, and Docker containers

Metrics & Monitoring

Sidekick includes comprehensive metrics collection and visualization:

Metrics Collection (runs every minute via sidekick-metrics.timer):

• System health: CPU, memory, disk, load average

• Tool usage: call counts, success rates, duration stats per tool

• Service status: MCP, Dashboard, Agent health

Grafana Dashboards (five provisioned from the repository):

1. Sidekick Overview — High-level system metrics and tool usage

2. Tool Analytics — Per-tool performance metrics with dynamic selectors

3. System Health — CPU, memory, disk usage over time

4. Database Performance — Query times, connection counts, cache hit ratios

5. Docker Containers — Container resource usage and health

Access Grafana directly at http://YOUR_REMOTE_IP:3000/ using sidekick and the configured SIDEKICK_GRAFANA_ADMIN_PASSWORD.

Knowledge Base

Sidekick includes a structured knowledge base for storing and retrieving project documentation:

• 35 packaged self-knowledge seed entries across categories: best-practices, architecture, operations, protocols, development

• Database-backed live content that can include imported, custom, or migrated entries beyond the packaged seed

• Full-text search with semantic similarity

• Manual import helper for migrating CONTEXT.md into structured knowledge entries

• Tool: knowledge for search, get, list, add, update, delete

Example queries:

# Search for debugging best practices
knowledge action="search" query="debugging"

# List all architecture entries
knowledge action="list" category="architecture"

# Get specific entry
knowledge action="get" id=18

Agent Bridge

The Agent at :4099 accepts a natural-language goal and creates one durable task projection. Live-state goals use governed tools; conceptual prompts may receive a direct answer. A durable task can normalize the goal, retain explicit criteria and requirements, shortlist capabilities from the current registry, execute a bounded plan, revise after evidence, checkpoint at safe boundaries, and independently verify the result. It produces a structured result alongside the readable transcript.

Task profiles are finite and bounded: quick, standard, deep, persistent, and research. The durable envelope records model/tool usage, failures, retries, plan revisions, checkpoints, workspace references, artifacts, verification, control events, and continuation operation fingerprints. A possibly completed mutation is not blindly repeated after recovery; the task parks for verification. The current Brain implementation also retains its provider-generation, plan-step, and legacy loop safety ceilings, so profile budgets are an outer durable envelope rather than a claim of unbounded execution.

Migrations 056_agent_tasks.sql and 057_agent_continuation.sql provide the durable task projection and the redacted control, artifact-reference, completed-operation, and ambiguous-operation recovery state. Migrations 058_agent_adaptive_durability.sql through 063_agent_escalation_decision_provenance.sql and 064_agent_learning_candidate_version.sql add bounded authority envelopes, profiles and root accounting, receipts, verification recipes, repair and hierarchical plans, workspace transactions, leases, continuations, learning review, and escalation provenance. The implementation is split across src/agent.js, src/agent/task-model.js, src/agent/task-store.js, src/agent/recovery-scan.js, src/agent/verification.js, and the existing platform-kernel execution path rather than introducing a second dispatcher.

Agent API

# Start a task
curl -X POST http://YOUR_REMOTE_IP:4099/api/agent/run \
  -H "Content-Type: application/json" \
  -d '{"goal": "check disk usage and store the result"}'

# Stream progress (SSE)
curl http://YOUR_REMOTE_IP:4099/api/agent/stream/{taskId}

# View history
curl http://YOUR_REMOTE_IP:4099/api/agent/history

# Inspect durable state and control a running task
curl http://YOUR_REMOTE_IP:4099/api/agent/tasks/{taskId}
curl -X POST http://YOUR_REMOTE_IP:4099/api/agent/tasks/{taskId}/pause
curl -X POST http://YOUR_REMOTE_IP:4099/api/agent/tasks/{taskId}/resume
curl -X POST http://YOUR_REMOTE_IP:4099/api/agent/tasks/{taskId}/guidance \
  -H "Content-Type: application/json" \
  -d '{"guidance":"Verify the result against current state before completing."}'

# Create a governed child from a selected result/finding/artifact
curl -X POST http://YOUR_REMOTE_IP:4099/api/agent/tasks/{taskId}/act-on \
  -H "Content-Type: application/json" \
  -d '{"kind":"verify","goal":"Verify the selected finding"}'

Optional Agent Bootstrap with AGENTS.md

AGENTS.md is a portable bootstrap template for clients and agents that support persistent instructions. It is not required by the MCP protocol and is not the primary documentation store. Its purpose is to point an agent toward Sidekick's connection details, searchable knowledge, current tool registry, and project continuity data.

The template includes:

• Connection and endpoint guidance

• Knowledge-base query examples

• Tool catalog and registry query examples

• Basic operating and safety instructions

Automatic loading behavior depends on the client. Copy, import, or adapt AGENTS.md using the instruction mechanism supported by your chosen MCP client.

Knowledge Base Categories

The knowledge base includes entries in these categories:

• best-practices — Interaction policies, debugging, tool selection, token efficiency

• architecture — Services, DB-first architecture, monitoring, tooling

• operations — Deployment, configuration, security, troubleshooting

• protocols — Context recall and other protocols

Query the knowledge base:

# List all categories
knowledge action="list"

# Search for specific topics
knowledge action="search" query="deployment"

# Get entries by category
knowledge action="list" category="best-practices"

Daily Workflow

# 1. Edit code in src/
# 2. Commit and push
git add -A
git commit -m "what you changed"
git push

# 3. Deploy (Windows)
.\deploy.ps1 -IP "YOUR_REMOTE_IP"

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

Or SSH directly to pull:

ssh sidekick@YOUR_REMOTE_IP
cd /home/sidekick/sidekick
git pull
sudo systemctl restart sidekick-mcp sidekick-dashboard sidekick-agent

Optional Infrastructure

Sidekick can be extended with additional services for enhanced capabilities:

Database Services

PostgreSQL (optional, alongside SQLite):

sudo systemctl start sidekick-postgres

• Full SQL database for complex queries and relational data

• Accessible via db_query with database="postgres"

Redis (session caching):

sudo systemctl start sidekick-redis

• Session-scoped caching with TTL

• Automatic fallback to in-memory cache if unavailable

Qdrant (vector database):

sudo systemctl start sidekick-qdrant

• Semantic search for context tool

• Embedding-based similarity search

Metrics & Monitoring

InfluxDB (time-series database):

sudo systemctl start sidekick-influxdb

• Stores system metrics, tool usage, service status

• Metrics collected every minute via sidekick-metrics.timer

Grafana (visualization):

sudo systemctl start sidekick-grafana

• Provisioned dashboards are defined under grafana/provisioning/dashboards/; discover the current set from those files rather than relying on a hard-coded count.

• Accessible at http://YOUR_REMOTE_IP:3000/ using sidekick and the configured SIDEKICK_GRAFANA_ADMIN_PASSWORD

• Embedded in Dashboard's Metrics tab through the authenticated dashboard Grafana proxy

Install All Services

Run the setup script to install the full tool stack:

sudo bash scripts/setup-tools.sh

This installs:

• Docker and Docker Compose

• PostgreSQL, Redis, Qdrant, InfluxDB, Grafana

• Media tools (ffmpeg, ImageMagick, Tesseract OCR)

• Development tools (Go, Python packages)

• Networking tools (Cloudflare tunnels, WireGuard, Nginx)

• And more...

Configuration

To change environment variables (ports, API keys, max iterations, etc.):

# 1. Edit .env locally
notepad .env

# 2. Deploy (syncs .env to remote and restarts services)
.\deploy.ps1 -IP "YOUR_REMOTE_IP"

The deploy script automatically syncs .env to the remote machine if it exists locally. No SSH required for config changes.

Deploy Script Options

First deploy: The script prompts for the initial SSH user if not provided, then prompts for their password once. It then bootstraps the VM (creates sidekick user, installs Node.js, configures sudoers, installs services, installs SSH key, and opens firewall ports). After that, deploys are fully automated with no password required.

Automation/CI: Specify the initial user with -InitialUser to skip the interactive prompt:

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

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

Security Model

The deploy script follows a two-phase security approach:

1. First deploy (password required): The script SSHs as the initial user (ubuntu/admin/root) and bootstraps the VM using SSH ControlMaster for connection multiplexing. This creates the sidekick user, installs Node.js, configures sudoers, installs systemd services, installs your SSH key, and opens firewall ports. All privileged operations require the initial user's password (prompted once via SSH ControlMaster).

2. Subsequent deploys (no password): The script SSHs as the sidekick user using SSH key authentication. Only minimal sudo permissions are used for service management (start/stop/restart/status) and log viewing. The sudoers file restricts the sidekick user to only these specific commands:

   • systemctl start/stop/restart/status sidekick-*

   • journalctl -u sidekick-*

   • ufw allow 4097/4098/4099

This follows the principle of least privilege: after initial setup, the sidekick user cannot reload systemd, enable/disable services, or modify the system in any way beyond managing the Sidekick services.

Project Structure

├── src/
│   ├── tools.js            Compatibility re-export for the modular tool runtime
│   ├── tools/
│   │   ├── index.js        Public tool facade and compatibility exports
│   │   ├── canonical-registry.js Canonical built-in descriptor registry
│   │   ├── canonical-order.js Compatibility ordering for built-in descriptors
│   │   ├── registry.js     Registry validation, materialization, and aliases
│   │   ├── dispatcher.js   Authoritative validation, policy, approval, execution, and audit path
│   │   ├── context.js      Request-scoped execution context
│   │   ├── dispatch-seam.js Dependency-free nested tool dispatch seam
│   │   └── families/       Descriptor-owned tool families (including Compute registration)
│   ├── tools-legacy.js     Compatibility policy/approval/audit machinery and re-exports
│   ├── modules/            Module lifecycle: manifest, discovery, packaging, managed store,
│   │                       verified entry loading, install/configure/enable/upgrade/uninstall,
│   │                       permissions, migrations, health (bundled: data-utilities)
│   ├── packs/              Capability-pack lifecycle: manifest, packaging, managed store,
│   │                       ownership, install/enable/upgrade/uninstall, derived health
│   ├── workflows/          Workflow definition registry, reference contract, and the runner
│   │                       over the kernel's execution primitives
│   ├── approvals/          Durable task-originated approval continuation (ADR stack)
│   ├── brain/              Bounded planner/verifier/synthesizer over governed Agent execution
│   ├── compute/            Worker, provider, model, job, routing, lease, and artifact system
│   ├── platform/           Platform kernel: executions, events, artifacts, projects,
│   │                       workspaces, connectors, and research record foundations
│   ├── memory.js           Automatic memory capture and recall helpers
│   ├── index.js            Application/bootstrap composition and Compute HTTP routes
│   ├── mcp/                MCP server, sessions, Streamable HTTP, and legacy SSE adapters
│   ├── dashboard.js        Dashboard bootstrap and route composition
│   ├── dashboard/          Dashboard route families, including auth/identity and approvals
│   ├── agent.js            Agent Bridge task loop, streaming, delays, and watches
│   ├── redact.js           Sensitive data redaction
│   ├── db.js               SQLite core database layer and transaction/migration ownership
│   ├── db/                 Focused persistence stores such as handoff/task-session storage
│   ├── pg.js               PostgreSQL support
│   ├── redis.js            Redis client for caching
│   ├── qdrant.js           Qdrant vector DB client for semantic search
│   └── crypto-utils.js     Timing-safe comparison helpers
├── packs/
│   ├── browser-automation/  Bundled Governed Browser Automation capability pack
│   ├── developer/           Bundled Developer / Software Engineering capability pack
│   ├── jellyfin/            Bundled Jellyfin capability pack
│   ├── container-operations/ Bundled Docker / Podman Container Operations pack
│   ├── proxmox/             Bundled Proxmox VE capability pack
│   └── security-research/   Bundled Security Research capability pack
├── scripts/
│   ├── bootstrap.sh    VM bootstrap script (creates user, installs Node.js, etc.)
│   ├── setup-tools.sh  Server tooling setup (Docker, databases, media tools, etc.)
│   ├── collect-metrics.js  Metrics collection script (runs via cron)
│   └── seed-knowledge.js   Seed the knowledge base on fresh deployments
├── systemd/
│   ├── sidekick-mcp.service       MCP server systemd unit
│   ├── sidekick-dashboard.service Dashboard systemd unit
│   ├── sidekick-agent.service     Agent bridge systemd unit
│   ├── sidekick-postgres.service  PostgreSQL Docker wrapper
│   ├── sidekick-redis.service     Redis Docker wrapper
│   ├── sidekick-qdrant.service    Qdrant Docker wrapper
│   ├── sidekick-influxdb.service  InfluxDB Docker wrapper
│   ├── sidekick-grafana.service   Grafana Docker wrapper
│   └── sidekick-sudoers           Sudoers config for sidekick user
├── docker/
│   └── docker-compose.yml  Docker services (Postgres, Redis, Qdrant, InfluxDB, Grafana)
├── grafana/
│   ├── provisioning/       Grafana auto-provisioning configs
│   └── dashboards/         Provisioned Grafana dashboards
├── migrations/             57 ordered SQLite migrations: core schema, tool registry,
│                           structured memory, Black Box, platform kernel, Compute,
│                           approvals, modules, projects, events, connectors, research records
├── packaging/              Compute worker OS-service installers (systemd, launchd, winsw)
├── data/               Runtime data (on remote: logs, KV, conversations, metrics)
├── deploy.ps1          Deploy script (Windows)
├── deploy.sh           Deploy script (Linux/Mac)
├── .env.example        Environment variable template
└── AGENTS.md           Optional portable agent bootstrap template

Troubleshooting

Deploy script fails with "SSH key not found": The script will automatically generate an SSH key if one doesn't exist at ~/.ssh/sidekick.

Deploy script fails with SSH connection error: On first deploy, you'll need to install the SSH key. The script will prompt you for the sidekick password automatically.

Deploy script fails with "sudoers setup failed": Ensure the sidekick user exists on the remote machine and has sudo access. The script will prompt for the password to configure passwordless sudo for service management.

MCP connection issues: If you see "Server not initialized" errors, restart the MCP service:

sudo systemctl restart sidekick-mcp

Dashboard won't load: Check that the dashboard service is running:

sudo systemctl status sidekick-dashboard

Services not starting: Check the logs:

sudo journalctl -u sidekick-mcp -n 50
sudo journalctl -u sidekick-dashboard -n 50
sudo journalctl -u sidekick-agent -n 50

Get Started

1. Clone the repo

2. Copy .env.example → .env and fill in your values

3. Run .\deploy.ps1 -IP "YOUR_REMOTE_IP" (Windows) or ./deploy.sh -IP YOUR_REMOTE_IP (Linux/Mac)

4. Enter the sidekick password when prompted (first deploy only)

5. Open http://YOUR_REMOTE_IP:4098/ and explore your new autonomous agent platform

That's it. Sidekick is live.

License: GNU General Public License v3.0 only (GPL-3.0-only) · See LICENSE for details.

Copyright: © 2026 Geoffrey McClinsey.

Contributing: PRs welcome.

Issues: Open one if you find a bug or have a feature request.