Vinexus Docs

Getting Started

Vinexus is a native desktop IDE built for developers who work on remote virtual machines. Instead of browser-based tools or raw SSH sessions, Vinexus gives you a professional development environment — Monaco editor, integrated terminal, file explorer, git, and deploy tools — all connected directly to your VM over SSH.

What is Vinexus?

Vinexus is a desktop application (macOS, Windows, and Linux) that establishes a direct SSH connection to your virtual machine. There is no cloud infrastructure in the middle — your SSH credentials stay on your local machine, files are read and written via SFTP, and the terminal is a genuine PTY session on your server. Vinexus stores nothing about your code or credentials.

System Requirements

• macOS: macOS 12 (Monterey) or later. Apple Silicon (M1/M2/M3/M4) and Intel both supported.
• Windows: Windows 10 version 1903 or later. x86_64 architecture.
• Linux: Any distribution with glibc 2.17+. Includes Ubuntu, Debian, Fedora, Arch, Alpine, and more. x86_64 and ARM64 supported.
• RAM: 4 GB minimum, 8 GB recommended.
• Network: Internet connection required to reach your VM via SSH.

Download

Download the latest Vinexus installer from the download page. Choose the installer for your platform:

• macOS: Vinexus-mac.dmg
• Windows: Vinexus-Setup.exe
• Linux: Vinexus.AppImage or .deb / .rpm

Installing on macOS

Installing Vinexus on macOS takes about two minutes. Follow these steps to get set up.

Step 1: Download the .dmg

Download Vinexus-mac.dmg from the download page.

Step 2: Install to Applications

Open the downloaded .dmg file. In the Finder window that appears, drag the Vinexus icon to the Applications folder shortcut. Wait for the copy to complete, then eject the disk image.

Step 3: First Launch (Gatekeeper)

On first launch, macOS Gatekeeper will block Vinexus because it was downloaded from the internet. To open it:

1. In Finder, navigate to your Applications folder.
2. Right-click (or Control-click) on Vinexus.
3. Click Open in the context menu.
4. In the dialog that appears, click Open again to confirm.

You only need to do this once. After the first launch, Vinexus will open normally.

Alternative: System Settings approach

If you see a dialog saying the app cannot be opened, go to System Settings → Privacy & Security. Scroll down to the Security section and click Open Anyway next to the Vinexus message.

Alternative: Command-line quarantine removal

xattr -dr com.apple.quarantine /Applications/Vinexus.app

Installing on Windows

Vinexus on Windows installs like any standard application. The setup wizard handles everything automatically.

Step 1: Download the installer

Download Vinexus-Setup.exe from the download page.

Step 2: Run the installer

Double-click Vinexus-Setup.exe to launch the installer. Click through the setup wizard — accept the license agreement, choose an installation folder (the default is recommended), and click Install. The installer will create Start Menu and Desktop shortcuts automatically.

Windows Defender SmartScreen

Windows may show a SmartScreen warning the first time you run the installer. To proceed:

1. Click More info on the SmartScreen dialog.
2. Click Run anyway.

Windows Defender Firewall

On first launch, Windows may ask whether to allow Vinexus through the firewall. Click Allow access — Vinexus needs outbound access to establish SSH connections to your VM.

winget (coming soon)

winget install Vinexus.Desktop

Installing on Linux

Vinexus runs on any Linux distribution with glibc 2.17 or later. This includes Ubuntu, Debian, Fedora, Arch Linux, openSUSE, Alpine (via compatibility layer), and any other mainstream distro. Both x86_64 and ARM64 (including Raspberry Pi 4+) are supported.

AppImage (Universal — recommended)

The AppImage works on any distro with no installation required. Download it, mark it executable, and run it.

# Download the AppImage
curl -Lo Vinexus.AppImage https://download.vinexus.dev/latest/Vinexus.AppImage

# Mark it executable
chmod +x Vinexus.AppImage

# Run it
./Vinexus.AppImage

