Own a shelf of AI resources, accessible to your team, right in your IDE

This guide covers installing all AIShelf clients. Start with the local service - every other client requires it to be running first.

Local Service

The AIShelf Service is the hub that all clients connect to. It runs locally on your machine, manages registry clones in ~/.aishelf/, and exposes a REST API on localhost:5314. Install and run it before using any other AIShelf client.

Choose one installation method - both run the same service:

Docker (Recommended)

Docker is the recommended way to run the AIShelf service. It always pulls the latest version on startup and restarts automatically when Docker starts.

Prerequisite

Docker Desktop must be installed and running.

Within Docker Desktop, enable Settings → General → Start Docker Desktop when you sign in so the service comes back up automatically after a restart.

Start the service

1. Create the data directory (skip if it already exists):

mkdir -p ~/.aishelf

2. Pull the image and start the container:

docker run -d \
  --name aishelf-service \
  --restart=unless-stopped \
  -p 5314:5314 \
  -v ~/.aishelf:/root/.aishelf \
  -e AISHELF_HOST_HOME_PATH=$HOME \
  ghcr.io/aishelf/service:latest

Already have a container named aishelf-service?

If you ran this before, just start the existing container:

docker start aishelf-service

To start fresh (removes the old container first):

docker rm -f aishelf-service

Then re-run the command above.

--restart=unless-stopped — Docker restarts the container automatically when Docker starts

-v ~/.aishelf:/root/.aishelf — bind-mount your local ~/.aishelf/ so data survives container recreation

-e AISHELF_HOST_HOME_PATH — tells the service your real home directory path so file paths returned to the IDE extension are correct

Verify it started

curl http://localhost:5314/health
# Expected: {"status":"ok"}

Stop / start manually

docker stop aishelf-service   # stop
docker start aishelf-service  # start again

Updates

No manual action needed. The container always installs the latest version of @aishelf/service on startup, skipping the install when already up to date.

npm global install (Beta)

Beta - Docker recommended

This installation method is currently in beta. It may behave unexpectedly on some systems, particularly around OS daemon registration. If you have Docker available, use the Docker method instead. The CLI will also warn you and ask for confirmation before proceeding.

If you do not have Docker, you can install the service as a global npm package and register it as an OS daemon (launchd on macOS, systemd on Linux, Windows Service Manager on Windows).

Prerequisite

Node.js 18 or later. Check your version: node --version

Install and register as OS daemon

npm install -g @aishelf/service
aishelf service install

The aishelf service install command will display the beta warning and ask for explicit confirmation before registering the daemon.

Stop / start manually

aishelf service stop
aishelf service start

Update to the latest version

npm install -g @aishelf/service@latest
aishelf service restart

Verify it's working

After installation, confirm the service is reachable:

curl http://localhost:5314/health
# Expected: {"status":"ok"}

Or open the VS Code extension - the status bar item will show AIShelf with a checkmark when the service is running.

Service is running

If you see {"status":"ok"} in the terminal or the status bar shows a checkmark, you're all set. Proceed to install your preferred client below.

IDE Extension

The VS Code extension lets you browse, copy, edit, and sync AI resources directly from the IDE sidebar. It connects to the local service automatically once the service is running.

Install

Install AIShelf from the VS Code Marketplace or Open VSX Registry:

VS Code Marketplacemarketplace.visualstudio.comAIShelf.aishelf Open VSX Registryopen-vsx.orgAIShelf/aishelf

Compatibility

Compatible with VS Code, Cursor, Windsurf, and any VS Code-based IDE (version 1.105.0 or later).

After installing

Open the AIShelf sidebar panel. If the local service is running, the extension connects automatically and the status bar shows a checkmark. If the service is not running, the status bar shows "AIShelf: Offline" with a link to this page.

Browser Extension

Coming Soon

Not available yet

The browser extension is not available yet. We're working on it - check back soon.

The browser extension will let you access your AIShelf registries from any web-based AI tool - without switching to your IDE. Like all AIShelf clients, it connects to the same local service and reads from the same registries.

MCP Server

Early Preview

Limited early version

The current MCP server is an early preview with limited functionality. It lets AI models list and fetch resources from your connected registries - read-only, no write support yet. Deeper integration, write support, and real-time sync are planned for future releases.

What it does now

The MCP server exposes your connected AIShelf registries to any MCP-capable AI client - Cursor, Windsurf, Claude Code, and others. The AI model can discover and read resources (skills, prompts, rules, workflows) directly during a conversation, without manual copy-paste.

Two tools are exposed: list_resources to index available resources, and get_resource to fetch the full content of a specific resource.

What's coming

Write support - create and edit resources via MCP
Real-time sync with connected registries
Deeper IDE integrations

Setup (early preview)

Add this to your IDE's MCP configuration file:

mcp.json

{
  "mcpServers": {
    "aishelf": {
      "command": "npx",
      "args": ["-y", "@aishelf/mcp-server"]
    }
  }
}

Prerequisites

The AIShelf local service must be running on localhost:5314
At least one registry must be connected via the IDE extension

Tip

Hint to the model

Add use aishelf anywhere in your prompt to explicitly tell the AI model to check AIShelf for relevant resources before responding.

View on npm - @aishelf/mcp-server