upsun

Upsun plugin for AI coding agents

⚠️ Warning: This project is in early and active development. Things may change without notice.

Upsun plugin for AI coding agents and IDEs. Manage Upsun projects with skills and an MCP server. The plugin lives in plugins/upsun/ and can be shared across multiple agents. Plugins are available for Claude Code and Cursor, with skill-based integration for other IDEs and agents via skills.sh.

What's included

Component	Location	Description
Skills	plugins/upsun/skills/	using-upsun – 130+ CLI commands for deployments, environments, backups, databases, and more
MCP Server	plugins/upsun/.mcp.json	Natural-language infrastructure management via Upsun MCP

Installation

Prerequisites

1. Upsun CLI v5.6.0 or higher installed and authenticated

   # Install Upsun CLI (if not already installed)
   curl -fsSL https://raw.githubusercontent.com/platformsh/cli/main/installer.sh | VENDOR=upsun bash
   
   # Or via brew
   brew install platformsh/tap/upsun-cli
   
   # Authenticate
   upsun auth:browser-login
   

2. AI coding agent or IDE – e.g. Claude Code, Cursor, or other MCP-compatible tools

Claude Code

# In Claude Code, run:
/plugin marketplace add upsun/ai
/plugin install upsun@upsun
/reload-plugins

Note: A restart of Claude Code may be needed if the plugin install command fails.

Other IDEs and AI Agents (via skills.sh)

Install the Upsun skill for Cursor, VS Code, Windsurf, and any other AI agent or IDE that supports skills.sh:

npx skills add https://github.com/upsun/ai --skill upsun

After installation, the skill is immediately available to your AI agent. Ask it about Upsun tasks and it will use the skill automatically — for example: "Deploy to Upsun" or "Create a new environment."

Alternative: Skills only (manual)

To install just the skills without the full plugin, copy the contents of plugins/upsun/skills/ into your agent's skills directory so that the using-upsun/ folder ends up directly inside it (for example, at ~/.claude/skills/using-upsun/ for Claude Code). This includes all current and future skills in the repo.

Claude Code:

git clone https://github.com/upsun/ai.git /tmp/upsun-ai
# Copy the contents of the skills directory so that ~/.claude/skills/using-upsun/ is created
cp -r /tmp/upsun-ai/plugins/upsun/skills/. ~/.claude/skills/

Configure Permissions

Plugin installation (automatic)

If you installed via the plugin system, recommended permissions are automatically suggested. Accept them to enable full functionality.

Manual installation

Add Upsun CLI permissions to your agent's settings. For Claude Code, create or edit .claude/settings.local.json:

{
  "permissions": {
    "allow": [
      "Bash(upsun auth:*)",
      "Bash(upsun environment:*)",
      "Bash(upsun activity:*)",
      "Bash(upsun backup:*)",
      "Bash(upsun project:*)",
      "Bash(upsun logs:*)",
      "Bash(upsun resources:*)",
      "Bash(upsun metrics:*)",
      "Bash(upsun user:*)",
      "Bash(upsun organization:*)"
    ]
  }
}

For global permissions, edit ~/.claude/settings.json with the same structure. For other IDEs, refer to your agent's documentation for configuring permissions.

MCP Server (Optional)

The plugin includes the Upsun MCP Server for natural-language infrastructure management. To enable it, set the UPSUN_API_TOKEN environment variable to your Upsun API token (generate one in Upsun Console → Account settings):

export UPSUN_API_TOKEN=your_token_here

Verify Installation

1. Open your AI coding agent or IDE in a project
2. Ask: "Can you help me deploy to Upsun?"
3. The plugin's skill should activate and offer assistance

Usage

The skill activates automatically when you mention Upsun-related tasks:

• "Deploy to Upsun"
• "Create a new Upsun environment"
• "Backup the production environment"
• "Check Upsun environment status"
• "Scale Upsun resources"
• "Manage Upsun users"

Quick Start Examples

Deploy to production:

"Deploy my changes to the production environment on Upsun"

Create and test a feature branch:

"Create a new feature environment for testing my authentication changes"

Health check:

"Check the health of my production Upsun environment"

Backup before changes:

"Create a verified backup of production before I deploy"

Resource optimization:

"Audit resource usage across all my Upsun environments"

Skill documentation