To integrate it into your application launcher, move it to ~/.local/bin/ and create a .desktop entry.

Debian / Ubuntu (.deb)

# Download the .deb package
curl -Lo vinexus.deb https://download.vinexus.dev/latest/Vinexus.deb

# Install with dpkg
sudo dpkg -i vinexus.deb

# Fix any missing dependencies
sudo apt-get install -f

# Launch
vinexus

Fedora / RHEL / CentOS (.rpm)

# Download the .rpm package
curl -Lo vinexus.rpm https://download.vinexus.dev/latest/Vinexus.rpm

# Install with rpm
sudo rpm -i vinexus.rpm

# Or using dnf (auto-resolves dependencies)
sudo dnf install vinexus.rpm

# Launch
vinexus

Arch Linux (AUR)

# Using yay
yay -S vinexus-desktop

# Using paru
paru -S vinexus-desktop

Required Dependencies

Most systems have these already. If Vinexus fails to start, install:

# Ubuntu / Debian
sudo apt-get install libgtk-3-0 libnotify4 libnss3 libxss1 libxtst6 xdg-utils

# Fedora / RHEL
sudo dnf install gtk3 libnotify nss libXScrnSaver libXtst xdg-utils

Setting Up Your Cloud VM

Vinexus connects to any Linux server accessible via SSH. Here is how to set up a cloud VM with the three most popular providers.

AWS EC2

1. Open the EC2 Console and click Launch Instance.
2. Choose Ubuntu Server 22.04 LTS (free tier eligible on t2.micro).
3. Under Key pair, create a new key pair or select an existing one. Download the .pem file — you will need it to connect.
4. Under Network settings, create a Security Group that allows SSH (port 22) from your IP only. Run curl ifconfig.me in your terminal to find your current public IP.
5. Launch the instance and wait for it to reach the running state.

# Fix key permissions (required on macOS/Linux)
chmod 400 my-key.pem

# Test your connection
ssh -i my-key.pem ubuntu@<your-ec2-public-ip>

DigitalOcean Droplet

1. In the DigitalOcean console, click Create → Droplets.
2. Choose Ubuntu 22.04 (LTS) and a Basic plan (the $6/mo shared CPU is fine for most projects).
3. Under Authentication, select SSH Key and add your public key.
4. Choose a data center region close to you and click Create Droplet.

# Connect as root (DigitalOcean default)
ssh root@<droplet-ip>

Any VPS or Self-Hosted Server

Vinexus works with any SSH-accessible server. Make sure SSH is running and your firewall allows port 22.

# Check if SSH is running on your server
sudo systemctl status ssh

# Start SSH if it's not running
sudo systemctl start ssh
sudo systemctl enable ssh

# Find your server's public IP
curl ifconfig.me

If you do not have an SSH key yet, generate one on your local machine:

# Generate a new SSH key (on your local machine)
ssh-keygen -t ed25519 -C "vinexus"

# Copy public key to your server
ssh-copy-id -i ~/.ssh/id_ed25519.pub user@<server-ip>

# Or manually append to authorized_keys on the server:
echo "$(cat ~/.ssh/id_ed25519.pub)" >> ~/.ssh/authorized_keys

IP Whitelisting

IP whitelisting restricts SSH access to your VM to only your specific IP address. This is one of the most effective defenses against brute-force attacks. Since Vinexus connects directly from your machine — no Vinexus servers in the middle — you only need to whitelist your own computer's public IP.

Find Your Public IP

# Run this on your local machine (the one running Vinexus)
curl ifconfig.me

Linux ufw (Ubuntu / Debian)

# Allow SSH only from your IP
sudo ufw allow from <YOUR_IP> to any port 22

# Enable the firewall (if not already enabled)
sudo ufw enable

# Verify the rules
sudo ufw status

AWS Security Groups

1. Open the EC2 console and navigate to Security Groups.
2. Select the security group attached to your instance.
3. Click Edit inbound rules → Add rule.
4. Set Type to SSH, Port to 22.
5. Under Source, select My IP — AWS will auto-fill your current IP.
6. Click Save rules.

