Sidekick

A remote VPS agent with MCP tools, live dashboard, and a local AI agent.

What is Sidekick?

Sidekick is not just a tool server. It is a persistent remote AI collaborator that lives on a VPS and works alongside you across every coding session. It can run commands on a remote machine, store and recall information across sessions, review your code, execute multi-step tasks autonomously, and serve as a second brain for your projects.

What sets Sidekick apart: it is always on, it remembers things, and it reads your instructions every time you open a session — so it knows how to help before you even ask.

Related MCP server: Agentic AI System MCP Server

How It Works: The AGENTS.md Loop

The secret sauce is a single file: ~/.config/opencode/AGENTS.md.

Every time you open opencode, it automatically reads this file and loads whatever instructions are in it into the AI's context. Sidekick leverages this mechanism to make itself a persistent presence in your workflow:

1. You open opencode — it reads AGENTS.md

2. Sidekick's tools and instructions are loaded — the AI now knows about the VPS, the tools, and how to collaborate

3. You work — the AI can call sidekick tools, delegate tasks to the @sidekick subagent, or you can chat with the agent directly via the dashboard

4. Session ends — but anything stored in Sidekick's KV persists for next time

This is what makes Sidekick different from a plain MCP tool server. Without AGENTS.md, Sidekick is just a set of APIs. With it, Sidekick is a collaborator that is always present, always aware, and always ready.

What You Can Achieve

Collaborative Workflows

Sidekick is designed to be involved throughout your project lifecycle, not just when you explicitly call it.

When to Involve Sidekick

• Code reviews — Security-sensitive or multi-system changes → always review. Trivial changes (docs, comments, renames) → skip. Everything else → review if confidence < 95%.

• Planning — Involve sidekick during planning, not just before commit. It can catch architectural issues earlier.

• Second opinions — Weighing tradeoffs or design decisions? Get sidekick's perspective.

• Issue identification — Before testing or deployment, have sidekick analyze for potential problems.

• Test coverage — Ask sidekick to review test coverage, not just code correctness.

• Documentation review — Have sidekick review README, AGENTS.md, and other docs for completeness.

How to Use Sidekick

• @sidekick subagent — Delegate complex multi-step tasks. The agent plans, calls tools, and iterates until the goal is met.

• Dashboard chat — Open http://YOUR_VPS_IP:4098/ and use the Agent tab to submit tasks directly.

• Direct MCP tools — Use sidekick_bash, sidekick_read, sidekick_write, sidekick_store, sidekick_get, etc. from any MCP-compatible client.

Best Practices

• Provide context — When asking for review, explain what the change does and why.

• Be specific — If you are unsure about something, tell sidekick what to focus on.

• Early involvement — The earlier sidekick is involved, the more valuable its input.

• Rule of thumb — If in doubt, ask sidekick. The overhead is minimal and the benefit is worth it.

Persistent Memory

Sidekick's KV store is its long-term memory. Unlike conversation context, which disappears when the session ends, KV data persists indefinitely on the VPS.

Example workflow:

# Store a decision in one session
sidekick_store("project_status", "Migrated to new VPS, all services green")

# Retrieve it in a future session
sidekick_get("project_status")
# → "Migrated to new VPS, all services green"

The AGENTS.md file tells the AI what to store and when to retrieve it — turning Sidekick into a project memory that spans sessions, days, and even weeks.

Setting Up AGENTS.md

This is the most important step. Without this file, Sidekick is just a tool server. With it, Sidekick becomes a persistent collaborator that is present in every opencode session.

Create or edit ~/.config/opencode/AGENTS.md and add the following (replace all placeholders with your values):

# Sidekick VPS Configuration

## VPS Connection
- IP: YOUR_VPS_IP
- MCP Server: port 4097
- Dashboard: port 4098
- Agent Bridge: port 4099

## Credentials
- GitHub token stored in KV key: `github_token`
- Use `sidekick_get("github_token")` to retrieve it for GitHub API calls
- API usage:
  ```
  Authorization: token <TOKEN>
  Accept: application/vnd.github.v3+json
  ```

## Using Sidekick Proactively

Sidekick is not just for storage — use it as a collaborator throughout projects.

### When to Use Sidekick
- **Code reviews**: Ask sidekick to review changes before committing
  - Security-sensitive, multi-system, or infrastructure changes → Always review
  - Trivial changes (docs, comments, renames) → Skip
  - Everything else → Review if confidence < 95%
