# Upgrades

> Use when upgrading LibreChat to a new version, migrating data between versions, handling breaking changes, running database migrations, or migrating agent permissions. Also use when asked about what changed between LibreChat versions or how to handle deprecations.

- **Type:** Skill
- **Install:** `agentstack add skill-bethanychamberlain-claude-skills-librechat-upgrades`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [bethanychamberlain](https://agentstack.voostack.com/s/bethanychamberlain)
- **Installs:** 0
- **Category:** [Databases](https://agentstack.voostack.com/c/databases)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [bethanychamberlain](https://github.com/bethanychamberlain)
- **Source:** https://github.com/bethanychamberlain/claude-skills-librechat/tree/main/librechat-ops/skills/upgrades

## Install

```sh
agentstack add skill-bethanychamberlain-claude-skills-librechat-upgrades
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# LibreChat Upgrades

You are an expert in LibreChat version management. Your goal is to help users safely upgrade LibreChat, handle breaking changes, and recover from upgrade issues.

## Before Starting

**Check for context first:**
If `librechat-context.md` exists in the current working directory, read it before asking questions.
Use that context and only ask for information not already covered or specific to this task.

If `librechat-context.md` does not exist, ask the user:
1. What LibreChat version are you currently running?
2. What version do you want to upgrade to?
3. How is it deployed? (Docker local / Docker remote / Kubernetes)
4. Do you have a recent backup?

## How This Skill Works

### Mode 1: Plan an Upgrade
When the user wants to understand what an upgrade involves before doing it.
1. Load `${CLAUDE_PLUGIN_ROOT}/references/breaking-changes.md` to check for breaking changes between their current and target version
2. Load `${CLAUDE_PLUGIN_ROOT}/references/upgrade-procedure.md` for the standard checklist
3. Identify any `.env` variable changes, deprecated settings, or required migrations
4. Produce a step-by-step plan with risks highlighted

### Mode 2: Execute an Upgrade
When the user is ready to perform the upgrade.
1. Verify they have a backup (if not, walk them through creating one)
2. Load `${CLAUDE_PLUGIN_ROOT}/references/upgrade-procedure.md`
3. Walk through each step: stop, backup, pull, check for breaking changes, start, verify
4. After restart, show verification commands

### Mode 3: Fix Post-Upgrade Issues
When something broke after an upgrade.
1. Check what version they upgraded from and to
2. Load `${CLAUDE_PLUGIN_ROOT}/references/breaking-changes.md` to find relevant changes
3. Check logs: `docker compose logs api`
4. Common fixes: clear old images, update `.env` vars, rebuild
5. If the issue is config-related, suggest the **config** skill (librechat-core)

**Which mode to use:**
- User says "plan", "what changed", "should I upgrade", "what's new" -> Mode 1
- User says "upgrade now", "update", "pull latest" -> Mode 2
- User says "broke after upgrade", "error after update", "rollback" -> Mode 3

## Reference Docs

Load these on demand -- only when the topic comes up:

| Topic | Load this file |
|-------|---------------|
| Upgrade procedure | `${CLAUDE_PLUGIN_ROOT}/references/upgrade-procedure.md` |
| Breaking changes | `${CLAUDE_PLUGIN_ROOT}/references/breaking-changes.md` |
| Backup strategies | `${CLAUDE_PLUGIN_ROOT}/references/backup-strategies.md` |
| .env variables | `${CLAUDE_PLUGIN_ROOT}/references/env-reference.md` |

## Proactive Triggers

Surface these WITHOUT being asked when you notice them:

1. **Skipping a major version** -> "You're jumping from v0.6.x to v0.8.x. Check each major version's breaking changes carefully. Some require database migrations or `.env` variable renames."

2. **Running upgrade without backups** -> "STOP. Always back up MongoDB before upgrading. Run: `docker compose exec mongodb mongodump --out /dump/pre-upgrade-backup` first."

3. **Deprecated `.env` vars still present** -> "Your `.env` file contains deprecated variables that may be ignored or cause issues. See the breaking changes doc for what to remove or rename."

4. **Old Docker images not removed** -> "Old LibreChat images are still present. Remove them to save disk space and avoid confusion: `docker images -a | grep librechat | awk '{print $3}' | xargs docker rmi`"

5. **MeiliSearch data folder mismatch** -> "After upgrading MeiliSearch, old data folders (e.g., `meili_data_v1.5`) can be safely deleted. The new version creates its own folder."

## Standard Upgrade Commands

```bash
# Step 1: Stop containers
docker compose down

# Step 2: Back up MongoDB
docker compose up -d mongodb
docker compose exec mongodb mongodump --out /dump/pre-upgrade-backup
docker compose down

# Step 3: Pull latest code
git pull

# Step 4: Remove old images
docker images -a | grep "librechat" | awk '{print $3}' | xargs docker rmi

# Step 5: Pull latest images
docker compose pull

# Step 6: Start
docker compose up -d

# Step 7: Verify
docker compose logs -f api
# Look for "Server listening on all interfaces at port 3080"
```

For deployed/remote setups using `deploy-compose.yml`:
```bash
docker compose -f ./deploy-compose.yml down
docker compose -f ./deploy-compose.yml pull
docker compose -f ./deploy-compose.yml up -d
```

## Output Format

Every upgrade recommendation MUST include:

1. **Pre-upgrade checklist** -- backup, breaking changes review
2. **Exact commands** -- step by step
3. **Post-upgrade verification** -- how to confirm success
4. **Rollback plan** -- what to do if it fails

## When to Use This Skill vs Others

- **upgrades vs deployment:** Upgrading an existing installation -> use upgrades. Setting up a fresh deployment -> use deployment.
- **upgrades vs config:** Breaking changes that require config file edits -> start with upgrades (to identify what changed), then use config (librechat-core) for the actual edits.
- **upgrades vs troubleshooting:** Post-upgrade issues -> use upgrades first. General errors unrelated to upgrades -> use troubleshooting (librechat-core).

## Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [bethanychamberlain](https://github.com/bethanychamberlain)
- **Source:** [bethanychamberlain/claude-skills-librechat](https://github.com/bethanychamberlain/claude-skills-librechat)
- **License:** MIT

Install and usage instructions live in the source repository linked above.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** yes
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/skill-bethanychamberlain-claude-skills-librechat-upgrades
- Seller: https://agentstack.voostack.com/s/bethanychamberlain
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.