# AgentVault Agentic Access Setup

Use this skill when the user asks an AI coding agent to set up AgentVault Agentic Access on their local machine.

AgentVault has two parts:

- the Chrome extension, where the user stores encrypted skills and secrets
- the optional desktop companion, which runs on `http://127.0.0.1:3747` so local agents can request secrets during a temporary session

The extension's vault and skill library work without the companion. Agent Session requires the companion to be installed and running.

## Safety Rules

- Explain what you are about to change before writing files.
- Install only inside the AgentVault companion directory for this OS.
- Do not modify unrelated user projects.
- Do not overwrite existing AI client MCP config without reading it first and preserving existing entries.
- Download companion files only from `https://getagentvault.app/downloads/companion/`.
- If anything is unclear or blocked by permissions, stop and tell the user exactly what to do next.

## Install Locations

Use these permanent locations:

- Windows: `%LOCALAPPDATA%\AgentVaultCompanion`
- macOS: `~/Library/Application Support/AgentVaultCompanion`
- Linux: `~/.local/share/agentvault-companion`

## Prerequisites

1. Detect the OS.
2. Check Node.js:

```bash
node --version
```

Require Node.js 18 or newer. If missing or too old, ask the user to install Node.js from `https://nodejs.org` and stop.

## Download Files

Create this structure in the install location:

```text
AgentVaultCompanion/
  companion/
    server.js
    start-silent.vbs        # Windows only
  mcp/
    package.json
    package-lock.json
    server.js
```

Download:

- `https://getagentvault.app/downloads/companion/server.js`
- `https://getagentvault.app/downloads/companion/start-silent.vbs`
- `https://getagentvault.app/downloads/companion/mcp/package.json`
- `https://getagentvault.app/downloads/companion/mcp/package-lock.json`
- `https://getagentvault.app/downloads/companion/mcp/server.js`

Then run:

```bash
npm install
```

inside the `mcp/` folder.

## Start The Companion

Start the companion server with:

```bash
node companion/server.js
```

It should listen on:

```text
http://127.0.0.1:3747
```

Verify:

```bash
curl http://127.0.0.1:3747/health
```

Expected response includes:

```json
{ "status": "ok" }
```

If `curl` is unavailable, use the platform's equivalent HTTP request command.

## Auto-Start

Set up auto-start only after the health check works.

### Windows

Create a shortcut or VBS entry in:

```text
%APPDATA%\Microsoft\Windows\Start Menu\Programs\Startup
```

It should run `node companion/server.js` from the install location with no visible terminal window.

### macOS

Create a user LaunchAgent:

```text
~/Library/LaunchAgents/com.agentvault.companion.plist
```

The LaunchAgent should run Node with the installed `companion/server.js` at login.

### Linux

Create a user systemd service if systemd is available:

```text
~/.config/systemd/user/agentvault-companion.service
```

Then enable and start it with:

```bash
systemctl --user enable --now agentvault-companion.service
```

If user systemd is not available, create a clear manual start command instead.

## MCP Configuration

Configure MCP only for clients that are installed or whose config folder exists. Preserve existing MCP servers.

The AgentVault MCP server command is:

```text
node
```

Arguments:

```text
<INSTALL_LOCATION>/mcp/server.js
```

Add an MCP server named:

```text
agentvault
```

### Claude Desktop

Common config paths:

- Windows: `%APPDATA%\Claude\claude_desktop_config.json`
- macOS: `~/Library/Application Support/Claude/claude_desktop_config.json`

Add or merge:

```json
{
  "mcpServers": {
    "agentvault": {
      "command": "node",
      "args": ["<INSTALL_LOCATION>/mcp/server.js"]
    }
  }
}
```

### Cursor and Windsurf

Detect existing MCP config locations if present. If the client is installed but the config path is unclear, tell the user what command and args to paste into the client's MCP settings:

```text
Name: agentvault
Command: node
Args: ["<INSTALL_LOCATION>/mcp/server.js"]
```

## Final User Instructions

After setup:

1. Open AgentVault in Chrome.
2. Unlock the vault.
3. Choose the number of access minutes.
4. Click `Session`.
5. Use `Copy Agent Instructions`, or use MCP tools:
   - `list_secrets`
   - `get_secret`

If the Session button is disabled, the companion is not running or is blocked.

## Final Report

Tell the user:

- where AgentVault Companion was installed
- whether Node.js was detected and which version
- whether auto-start was configured
- which MCP clients were configured
- whether `http://127.0.0.1:3747/health` returned ok
- what they should do next in the Chrome extension