⚠️ 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.
| 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 |
-
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
-
AI coding agent or IDE – e.g. Claude Code, Cursor, or other MCP-compatible tools
# In Claude Code, run:
/plugin marketplace add upsun/ai
/plugin install upsun@upsun
/reload-pluginsNote: A restart of Claude Code may be needed if the plugin install command fails.
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 upsunAfter 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."
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/If you installed via the plugin system, recommended permissions are automatically suggested. Accept them to enable full functionality.
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.
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- Open your AI coding agent or IDE in a project
- Ask: "Can you help me deploy to Upsun?"
- The plugin's skill should activate and offer assistance
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"
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.md – Main skill navigation and quick reference
- references/ - Detailed command documentation
- COMMAND-INDEX.md - Alphabetical command reference
- environments.md - Environment lifecycle
- deployments.md - Deployment patterns
- backups.md - Backup/restore procedures
- services-databases.md - Database operations
- resources-scaling.md - Resource management
- access-security.md - Security and access control
- integration-variables.md - Configuration
- development-tools.md - Developer tools
- projects-organizations.md - Project management
- troubleshooting.md - Common issues
The using-upsun skill uses a progressive disclosure architecture:
- SKILL.md (entry point) - Workflow navigation and common operations
- references/ (on-demand) - Detailed documentation loaded as needed
This design minimizes context usage while providing comprehensive coverage.
All plugin components live inside plugins/upsun/. When adding new functionality, place it in the corresponding subdirectory:
plugins/upsun/
├── .claude-plugin/
│ └── plugin.json # Plugin manifest
├── .mcp.json # MCP server configuration
└── skills/
└── using-upsun/ # Upsun skill
This structure means the plugin is self-contained and reusable — any agent that installs upsun@upsun gets all components automatically.
- Update existing reference files in
plugins/upsun/skills/using-upsun/references/ - Add cross-references to related documents
- Update
SKILL.mdif adding commonly-used commands - Test that your agent can find and use the new documentation
- Upsun CLI v5.6.0 or higher
- AI coding agent or IDE (Claude Code, Cursor, etc.)
- Authenticated Upsun account
This project is licensed under the MIT - see the LICENSE file for details.
- Upsun Documentation: https://docs.upsun.com
- Upsun CLI Reference: https://docs.upsun.com/administration/cli/reference.html
- Claude Code (plugin docs): https://code.claude.com/docs
- Issues: Please report issues on the GitHub repository
- Upsun plugin for AI coding agents and the Upsun Platform-as-a-Service
- Uses Upsun CLI v5.6.0+ command structure