DigitalOcean Firewall

1. Go to Networking → Firewalls → Create Firewall.
2. Under Inbound Rules, add: Type SSH, Sources set to your IP address.
3. Apply the firewall to your droplet and click Create Firewall.

Connecting to Your VM

Once your VM is running and your firewall is configured, connecting with Vinexus takes about 30 seconds.

Step-by-Step Connection

1. Open Vinexus and click New Connection (or press Cmd/Ctrl+N).
2. Fill in the connection details:
   • Host: Your VM's public IP address (e.g., 203.0.113.42)
   • Port: 22 (default SSH port)
   • Username: ubuntu for Ubuntu/AWS, root for DigitalOcean, or your custom username
3. Choose authentication:
   • SSH Key: Browse to your private key file (.pem or id_ed25519) — recommended
   • Password: Enter your SSH password
4. Click Connect. Vinexus opens the file explorer, editor, and terminal simultaneously.

Troubleshooting Connection Issues

Connection refused:

• Check that SSH is running: sudo systemctl status ssh
• Verify your security group / firewall allows port 22 from your IP

Permission denied (publickey):

• Verify the username is correct for your server
• Check key permissions: chmod 600 ~/.ssh/id_ed25519
• Ensure the public key is in ~/.ssh/authorized_keys on the server

Timeout / no route to host:

• Confirm the IP is correct and the VM is running
• Run curl ifconfig.me to verify your current public IP has not changed

Claude Code Integration

Claude Code is Anthropic's agentic AI coding assistant. By installing it directly on your VM, you can run it from the Vinexus integrated terminal and get full AI pair programming — Claude can read files, write code, run tests, and execute commands on your server with your approval at each step.

Requirements

• Premium or Max Vinexus plan
• Node.js 18+ installed on your VM
• An Anthropic API key from console.anthropic.com

Install on Your VM

# Step 1: Install Node.js 18+ if not already installed
curl -fsSL https://deb.nodesource.com/setup_18.x | sudo -E bash -
sudo apt-get install -y nodejs

# Verify
node --version

# Step 2: Install Claude Code globally on your VM
npm install -g @anthropic-ai/claude-code

# Verify installation
claude --version

# Step 3: Set your Anthropic API key
export ANTHROPIC_API_KEY="sk-ant-..."

# Step 4: Start Claude Code
claude

Make the API Key Permanent

# Add to .bashrc (bash) or .zshrc (zsh)
echo 'export ANTHROPIC_API_KEY="sk-ant-..."' >> ~/.bashrc
source ~/.bashrc

Using Claude Code in the Vinexus Terminal

ubuntu@prod-server:~/app$ claude

Claude Code ready. Type a message or '/help' for commands.

> fix the memory leak in src/worker.ts

I'll analyze worker.ts for memory leaks...
Reading file src/worker.ts (142 lines)

Found: EventEmitter listener added in startWorker() is never
removed in the cleanup() method, causing leaks on every restart.

Applying fix...
  - Added: emitter.off('data', handler) in cleanup()
  - Added: emitter.removeAllListeners() as fallback
✓ Fixed. Would you like me to add a test for this case?

Editor Features

Vinexus uses Monaco — the same editor engine that powers Visual Studio Code — for all code editing. Files are read and written directly over SFTP, so changes appear on your VM immediately when you save.

Syntax Highlighting

Monaco automatically detects the language from your file extension and applies syntax highlighting. 50+ languages are supported out of the box: JavaScript, TypeScript, Python, Go, Rust, Java, C/C++, Ruby, PHP, YAML, JSON, Markdown, and many more.

Keyboard Shortcuts

Multi-File Tabs

Open multiple files and switch between them using tabs at the top of the editor. Unsaved changes are indicated by a dot on the tab. Tabs persist across reconnections.

Find & Replace

Press Ctrl/Cmd+F to open the find bar. Press Ctrl/Cmd+H for find-and-replace with regex support.

