{"slug": "probably-just-end-up-embarrassing-myself-but-here-is-sidekick", "title": "Probably just end up embarrassing myself, but here is Sidekick", "summary": "Developer Geoff McCaughan released Sidekick, a self-hosted AI agent platform with persistent memory and 70 MCP tools that can extend itself without code changes. The platform runs on a remote machine, learns from user workflows, and provides autonomous agent capabilities via a single AGENTS.md file read by opencode. Sidekick distinguishes itself from other MCP servers by offering persistent memory, tool generation, and an independent Agent Bridge for complex tasks.", "body_md": "**Autonomous Agent Platform**\n\nA self-hosted AI agent platform with persistent memory, 70 MCP tools, and the ability to extend itself. Runs on your remote machine, learns from your workflow, and grows its own capabilities—no code changes required.\n\n**How?** A single `AGENTS.md`\n\nfile that opencode reads on every session start. No plugins, no hooks — just markdown.\n\nNote: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.\n\n**What you need:** Node.js 22+, a remote Ubuntu/Debian machine with SSH access (VPS, home server, Raspberry Pi), Git, ~15 minutes.\n\n```\n# Clone the repo\ngit clone https://github.com/geoffmcc/sidekick.git\ncd sidekick\n\n# Copy env template and edit\ncopy .env.example .env\n# Edit .env with your API key and settings\n\n# Deploy to your remote machine (Windows)\n.\\deploy.ps1 -IP \"YOUR_REMOTE_IP\"\n\n# Or deploy (Linux/Mac)\n./deploy.sh -IP YOUR_REMOTE_IP\n```\n\n**First deploy to a fresh VM:** The script will automatically:\n\n- Prompt for the initial SSH user (e.g., ubuntu, admin, root)\n- Prompt for the initial user's password (once)\n- Create the sidekick user and install Node.js 20 LTS\n- Configure sudo permissions for service management\n- Install and enable systemd services\n- Install your SSH key for passwordless access\n- Open firewall ports (if UFW is active)\n- Deploy the application and start services\n\n**Subsequent deploys** are fully automated — no password required.\n\n**For automation/CI**, specify the initial user with `-InitialUser`\n\n:\n\n```\n# Windows\n.\\deploy.ps1 -IP \"YOUR_REMOTE_IP\" -InitialUser \"ubuntu\"\n\n# Linux/Mac\n./deploy.sh -IP YOUR_REMOTE_IP -InitialUser ubuntu\n```\n\n**Airgap/Offline Deploy** — If your remote server cannot reach GitHub (firewall, air-gapped network, etc.), use the `--scp`\n\nflag to sync files individually via SSH:\n\n```\n# Windows\n.\\deploy.ps1 -IP \"YOUR_REMOTE_IP\" -Scp\n\n# Linux/Mac\n./deploy.sh -IP YOUR_REMOTE_IP --scp\n```\n\nThis uses the original SCP-based approach, copying files one-by-one from your local machine. No internet access required on the remote server.\n\nOpen `http://YOUR_REMOTE_IP:4098/`\n\nin a browser. That's it — Sidekick is live.\n\nEvery time you open opencode, it automatically reads `~/.config/opencode/AGENTS.md`\n\nand loads whatever instructions are in it into the AI's context. Sidekick provides the infrastructure — remote execution tools, persistent memory, and an autonomous agent — that the AI can use.\n\n**You open opencode**— it reads`AGENTS.md`\n\n**Sidekick's tools and instructions are loaded**— the AI now knows about the remote machine, the tools, and how to use them** You work**— the AI can call sidekick tools to execute commands on the remote machine, store/retrieve persistent data, or you can submit tasks to the autonomous Agent Bridge via the dashboard**Session ends**— but anything stored in Sidekick's KV persists for next time\n\nSidekick is the infrastructure. The AI (running in opencode) uses that infrastructure to help you work. Without `AGENTS.md`\n\n, the AI doesn't know Sidekick exists. With it, the AI has persistent remote capabilities.\n\nMost MCP servers are just tool wrappers—they give AI access to specific APIs or services. Sidekick is fundamentally different:\n\nSidekick remembers everything. Your decisions, project context, API responses, workflow patterns—it all persists in a structured KV store organized by project. The AI doesn't start from scratch every session.\n\nTeach Sidekick new procedures, and it can generate its own tools. The `sidekick_teach`\n\ntool lets you describe a workflow in natural language, and Sidekick creates the implementation. It's not just using tools—it's building them.\n\nThe Agent Bridge runs independently from your main AI session. Submit a complex task via the dashboard, and Sidekick will plan, execute, and iterate until it's done—without you babysitting each step.\n\n**Context tracking**- Automatically recalls relevant past decisions and patterns** Health monitoring**- Real-time system health checks with scoring** Predictive analysis**- Identifies patterns in your workflow and suggests improvements** Event-driven automation**- Watches for conditions and triggers actions automatically\n\nEvery 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.\n\nNot just bash and file operations. Sidekick includes tools for:\n\n- GitHub integration (PRs, issues, releases)\n- Service and process management\n- Scheduled tasks and monitoring\n- Data transformation and validation\n- Multi-agent orchestration\n- Encrypted credential management\n- Network diagnostics and troubleshooting\n- Incident response and forensics\n- Operational runbooks and procedures\n- Dependency analysis and impact assessment\n**Database operations (query, backup, restore, search, migrations)**- And much more\n\n**The result:** Sidekick isn't just a tool server—it's an autonomous platform that learns, adapts, and grows with your workflow.\n\nSidekick used its own tools to help develop itself. Here's the AI agent debugging Sidekick from within opencode:\n\n**Testing the debug tool's store/cleanup/recall cycle:**\n\n**Diagnosing its own hallucination problem with sidekick_fresheyes:**\n\n**Investigating why the self-improvement tool isn't working:**\n\n| Capability | How | Why AGENTS.md Matters |\n|---|---|---|\nRemote code execution |\n`sidekick_bash` runs commands on a persistent remote machine |\nInstructions tell the AI when and how to use it |\nPersistent memory across sessions |\n`sidekick_store` / `sidekick_get` — KV storage that survives restarts |\nAI knows which keys to store and retrieve |\nAutonomous multi-step tasks |\nAgent bridge at `:4099` plans and executes until done |\nAI knows to delegate complex work to the agent |\nCode review |\nAsk the AI to review diffs using remote execution tools | Decision tree in AGENTS.md tells the AI when to use sidekick tools for review |\nGitHub integration |\nStored tokens let sidekick create repos, push code, manage PRs | AGENTS.md tells the AI where to find credentials |\nLive monitoring dashboard |\nWeb UI at `:4098` — system health, activity, KV data, agent tasks |\nAlways accessible, no config needed |\nWeb scraping from remote |\n`sidekick_web_fetch` bypasses local network restrictions |\nAI knows to use remote machine for fetching when needed |\nLLM on demand |\nCloud Groq for speed, local Ollama as fallback | AI knows which to use and when |\nFile content search |\n`sidekick_search` uses ripgrep/grep for fast code search |\nAI can quickly find code patterns across the codebase |\nGit operations |\n`sidekick_git` provides structured git commands |\nAI can check status, diff, log, commit, push, pull safely |\nNotifications |\n`sidekick_notify` sends alerts to Discord, Slack, or email |\nAI can alert you when tasks complete or errors occur |\nProcess management |\n`sidekick_process` lists, monitors, and kills processes |\nAI can troubleshoot high CPU/memory or kill hung processes |\nService management |\n`sidekick_service` controls systemd services safely |\nAI can restart services, check status, view logs |\nArchive operations |\n`sidekick_archive` creates/extracts tar.gz and zip files |\nAI can backup data, deploy archives, manage backups |\nScheduled tasks |\n`sidekick_cron` schedules recurring jobs via crontab |\nAI can set up automated health checks, backups, monitoring |\nGitHub automation |\n`sidekick_github` manages PRs, issues, releases via API |\nAI can automate PR workflows, track issues, create releases |\nWebhook integration |\n`sidekick_webhook` receives and stores external webhooks |\nAI can react to GitHub events, CI/CD pipelines, external alerts |\nPersistent context |\n`sidekick_context` tracks projects, decisions, problems, patterns |\nAI can recall past context, get suggestions, maintain continuity across sessions |\nSelf-extension |\n`sidekick_teach` teaches procedures, generates tools, learns from examples |\nAI can grow its own capabilities without code changes |\n\n```\n┌─ Local Machine (source of truth) ─────────────────────┐\n│  git push → github.com/geoffmcc/sidekick               │\n│  ./deploy.ps1 → SSH into remote, git pull, restart     │\n└────────────────────────────────────────────────────────┘\n                          │\n                          ▼\n┌─ Remote Machine (YOUR_REMOTE_IP) ─────────────────────────┐\n│                                                        │\n│  ┌─────────────┐  ┌──────────────┐  ┌──────────────┐  │\n│  │  MCP Server  │  │  Dashboard   │  │ Agent Bridge │  │\n│  │  :4097       │  │  :4098       │  │  :4099       │  │\n│  └──────┬───────┘  └──────┬───────┘  └──────┬───────┘  │\n│         │                  │                  │          │\n│         └──────────────────┼──────────────────┘          │\n│                            │                             │\n│         ┌──────────────────▼──────────────┐              │\n│         │        Ollama :11434            │              │\n│         │     Model: phi3:mini (2.2GB)    │              │\n│         └─────────────────────────────────┘              │\n└────────────────────────────────────────────────────────┘\n```\n\n*The agent bridge also supports Groq cloud API — when GROQ_API_KEY is set, it uses Groq instead of Ollama for near-instant LLM responses.*\n\n| Service | Port | Description |\n|---|---|---|\nMCP Server |\n4097 | 70 tools: bash, read, write, list, search, git, notify, process, service, archive, cron, github, webhook, context, teach, store, get, list_projects, get_by_project, web_fetch, llm, transform, health, delay, snapshot, watch, secret, parse, diff, hash, validate, template, queue, retry, evolve, orchestrate, predict, debug_tool, fresheyes, batch, cache, summarize, filter, project, tail, diff_files, find, status, extract, anonymize, sandbox, changelog, netdiag, timeline, circuit, baseline, depend, runbook, black_box, respond, db_schema, db_query, db_stats, db_backup, db_restore, log_query, db_export, db_search, db_migrate, db_diff |\nDashboard |\n4098 | Web UI: system health, activity log, KV data, agent tasks |\nAgent Bridge |\n4099 | AI agent loop — LLM plans and calls MCP tools autonomously |\nOllama |\n11434 | Local LLM inference (phi3:mini). Fallback when no `GROQ_API_KEY` |\n\nAll tools are exposed via the MCP server at `http://YOUR_REMOTE_IP:4097/mcp`\n\n.\n\n— Inspect database schema: tables, columns, indexes, foreign keys.`sidekick_db_schema`\n\n— Raw SQL with safety limits (readonly by default, row caps, timeout).`sidekick_db_query`\n\n— DB size, table sizes, WAL status, cache hit ratio.`sidekick_db_stats`\n\n— Timestamped backup with gzip compression.`sidekick_db_backup`\n\n— Restore from backup with integrity check (auto-backup before restore).`sidekick_db_restore`\n\n— Advanced tool_logs filtering by time, tool, source, status.`sidekick_log_query`\n\n— Export tables to JSON, CSV, or SQL dump.`sidekick_db_export`\n\n— Full-text search across all tables (auto-creates FTS5 indexes).`sidekick_db_search`\n\n— Schema migrations with versioning and rollback.`sidekick_db_migrate`\n\n— Compare two DB snapshots, show what changed.`sidekick_db_diff`\n\n— Replace sensitive data with realistic fake values. Consistent mapping, custom patterns, redact safety net.`sidekick_anonymize`\n\n— Execute operations with automatic file backup and rollback. Safe experimentation on remote systems.`sidekick_sandbox`\n\n— Generate release notes from git history. Groups by type/scope/author, optional LLM summaries.`sidekick_changelog`\n\n— Unified network diagnostics: DNS, routing, port scanning, connectivity checks, local listeners.`sidekick_netdiag`\n\n— Build chronological timelines from multiple sources (log.jsonl, journalctl, git, files).`sidekick_timeline`\n\n— Generic circuit breaker for any tool call. Fast-fail when targets are down, configurable thresholds.`sidekick_circuit`\n\n— Behavioral baseline and anomaly detection. Learns patterns, detects statistical deviations.`sidekick_baseline`\n\n— Dependency analyzer for npm, systemd services, processes. Trees, reverse deps, impact analysis.`sidekick_depend`\n\n— Operational runbook executor with autonomous and guided modes. Verification, rollback, step-by-step.`sidekick_runbook`\n\n— Incident time capsule capturing full system context. Rate limited (5/day, 7-day TTL, 3 active max).`sidekick_black_box`\n\n— Execute multiple tool calls in one request to reduce API round-trips (max 20 per batch).`sidekick_batch`\n\n— Session-scoped caching to avoid redundant operations. Store and retrieve values with TTL.`sidekick_cache`\n\n— Summarize large files before returning to reduce token usage. Strategies: head, tail, grep, stats.`sidekick_summarize`\n\n— Filter file contents or directory listings by pattern, date, or size before returning.`sidekick_filter`\n\n— Get complete project context in one call: KV entries, context tracking, recent logs, procedures.`sidekick_project`\n\n— Tail recent log entries with filtering. Sources: log.jsonl, journalctl, or any file.`sidekick_tail`\n\n— Compare two files directly without reading both into context. Returns unified diff or summary.`sidekick_diff_files`\n\n— Advanced file finder: search by name pattern, date range, size range, and content pattern.`sidekick_find`\n\n— Unified system status: services, disk, memory, load, uptime, top processes in one call.`sidekick_status`\n\n— Parse JSON/YAML/INI/XML and extract specific fields by path. Returns only what you need.`sidekick_extract`\n\n— Self-modification with safety: analyze tool usage patterns, propose improvements, test and approve changes. Automatically implements approved proposals (creates documentation and teaches procedures). Rate limited to 10 proposals per day.`sidekick_evolve`\n\n**Requires explicit tool policy restrictions to prevent automatic implementation.**— Multi-agent coordination: create task graphs, execute subtasks with dependencies, track progress across all subtasks.`sidekick_orchestrate`\n\n— Anticipatory intelligence: analyze context and tool patterns, predict needs, track prediction usefulness via feedback.`sidekick_predict`\n\n— Validate data against JSON Schema using ajv. Returns detailed error messages with paths.`sidekick_validate`\n\n— Render Handlebars templates with data for config generation and dynamic content.`sidekick_template`\n\n— Persistent task queue with priorities, status tracking, and automatic retry tracking.`sidekick_queue`\n\n— Retry wrapper for any tool call with exponential/linear/fixed backoff strategies.`sidekick_retry`\n\n— Parse structured data formats (JSON, YAML, XML, INI, CSV) with auto-detection.`sidekick_parse`\n\n— Semantic comparison of text, JSON, or YAML with structure-aware diffing.`sidekick_diff`\n\n— Generate checksums (MD5, SHA1, SHA256, SHA512) for files or data with verification.`sidekick_hash`\n\n— Data manipulation pipeline: filter, extract, sort, format, and map data.`sidekick_transform`\n\n— Composite system health checks with scoring and issue detection.`sidekick_health`\n\n— One-shot task scheduling: run a tool once at a specific time or after a delay.`sidekick_delay`\n\n— Capture system state and detect drift by comparing snapshots.`sidekick_snapshot`\n\n— Event-driven monitoring: watch services, processes, endpoints, or files and trigger actions on conditions.`sidekick_watch`\n\n— Encrypted credential management with AES-256-GCM (requires SIDEKICK_SECRET_KEY in .env).`sidekick_secret`\n\n— Meta-learning and self-extension: teach procedures, generate tools from descriptions, learn from examples, execute learned workflows. Enables sidekick to grow its own capabilities.`sidekick_teach`\n\n— Persistent intelligent context management: track projects, decisions, problems, patterns; recall and suggest based on past context. Uses semantic similarity search.`sidekick_context`\n\n— Schedule recurring tasks: add, list, remove, run jobs. Uses system crontab for scheduling.`sidekick_cron`\n\n— Full GitHub API integration: PRs (list/create/get/merge), issues (list/create/close), commit status, releases, repo info. Uses stored`sidekick_github`\n\n`github_token`\n\n.— Receive and manage webhooks: list, get, clear. Webhook endpoint at`sidekick_webhook`\n\n`POST /api/webhook/:source`\n\non dashboard.\n\n— Manage processes: list, top CPU/memory consumers, kill by PID/name, process tree.`sidekick_process`\n\n— Manage systemd services: start, stop, restart, status, enable, disable, view logs.`sidekick_service`\n\n— Create, extract, or list archives (tar.gz, tgz, zip).`sidekick_archive`\n\n— Fast file content search using ripgrep (falls back to grep). Supports regex patterns and file filtering.`sidekick_search`\n\n— Structured git operations: status, diff, log, add, commit, push, pull, branch, checkout, stash. Safer than raw bash for git commands.`sidekick_git`\n\n— Send notifications to Discord, Slack (via webhooks), or email (via SMTP). Useful for alerts and monitoring.`sidekick_notify`\n\nTo avoid confusion, it's important to understand what each component is:\n\n**Sidekick**= The autonomous agent platform: remote machine + 70 MCP tools + persistent memory + Dashboard + Agent Bridge + self-extending capabilities**The AI**= The assistant running in opencode (e.g., qwen, Claude, etc.) that uses Sidekick's platform** Agent Bridge**= Sidekick's autonomous agent that runs tasks independently via the Dashboard\n\nWhen you call sidekick tools in opencode, you're executing commands on the remote machine. The AI makes the decisions; Sidekick provides the capabilities.\n\nThe Agent Bridge is a separate system that can run tasks autonomously, but it's not integrated into the main AI's workflow. It's accessed via the Dashboard's Agent tab or direct API calls.\n\n**What Sidekick does NOT do (currently):**\n\n- It does not provide multi-AI collaboration (the main AI cannot consult the Agent Bridge and get responses back)\n- It does not make decisions on its own (the AI in opencode makes all decisions)\n- It is not a separate AI entity (it's infrastructure that the AI uses)\n\n| Layer | Measure |\n|---|---|\nMCP Server |\nBearer token auth + IP whitelist (`SIDEKICK_ALLOWED_IPS` ) + dangerous command blocklist + configurable tool policy |\nDashboard |\nHTTP Basic Auth (`SIDEKICK_DASHBOARD_USER` /`PASS` ) + rate limiting + CSRF protection + audit logging + tool policy visibility |\nAgent Bridge |\nBinds to `127.0.0.1` only, accessible exclusively through the dashboard proxy |\nSidekick user |\nSudo restricted to service management commands only (no wildcard `ALL` ) |\nInfrastructure |\nSSH key-only, fail2ban, UFW, unattended-upgrades, `.env` file permissions locked to owner |\nData Redaction |\nAll tool outputs automatically redact SSH keys, GitHub tokens, API keys, passwords, database URLs, etc. |\n\nThe dashboard auth and IP whitelist are disabled by default (empty env var = no restriction). Set them in `.env`\n\nbefore exposing to the internet. For shared or public-facing deployments, set `SIDEKICK_TOOL_POLICY=restricted`\n\nand explicitly allow only the high-risk tools your workflow needs.\n\n** ⚠️ Evolve Tool Warning:** The\n\n`sidekick_evolve`\n\ntool can automatically implement approved proposals (creating documentation files and teaching procedures). If your tool policy is `open`\n\n, evolve will execute these implementations without additional approval. For shared or public-facing deployments, set `SIDEKICK_TOOL_POLICY=restricted`\n\nto require explicit tool allowlisting before evolve can create or use tools.Open `http://YOUR_REMOTE_IP:4098/`\n\nin a browser.\n\n**System**— uptime, CPU, memory, disk, LLM status, service indicators (MCP, Agent, Ollama)** Activity**— live tool call log with source badges (mcp/agent/dashboard)** Data**— KV store contents with project filtering, age filtering, and expandable previews** Config**— environment variables (sensitive values redacted)** Agent**— submit tasks for the AI agent to execute autonomously** Tools**— browsable catalog of all 70 tools with search, category filtering, policy status, risk labels, and detailed argument info\n\nThe agent at `:4099`\n\ntakes a natural-language goal and runs an autonomous loop:\n\n- Sends goal + tool definitions to the LLM (Groq cloud or local Ollama)\n- LLM responds with a tool call decision\n- Bridge executes the tool via MCP\n- Feeds result back to LLM\n- Repeats until the task is complete\n\n```\n# Start a task\ncurl -X POST http://YOUR_REMOTE_IP:4099/api/agent/run \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\"goal\": \"check disk usage and store the result\"}'\n\n# Stream progress (SSE)\ncurl http://YOUR_REMOTE_IP:4099/api/agent/stream/{taskId}\n\n# View history\ncurl http://YOUR_REMOTE_IP:4099/api/agent/history\n```\n\nThis is the most important step.Without this file, Sidekick is just a tool server. With it, Sidekick's tools and instructions are loaded into every opencode session.\n\nCreate or edit `~/.config/opencode/AGENTS.md`\n\nwith the following structure (replace placeholders with your values):\n\n```\n# Sidekick Configuration\n\n## Connection\n- IP: YOUR_REMOTE_IP\n- MCP Server: port 4097\n- Dashboard: port 4098\n- Agent Bridge: port 4099\n\n## Credentials\n- GitHub token stored in KV key: `github_token`\n- Use `sidekick_get(\"github_token\")` to retrieve it for GitHub API calls\n\n## Usage\n- `sidekick_bash` — Run commands on the remote machine\n- `sidekick_store` / `sidekick_get` — Persistent KV storage\n- `sidekick_read` / `sidekick_write` — File operations\n- `sidekick_git` — Git operations\n- `task` subagent — Delegate complex multi-step tasks\n```\n\n**opencode reads this file automatically on every session start.** No plugins, no hooks, no manual loading — just a markdown file in the right place.\n\nFor the full AGENTS.md template with detailed usage guidelines, see [ AGENTS.md](/geoffmcc/sidekick/blob/main/AGENTS.md) in this repo.\n\n```\n# 1. Edit code in src/\n# 2. Commit and push\ngit add -A\ngit commit -m \"what you changed\"\ngit push\n\n# 3. Deploy (Windows)\n.\\deploy.ps1 -IP \"YOUR_REMOTE_IP\"\n\n# Or deploy (Linux/Mac)\n./deploy.sh YOUR_REMOTE_IP\n```\n\nOr SSH directly to pull:\n\n```\nssh sidekick@YOUR_REMOTE_IP\ncd /home/sidekick/sidekick\ngit pull\nsudo systemctl restart sidekick-mcp sidekick-dashboard sidekick-agent\n```\n\nTo change environment variables (ports, API keys, max iterations, etc.):\n\n```\n# 1. Edit .env locally\nnotepad .env\n\n# 2. Deploy (syncs .env to remote and restarts services)\n.\\deploy.ps1 -IP \"YOUR_REMOTE_IP\"\n```\n\nThe deploy script automatically syncs `.env`\n\nto the remote machine if it exists locally. No SSH required for config changes.\n\n| Option | Description |\n|---|---|\n`-IP` |\nRemote machine IP address (default: `192.168.1.10` ) |\n`-InitialUser` |\nInitial SSH user for bootstrap (e.g., ubuntu, admin, root) |\n\n**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.\n\n**Automation/CI:** Specify the initial user with `-InitialUser`\n\nto skip the interactive prompt:\n\n```\n# Windows\n.\\deploy.ps1 -IP \"192.168.1.10\" -InitialUser \"ubuntu\"\n\n# Linux/Mac\n./deploy.sh -IP 192.168.1.10 -InitialUser ubuntu\n```\n\nThe deploy script follows a two-phase security approach:\n\n-\n**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). -\n**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-*`\n\n`journalctl -u sidekick-*`\n\n`ufw allow 4097/4098/4099`\n\nThis 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.\n\n| Variable | Default | Description |\n|---|---|---|\n`SIDEKICK_API_KEY` |\n— | API key for MCP server auth |\n`SIDEKICK_ALLOWED_IPS` |\n— | Comma-separated IP whitelist for MCP server (empty = allow all) |\n`SIDEKICK_PORT` |\n4097 | MCP server port |\n`SIDEKICK_DASHBOARD_PORT` |\n4098 | Dashboard port |\n`SIDEKICK_AGENT_PORT` |\n4099 | Agent bridge port |\n`SIDEKICK_DASHBOARD_USER` |\n— | Dashboard basic auth username (empty = disabled) |\n`SIDEKICK_DASHBOARD_PASS` |\n— | Dashboard basic auth password (empty = disabled) |\n`SIDEKICK_DATA_DIR` |\n`./data` |\nData directory for logs, KV, conversations |\n`SIDEKICK_TOOL_POLICY` |\n`open` |\nTool policy mode: `open` or `restricted` |\n`SIDEKICK_BLOCKED_TOOLS` |\n— | Comma-separated global blocklist of tool names or risk selectors |\n`SIDEKICK_ALLOWED_TOOLS` |\n— | Comma-separated global allowlist of tool names or risk selectors |\n`SIDEKICK_AGENT_TOOL_POLICY` |\n— | Source-specific tool policy override for the Agent Bridge |\n`SIDEKICK_MCP_TOOL_POLICY` |\n— | Source-specific tool policy override for MCP clients |\n`SIDEKICK_DASHBOARD_TOOL_POLICY` |\n— | Source-specific tool policy override for dashboard-originated calls |\n`OLLAMA_URL` |\n`http://127.0.0.1:11434` |\nOllama API URL (local fallback) |\n`GROQ_API_KEY` |\n— | Groq API key for cloud LLM (empty = use local Ollama) |\n`GROQ_MODEL` |\n`llama3-8b-8192` |\nGroq model name |\n`SIDEKICK_MAX_ITERATIONS` |\n`15` |\nMax agent loop iterations (safety limit) |\n\n```\n├── src/\n│   ├── tools.js        Shared tool handlers (extracted from index.js)\n│   ├── index.js        MCP server (session-aware transport management)\n│   ├── dashboard.js    Dashboard web UI (source tagging, Font Awesome icons)\n│   ├── agent.js        Agent bridge (LLM tool-use loop, direct tool calls)\n│   └── redact.js       Sensitive data redaction\n├── scripts/\n│   └── bootstrap.sh    VM bootstrap script (creates user, installs Node.js, etc.)\n├── systemd/\n│   ├── sidekick-mcp.service       MCP server systemd unit\n│   ├── sidekick-dashboard.service Dashboard systemd unit\n│   ├── sidekick-agent.service     Agent bridge systemd unit\n│   └── sidekick-sudoers           Sudoers config for sidekick user\n├── data/               Runtime data (on remote: logs, KV, conversations)\n├── deploy.ps1          Deploy script (Windows)\n├── deploy.sh           Deploy script (Linux/Mac)\n├── .env.example        Environment variable template\n├── AGENTS.md           opencode subagent config\n├── CONTEXT.md          Project context and session notes\n└── opencode.json       opencode MCP server config\n```\n\n**Deploy script fails with \"SSH key not found\":** The script will automatically generate an SSH key if one doesn't exist at `~/.ssh/sidekick`\n\n.\n\n**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.\n\n**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.\n\n**MCP connection issues:** If you see \"Server not initialized\" errors, restart the MCP service:\n\n```\nsudo systemctl restart sidekick-mcp\n```\n\n**Dashboard won't load:** Check that the dashboard service is running:\n\n```\nsudo systemctl status sidekick-dashboard\n```\n\n**Services not starting:** Check the logs:\n\n```\nsudo journalctl -u sidekick-mcp -n 50\nsudo journalctl -u sidekick-dashboard -n 50\nsudo journalctl -u sidekick-agent -n 50\n```\n\n- Clone the repo\n- Copy\n`.env.example`\n\n→`.env`\n\nand fill in your values - Run\n`.\\deploy.ps1 -IP \"YOUR_REMOTE_IP\"`\n\n(Windows) or`./deploy.sh YOUR_REMOTE_IP`\n\n(Linux/Mac) - Enter the sidekick password when prompted (first deploy only)\n- Open\n`http://YOUR_REMOTE_IP:4098/`\n\nand explore your new autonomous agent platform\n\nThat's it. Sidekick is live.\n\n**License:** MIT · See [LICENSE](/geoffmcc/sidekick/blob/main/LICENSE) for details.\n\n**Contributing:** PRs welcome.\n\n**Issues:** [Open one](https://github.com/geoffmcc/sidekick/issues) if you find a bug or have a feature request.", "url": "https://wpnews.pro/news/probably-just-end-up-embarrassing-myself-but-here-is-sidekick", "canonical_source": "https://github.com/geoffmcc/sidekick", "published_at": "2026-06-16 01:28:04+00:00", "updated_at": "2026-06-16 01:48:08.163534+00:00", "lang": "en", "topics": ["ai-agents", "ai-tools", "ai-infrastructure", "developer-tools", "ai-products"], "entities": ["Geoff McCaughan", "Sidekick", "opencode", "MCP", "Node.js", "Ubuntu", "Debian", "Raspberry Pi"], "alternates": {"html": "https://wpnews.pro/news/probably-just-end-up-embarrassing-myself-but-here-is-sidekick", "markdown": "https://wpnews.pro/news/probably-just-end-up-embarrassing-myself-but-here-is-sidekick.md", "text": "https://wpnews.pro/news/probably-just-end-up-embarrassing-myself-but-here-is-sidekick.txt", "jsonld": "https://wpnews.pro/news/probably-just-end-up-embarrassing-myself-but-here-is-sidekick.jsonld"}}