VaultScope Connect

What is VaultScope Connect?

VaultScope Connect is a powerful CLI tool that handles automatic deployment of code to Pterodactyl game server panels. It streamlines the process of compressing, uploading, extracting, and restarting your servers with a simple command-line interface.

Features

• One-command deployment - Deploy your code with a single command
• Automatic compression - ZIP your files with customizable compression levels
• Multi-instance support - Manage multiple Pterodactyl panels simultaneously
• Auto-extract & reboot - Optionally extract files and restart servers automatically
• Persistent configuration - Save your deployment preferences for quick redeployment
• Server selection - Easily switch between multiple servers

Quick Setup

1. Install VaultScope Connect

npm i -g @vaultscope/vs-connect

2. Initialize Configuration

Run the initialization wizard to set up your first Pterodactyl instance:

vs-connect init

You'll be prompted to provide:

• Instance name - A friendly name for your panel (e.g., "Production", "Development")
• Panel URL - Your Pterodactyl panel URL (e.g., panel.example.com)
• API Key - Your Pterodactyl client API key
• ZIP compression level - Compression level from 1-9 (default: 9)
• Auto-extract preference - Whether to automatically extract files after upload

3. Deploy Your Code

vs-connect deploy

The first time you run deploy in a project directory, you'll create a deploy.json configuration file with:

• Which instance to use
• Which server to deploy to
• Default folder to compress
• Auto-extract settings
• Auto-reboot settings
• Default extraction directory

Subsequent deployments will use these saved settings.

Commands

Main Commands

vs-connect

Display help information and list all available commands.

vs-connect

vs-connect init

Run the initial setup wizard to configure your first Pterodactyl instance.

vs-connect init

What it configures:

• Global configuration stored in your system config directory
• Multiple Pterodactyl instances (panels)
• Default compression settings
• Auto-extract preferences

vs-connect deploy

Deploy your code to a Pterodactyl server.

vs-connect deploy

What it does:

1. Creates deploy.json if it doesn't exist (stores deployment preferences)
2. Compresses your specified directory into a ZIP file
3. Uploads the ZIP to your selected server
4. Optionally extracts the ZIP on the server
5. Optionally reboots the server after extraction

Interactive prompts:

• Directory to compress (if different from default)
• Remote upload directory
• Whether to reboot (if not set to auto-reboot)

vs-connect add-instance

Add a new Pterodactyl instance to your global configuration.

vs-connect add-instance

What it does:

• Prompts for new instance details
• Adds the instance to your global config
• Optionally sets it as the default instance

Configuration Files

Global Configuration

Stored in your system's config directory:

• Linux/macOS: ~/.config/vs-connect/config.json
• Windows: %APPDATA%\vs-connect\config.json

{
  "defaultInstance": "Production",
  "instances": [
    {
      "name": "Production",
      "url": "panel.example.com",
      "apikey": "your-api-key-here"
    }
  ],
  "experimental": {
    "zipCompressionLevel": 9,
    "autoExtractFiles": true
  }
}

Project Configuration (deploy.json)

Created in your project directory after first deployment:

{
  "useInstanceURL": "Production",
  "autoExtract": true,
  "autoReboot": true,
  "autoRebootOnFailedExtract": false,
  "autoUpload": true,
  "autoCleanup": true,
  "defaultCompressedFolder": "./dist",
  "defaultExtractDirectory": "/",
  "defaultUploadDirectory": "/",
  "defaultServerId": "abc12345",
  "skipPrompts": false
}

Configuration options:

• useInstanceURL - Which instance from global config to use
• autoExtract - Automatically extract ZIP after upload
• autoReboot - Automatically restart server after successful extraction
• autoRebootOnFailedExtract - Restart server even if extraction fails
• autoUpload - Enable automatic upload (always true)
• autoCleanup - Delete local ZIP file after successful deployment
• defaultCompressedFolder - Directory to compress (default: ./)
• defaultExtractDirectory - Where to extract on server (default: /)
• defaultUploadDirectory - Where to upload ZIP on server (default: /)
• defaultServerId - Server identifier to deploy to
• skipPrompts - Skip all interactive prompts for fully automated deployment

How It Works

Deployment Flow

1. Configuration Check

   • Verifies global config exists
   • Loads or creates deploy.json for the project
   • Validates server access

2. Compression

   • Creates a ZIP archive of your specified directory
   • Uses configured compression level (1-9)
   • Excludes files listed in .gitignore (if using the default ./ directory)

3. Upload

   • Requests a signed upload URL from Pterodactyl
   • Uploads ZIP file to the server via PUT request
   • Handles authentication and headers automatically

4. Extraction (if enabled)

   • Sends decompression request to Pterodactyl API
   • Extracts to specified directory on the server
   • Confirms successful extraction

5. Reboot (if enabled)

   • Sends restart signal to the server
   • Waits for confirmation
   • Completes deployment process

API Key Requirements

To use VaultScope Connect, you need a Client API Key from your Pterodactyl panel:

1. Log into your Pterodactyl panel
2. Go to Account Settings → API Credentials
3. Click Create New
4. Copy the API key (you can only see it once!)
5. Use this key during vs-connect init

Required permissions:

• Read server information
• Upload files
• Decompress files
• Restart servers

Examples

Basic Deployment Workflow

# First time setup
vs-connect init

# Navigate to your project
cd /path/to/your/project

# Deploy (creates deploy.json on first run)
vs-connect deploy

# Subsequent deployments use saved settings
vs-connect deploy

Multi-Instance Setup

# Add production instance
vs-connect init
# Enter: Production, panel.example.com, your-api-key

# Add development instance
vs-connect add-instance
# Enter: Development, dev-panel.example.com, dev-api-key

# Deploy uses instance from deploy.json
# Switch by editing deploy.json or creating new one
vs-connect deploy

Custom Deployment

When running vs-connect deploy, you can override defaults:

vs-connect deploy
# Prompt: Directory to compress (default ./dist): ./build
# Prompt: Remote upload directory (/ = root): /plugins
# Uploads ./build to /plugins on the server

Fully Automated Deployment

For CI/CD pipelines or automated workflows, set skipPrompts: true in deploy.json:

{
  "skipPrompts": true,
  "autoExtract": true,
  "autoReboot": true,
  "autoCleanup": true,
  ...
}

Then simply run:

vs-connect deploy

No prompts will appear - everything uses the configured defaults.

Troubleshooting

"No global config found"

Run vs-connect init to create your configuration.

"Failed to fetch servers"

• Verify your API key is correct
• Check your panel URL (no https:// prefix needed)
• Ensure your API key has proper permissions

"Upload failed"

• Check server disk space
• Verify upload permissions
• Ensure server is online

"Decompression failed"

• Verify the ZIP file uploaded successfully
• Check extraction directory permissions
• Ensure server has enough disk space

Files Ignored

The generated files.zip is automatically ignored (listed in .gitignore).

Additionally, the following are ignored:

• node_modules/
• deploy.json (project-specific config)
• files.zip (the generated archive)

Contributing

Contributions are welcome! Please feel free to submit issues or pull requests.

License

MIT License - see LICENSE file for details.

Author

Created by cptcr

Support

For issues and questions:

• Create an issue on GitHub
• Check existing issues for solutions
• Review the troubleshooting section above

VaultScope Connect - Simplifying Pterodactyl deployments, one command at a time.