Terminal

The Vinexus terminal is a full PTY (pseudo-terminal) session over SSH. It behaves exactly like a native terminal — interactive programs, colors, tab completion, and Ctrl+C all work as expected.

Features

• Full 256-color and true color support
• Tab completion and command history (up/down arrows)
• Scrollback buffer for reviewing previous output
• Multiple terminal instances — open tabs as needed
• Copy: Cmd+C (macOS) or Ctrl+Shift+C (Windows/Linux)
• Paste: Cmd+V (macOS) or Ctrl+Shift+V (Windows/Linux)
• Uses your VM's default shell (bash, zsh, fish, etc.)

Preventing SSH Timeouts

# Edit ~/.ssh/config on your local machine
Host *
    ServerAliveInterval 60
    ServerAliveCountMax 3

This sends a keepalive packet every 60 seconds and allows up to 3 missed responses before disconnecting.

Server Management & Deploy

The Vinexus Deploy panel gives you a one-click deployment pipeline that runs directly on your VM. It reads its configuration from a .vmide.json file you create on the server, then handles saving files, running validation checks, executing pre/post-deploy hooks, restarting your service, and automatically rolling back if anything fails.

How it works

When you click Deploy Now in the Deploy tab, Vinexus runs a pipeline of steps in order:

If any step fails and autoRollbackOnFailure is enabled, Vinexus immediately triggers a rollback to restore the backed-up state. You can also manually trigger a rollback by clicking the Rollback button after a failed deploy.

Creating .vmide.json

Create a .vmide.json file on your VM. Vinexus searches for it in these locations (in order):

• {rootPath}/.vmide.json — next to your project files
• /home/{username}/.vmide.json
• /root/.vmide.json

Place it in your project root for the cleanest setup:

# Create in your project directory
nano /home/ubuntu/myapp/.vmide.json

Full .vmide.json schema

{
  "version": 1,

  "project": {
    "name": "My App",
    "rootPath": "/home/ubuntu/myapp",
    "type": "node"
  },

  "services": [
    {
      "name": "My App",
      "unit": "myapp",
      "type": "pm2",
      "restartCommand": "pm2 restart myapp",
      "statusCommand": "pm2 show myapp",
      "logCommand": "pm2 logs myapp --lines 50 --nostream"
    }
  ],

  "deploy": {
    "files": [],
    "preValidate": [
      "cd /home/ubuntu/myapp && npm run lint",
      "cd /home/ubuntu/myapp && npm test -- --passWithNoTests"
    ],
    "preDeployHooks": [
      "cd /home/ubuntu/myapp && git pull origin main",
      "cd /home/ubuntu/myapp && npm install --production",
      "cd /home/ubuntu/myapp && npm run build"
    ],
    "postDeployHooks": [
      "pm2 save"
    ],
    "autoRollbackOnFailure": true
  },

  "commands": [
    {
      "name": "View Logs",
      "command": "pm2 logs myapp --lines 100 --nostream",
      "dangerLevel": "safe",
      "requiresConfirmation": false
    },
    {
      "name": "Clear Cache",
      "command": "rm -rf /home/ubuntu/myapp/.cache",
      "dangerLevel": "moderate",
      "requiresConfirmation": true
    }
  ]
}

project

services

Each entry in the services array describes a process Vinexus can restart and monitor. Supported type values:

deploy hooks

Example: Node.js app with PM2

{
  "version": 1,
  "project": { "name": "API Server", "rootPath": "/home/ubuntu/api", "type": "node" },
  "services": [{
    "name": "API",
    "unit": "api",
    "type": "pm2",
    "restartCommand": "pm2 restart api",
    "statusCommand": "pm2 show api",
    "logCommand": "pm2 logs api --lines 50 --nostream"
  }],
  "deploy": {
    "files": [],
    "preValidate": ["cd /home/ubuntu/api && npm run lint"],
    "preDeployHooks": [
      "cd /home/ubuntu/api && git pull origin main",
      "cd /home/ubuntu/api && npm install --production",
      "cd /home/ubuntu/api && npm run build"
    ],
    "postDeployHooks": ["pm2 save"],
    "autoRollbackOnFailure": true
  },
  "commands": []
}