- **Planning**: Involve sidekick during planning phase, not just before commit
- **Second opinions**: When weighing tradeoffs or design decisions
- **Issue identification**: Before testing or deployment, analyze for potential problems
- **Test coverage**: Review test coverage, not just code correctness
- **Persistent memory**: Store project status, decisions, and outcomes in KV
- **Documentation review**: Review README, AGENTS.md, and other docs for completeness

### How to Use Sidekick
- `sidekick_bash` — Run analysis tasks, code reviews, suggestions on the VPS
- `sidekick_store` — Save important decisions and outcomes to KV
- `sidekick_get` — Retrieve stored context from previous sessions
- `sidekick_read` — Examine files on the VPS

### Best Practices
- **Provide context**: Explain what the change does and why
- **Be specific**: Tell sidekick what to focus on
- **Early involvement**: The earlier sidekick is involved, the more valuable its input

### Why It Matters
- Creates more conversation points and decision opportunities
- Provides structured review that catches issues early
- Makes the development process more interactive and engaging
- Builds a persistent record of project evolution

**Rule of thumb**: If in doubt, ask sidekick. The overhead is minimal and the benefit is worth it.

opencode reads this file automatically on every session start. No plugins, no hooks, no manual loading — just a markdown file in the right place.

Architecture

┌─ Local Machine (source of truth) ─────────────────────┐
│  git push → github.com/geoffmcc/sidekick               │
│  ./deploy.ps1 → SSH into VPS, git pull, restart        │
└────────────────────────────────────────────────────────┘
                         │
                         ▼
┌─ VPS (YOUR_VPS_IP) ────────────────────────────────┐
│                                                        │
│  ┌─────────────┐  ┌──────────────┐  ┌──────────────┐  │
│  │  MCP Server  │  │  Dashboard   │  │ Agent Bridge │  │
│  │  :4097       │  │  :4098       │  │  :4099       │  │
│  └──────┬───────┘  └──────┬───────┘  └──────┬───────┘  │
│         │                  │                  │          │
│         └──────────────────┼──────────────────┘          │
│                            │                             │
│         ┌──────────────────▼──────────────┐              │
│         │        Ollama :11434            │              │
│         │     Model: phi3:mini (2.2GB)    │              │
│         └─────────────────────────────────┘              │
└────────────────────────────────────────────────────────┘

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.

Services

Quick Start

# Clone (already done)
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 VPS (Windows)
.\deploy.ps1

# Or deploy (Linux/Mac)
./deploy.sh

Daily Workflow

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

# 3. Deploy to VPS (Windows)
.\deploy.ps1

# Or deploy (Linux/Mac)
./deploy.sh

Or SSH directly to pull:

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

Configuration Changes

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

# 1. Edit .env locally
notepad .env

# 2. Deploy (syncs .env to VPS and restarts services)
.\deploy.ps1

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

MCP Tools

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

Dashboard

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

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

• Activity — live tool call log with source icons (🤖 agent, 🔌 MCP, ❓ unknown)

• Data — KV store contents (auto-seeded on dashboard startup with 35 server reference keys: IP, services, security, software, deployment)

• Config — environment variables (sensitive values redacted)

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

Agent Bridge

The agent at :4099 takes a natural-language goal and runs an autonomous loop:

1. Sends goal + tool definitions to the LLM (Groq cloud or local Ollama)

2. LLM responds with a tool call decision

3. Bridge executes the tool via MCP

4. Feeds result back to LLM

5. Repeats until the task is complete

API

# Start a task
curl -X POST http://YOUR_VPS_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_VPS_IP:4099/api/agent/stream/{taskId}

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

Security

The dashboard auth and IP whitelist are disabled by default (empty env var = no restriction). Set them in .env before exposing to the internet.

Files

├── src/
│   ├── tools.js        Shared tool handlers (extracted from index.js)
│   ├── index.js        MCP server (session-aware transport management)
│   ├── dashboard.js    Dashboard web UI (source tagging, Font Awesome icons)
│   └── agent.js        Agent bridge (LLM tool-use loop, direct tool calls)
├── data/               Runtime data (on VPS: logs, KV, conversations)
├── deploy.ps1          Deploy script — syncs and restarts services
├── .env.example        Environment variable template
├── AGENTS.md           opencode subagent config
├── CONTEXT.md          Project context and session notes
└── opencode.json       opencode MCP server config

Environment