Example: Python app with systemd

{
  "version": 1,
  "project": { "name": "Flask API", "rootPath": "/home/ubuntu/flask-api", "type": "python" },
  "services": [{
    "name": "Flask API",
    "unit": "flask-api",
    "type": "systemd",
    "restartCommand": "systemctl restart flask-api",
    "statusCommand": "systemctl status flask-api",
    "logCommand": "journalctl -u flask-api -n 50 --no-pager"
  }],
  "deploy": {
    "files": [],
    "preValidate": ["cd /home/ubuntu/flask-api && python -m pytest tests/ -q"],
    "preDeployHooks": [
      "cd /home/ubuntu/flask-api && git pull origin main",
      "cd /home/ubuntu/flask-api && pip install -r requirements.txt --quiet"
    ],
    "postDeployHooks": [],
    "autoRollbackOnFailure": true
  },
  "commands": []
}

Example: Nginx static site

{
  "version": 1,
  "project": { "name": "Website", "rootPath": "/var/www/html", "type": "nginx" },
  "services": [{
    "name": "Nginx",
    "unit": "nginx",
    "type": "systemd",
    "restartCommand": "nginx -t && systemctl reload nginx",
    "statusCommand": "systemctl status nginx",
    "logCommand": "tail -n 50 /var/log/nginx/error.log"
  }],
  "deploy": {
    "files": [],
    "preValidate": ["nginx -t"],
    "preDeployHooks": ["cd /var/www/html && git pull origin main"],
    "postDeployHooks": [],
    "autoRollbackOnFailure": false
  },
  "commands": []
}

Using the Deploy Panel

1. Create a .vmide.json on your VM (see examples above).
2. In Vinexus, click the Deploy tab in the bottom panel. If the config is detected, you will see a Deploy Now button.
3. Click Deploy Now. The pipeline steps appear in real time as they run.
4. Each step shows a green check on success or a red X with the error output on failure.
5. If a deploy fails, click Rollback to restore the previous state. If autoRollbackOnFailure is enabled, this happens automatically.
6. Click Clear to dismiss the result and return to the idle state.

Viewing Service Logs

After a deploy, Vinexus automatically pulls the first lines from your logCommand. You can also view live logs at any time from the terminal:

# PM2 live logs
pm2 logs myapp

# systemd live logs
journalctl -u myapp -f

# Docker live logs
docker logs -f myapp

Troubleshooting

SSH Connection Issues

• Is your VM running? Check the cloud provider console.
• Is the IP address correct? VMs get new IPs when stopped and restarted on some providers.
• Is SSH running on the VM? sudo systemctl status ssh
• Does your firewall allow port 22 from your current IP? Run curl ifconfig.me and compare to your firewall rules.
• For key auth: check permissions with ls -la ~/.ssh/ — private keys must be 600, the .ssh directory must be 700.

App Not Opening on macOS (Gatekeeper)

1. Right-click Vinexus in Applications → Open
2. Or: System Settings → Privacy & Security → Open Anyway
3. Or: xattr -dr com.apple.quarantine /Applications/Vinexus.app

Linux: App won't start

• Ensure the AppImage is executable: chmod +x Vinexus.AppImage
• Install missing libraries: sudo apt-get install libgtk-3-0 libnss3 libxss1
• Run from terminal to see error output: ./Vinexus.AppImage --no-sandbox

Terminal Not Responding

If the terminal stops responding, the SSH session may have timed out. Click the reconnect button or open a new terminal tab. Add a keepalive to your SSH config to prevent this.

Editor Not Saving

• File permissions on the server — you need write access to the file
• Disk space on the VM: df -h
• Whether the SSH connection is still active (check the terminal)