Your Browser                    Remote Linux Server
     |                                  |
     |--- Click "VNC Desktop" --------->|
     |                                  |
     |    1. Detect X11 displays        |
     |    2. Find running browsers      |
     |    3. Start x11vnc server        |
     |    4. SSH port forwarding        |
     |                                  |
     |<-- WebSocket (noVNC) ------------|
     |    Live desktop stream           |
     |                                  |

# Step 1: Start a VNC session (auto-detects browser display)
curl -s -X POST https://app.nebulassh.com/api/Vnc/start \
  -H "Content-Type: application/json" \
  -d '{"host":"your-server","port":22,"username":"user","password":"pass"}'

# Response:
# { "sessionId": "abc123", "display": ":1", "port": 5901 }

# Step 2: Auto-detect displays with running browsers
curl -s -X POST https://app.nebulassh.com/api/Vnc/auto-detect \
  -H "Content-Type: application/json" \
  -d '{"host":"your-server","port":22,"username":"user","password":"pass"}'

# Response:
# { "displays": [{ "display": ":1", "browsers": ["chrome"], "hasVnc": true }] }

# Step 3: Scan all available X11 displays
curl -s -X POST https://app.nebulassh.com/api/Vnc/scan \
  -H "Content-Type: application/json" \
  -d '{"host":"your-server","port":22,"username":"user","password":"pass"}'

# Step 4: Connect to a specific display
curl -s -X POST https://app.nebulassh.com/api/Vnc/connect \
  -H "Content-Type: application/json" \
  -d '{"host":"your-server","port":22,"username":"user","password":"pass","display":":1"}'

# Step 5: Check session status
curl -s https://app.nebulassh.com/api/Vnc/status/{sessionId}

# Step 6: Execute commands on the remote desktop session
curl -s -X POST https://app.nebulassh.com/api/Vnc/execute/{sessionId} \
  -H "Content-Type: application/json" \
  -d '{"command":"xdotool getactivewindow getwindowname"}'

# Step 7: Stop the session when done
curl -s -X POST https://app.nebulassh.com/api/Vnc/stop/{sessionId}

> Open VNC desktop and show me what's on the screen

> Take a screenshot of the remote browser

> What website is currently open in the browser on display :1?

> Click the login button on the remote browser

> Navigate the remote browser to https://example.com

# Ubuntu/Debian
wget -q -O - https://dl.google.com/linux/linux_signing_key.pub | sudo gpg --dearmor -o /usr/share/keyrings/google-chrome.gpg
echo "deb [arch=amd64 signed-by=/usr/share/keyrings/google-chrome.gpg] http://dl.google.com/linux/chrome/deb/ stable main" | sudo tee /etc/apt/sources.list.d/google-chrome.list
sudo apt update && sudo apt install -y google-chrome-stable

# CentOS/RHEL
sudo dnf install -y https://dl.google.com/linux/direct/google-chrome-stable_current_x86_64.rpm

# Or install Chromium instead
sudo apt install -y chromium-browser   # Ubuntu
sudo dnf install -y chromium           # CentOS

# Start Chrome headless with debugging port
google-chrome --headless=new --no-sandbox \
  --remote-debugging-port=9222 \
  --disable-gpu --disable-dev-shm-usage \
  https://www.google.com &

# Verify it's running
curl -s http://127.0.0.1:9222/json/version
# Should return: { "Browser": "Chrome/...", ... }

# Check active pages
curl -s http://127.0.0.1:9222/json/list
# Should return a list of open tabs/pages

# One-liner: Start headless Chrome for AI viewing
google-chrome --headless=new --no-sandbox --remote-debugging-port=9222 \
  --disable-gpu --disable-dev-shm-usage https://your-target-site.com &

# For Playwright/Node.js automation with viewing support
npx playwright install chromium
node -e "
const { chromium } = require('playwright');
(async () => {
  const browser = await chromium.launch({
    headless: true,
    args: ['--remote-debugging-port=9222', '--no-sandbox']
  });
  const page = await browser.newPage();
  await page.goto('https://your-target-site.com');
  // Browser stays open for the CDP Viewer to stream
  console.log('Browser ready for viewing on port 9222');
})();
"

# Method 1: nohup (simple)
nohup google-chrome --headless=new --no-sandbox --remote-debugging-port=9222 \
  --disable-gpu --disable-dev-shm-usage https://your-site.com > /dev/null 2>&1 &

# Method 2: tmux (recommended for long-running)
tmux new-session -d -s chrome "google-chrome --headless=new --no-sandbox \
  --remote-debugging-port=9222 --disable-gpu --disable-dev-shm-usage https://your-site.com"

# Method 3: systemd service (production)
sudo tee /etc/systemd/system/headless-chrome.service > /dev/null << 'EOF'
[Unit]
Description=Headless Chrome for CDP Viewer
After=network.target

[Service]
Type=simple
User=your-username
ExecStart=/usr/bin/google-chrome --headless=new --no-sandbox --remote-debugging-port=9222 --disable-gpu --disable-dev-shm-usage https://your-site.com
Restart=always
RestartSec=5

[Install]
WantedBy=multi-user.target
EOF
sudo systemctl daemon-reload
sudo systemctl enable --now headless-chrome

   You (Browser / CLI)              Relay Server               Remote Machine
         |                      (app.nebulassh.com)             (Windows or Linux)
         |                              |                          |
         |--- Execute command --------->|                          |
         |                              |--- Poll (every 2s) ---->|
         |                              |<-- Here's a command ----|
         |                              |                          |
         |                              |    [ Runs command ]      |
         |                              |                          |
         |                              |<-- Result (stdout) -----|
         |<-- Output -------------------|                          |

┌─ NebulaSSH Agent ──────────────────────┐
│  Status:  ● Connected                  │
│  Your NebulaSSH ID:  123-456-789-012   │
│  Relay:   https://app.nebulassh.com    │
│                                        │
│  [ Connect ]  [ Disconnect ]  [ ⚙ ]    │
│  ─ Log ──────────────────────────────  │
│  Registered as 123-456-789-012         │
│  Waiting for commands...               │
└────────────────────────────────────────┘

# Install dependencies (Ubuntu/Debian)
sudo apt update && sudo apt install -y curl python3

# For CentOS/RHEL/Fedora
sudo yum install -y curl python3

# For Arch Linux
sudo pacman -S curl python

# Download the agent script straight to /usr/local/bin and make it executable
sudo curl -fsSL https://app.nebulassh.com/api/connector/download-linux-agent -o /usr/local/bin/nebulassh-agent
sudo chmod +x /usr/local/bin/nebulassh-agent

# (Optional) grab the guided installer instead
curl -fsSL https://app.nebulassh.com/api/connector/download-linux-installer -o install.sh
chmod +x install.sh && sudo ./install.sh

# First run — supply your token / key (one-time NS-… or permanent nse_…)
nebulassh-agent --relay https://app.nebulassh.com --enroll-token NS-XXXXX-XXXXX-XXXXX-XXXXX

# …or pass it via environment variable
NEBULASSH_ENROLL_TOKEN=NS-XXXXX-XXXXX-XXXXX-XXXXX nebulassh-agent --relay https://app.nebulassh.com

# After enrollment the token is no longer needed — just run:
nebulassh-agent --relay https://app.nebulassh.com

# Run as a background daemon
nebulassh-agent --relay https://app.nebulassh.com --daemon

╔══════════════════════════════════════╗
║    NebulaSSH Linux Agent v1.0.0     ║
╚══════════════════════════════════════╝
Agent ID:    031-975-703-405
Relay:       https://app.nebulassh.com
Shell:       bash
Interval:    2s

[2026-05-31 17:43:05] [INFO] Registering agent 031-975-703-405...
[2026-05-31 17:43:05] [INFO] Registration successful!
[2026-05-31 17:43:05] [INFO] Machine:   my-server
[2026-05-31 17:43:05] [INFO] OS:        Linux 6.8.0-117-generic x86_64
[2026-05-31 17:43:05] [INFO] User:      admin

# Create the service file
sudo tee /etc/systemd/system/nebulassh-agent.service <<EOF
[Unit]
Description=NebulaSSH Linux Agent
After=network-online.target
Wants=network-online.target

[Service]
Type=simple
User=$USER
Environment=HOME=$HOME
# First-time enrollment only — use your permanent key (nse_…) or a one-time NS-… token.
# Safe to remove once the machine is enrolled.
Environment=NEBULASSH_ENROLL_TOKEN=nse_XXXXXXXXXXXXXXXXXXXXXXXX
ExecStart=/usr/local/bin/nebulassh-agent --relay https://app.nebulassh.com
Restart=always
RestartSec=10

[Install]
WantedBy=multi-user.target
EOF

# Enable and start the service
sudo systemctl daemon-reload
sudo systemctl enable nebulassh-agent
sudo systemctl start nebulassh-agent

# Check status
sudo systemctl status nebulassh-agent

# View logs
sudo journalctl -u nebulassh-agent -f

# Restart agent
sudo systemctl restart nebulassh-agent

# Stop agent
sudo systemctl stop nebulassh-agent

# Run the installer with your one-time enrollment token
# (generate it in Dashboard -> Agents & Connector)
sudo NEBULASSH_ENROLL_TOKEN=NS-XXXXX-XXXXX-XXXXX-XXXXX ./install.sh

# It will:
# 1. Copy the agent to /usr/local/bin/
# 2. Ask for your relay server URL
# 3. Enroll the machine under your account (consumes the token)
# 4. Optionally create a systemd service

# List all online agents
nebulassh agents

# Execute a command on the Linux agent
nebulassh exec 031-975-703-405 "hostname && uptime && free -h"

# Interactive shell mode
nebulassh shell 031-975-703-405

# Step 1: Send a command
curl -X POST https://app.nebulassh.com/api/connector/execute \
  -H "Content-Type: application/json" \
  -d '{"AgentId":"031-975-703-405","Command":"df -h && free -h","Shell":"bash"}'
# Response: {"commandId":"abc123def456"}

# Step 2: Get the result
curl https://app.nebulassh.com/api/connector/result/abc123def456
# Response: {"isCompleted":true,"output":"...","error":"","exitCode":0}

# Upload a file to the Linux agent
curl -X POST https://app.nebulassh.com/api/connector/upload \
  -F "agentId=031-975-703-405" \
  -F "remotePath=/home/user/deploy/app.tar.gz" \
  -F "file=@./app.tar.gz"

# Download a file from the Linux agent
curl -X POST https://app.nebulassh.com/api/connector/download \
  -H "Content-Type: application/json" \
  -d '{"AgentId":"031-975-703-405","RemotePath":"/var/log/syslog"}'

# 64-bit x86 Linux
sudo curl -fsSL https://app.nebulassh.com/api/connector/download-tunnel-agent/linux-x64 \
  -o /usr/local/bin/nebulassh-tunnel-agent
sudo chmod +x /usr/local/bin/nebulassh-tunnel-agent

# First run: enrolls the machine + installs a systemd service (auto-start on boot) + connects
sudo /usr/local/bin/nebulassh-tunnel-agent --enroll-token NS-XXXXX-XXXXX-XXXXX-XXXXX

# ARM64? swap the URL for .../download-tunnel-agent/linux-arm64

curl -fsSL https://app.nebulassh.com/api/connector/download-tunnel-agent/install-linux -o install-linux.sh
chmod +x install-linux.sh
sudo NEBULASSH_ENROLL_TOKEN=NS-XXXXX-XXXXX-XXXXX-XXXXX ./install-linux.sh

nebulassh-tunnel-agent --id            # print this machine's Agent ID
nebulassh-tunnel-agent --run           # run in the foreground
nebulassh-tunnel-agent --install       # just enable start-at-boot and exit
nebulassh-tunnel-agent --uninstall     # remove start-at-boot
nebulassh-tunnel-agent --no-autostart  # run once without enabling boot start

# systemd (system service)
sudo systemctl status  nebulassh-tunnel-agent
sudo journalctl -u nebulassh-tunnel-agent -f
sudo systemctl restart nebulassh-tunnel-agent

# systemd (per-user service)
systemctl --user status nebulassh-tunnel-agent

# Windows 10/11 (x64) — enrolls, enables start-at-logon (HKCU Run), and connects
.\nebulassh-tunnel-agent-win-x64.exe --enroll-token NS-XXXXX-XXXXX-XXXXX-XXXXX

# Windows 7/8 — same flags, uses the built-in .NET Framework
.\nebulassh-tunnel-agent-win7.exe --enroll-token NS-XXXXX-XXXXX-XXXXX-XXXXX

# Run a command on the tunnel machine and get its output back
curl -s -X POST https://app.nebulassh.com/api/connector/tunnel-exec \
  -H "X-Api-Key: nsk_XXXXXXXXXXXXXXXXXXXX" \
  -H "Content-Type: application/json" \
  -d '{"agentId":"510-393-156-936","command":"whoami && uname -a","shell":"auto"}'
# → {"output":"root\nLinux …\n","error":"","exitCode":0}

# Classic queue + poll (works for tunnel AND classic agents)
CID=$(curl -s -X POST https://app.nebulassh.com/api/connector/execute \
  -H "X-Api-Key: nsk_XXXX" -H "Content-Type: application/json" \
  -d '{"agentId":"510-393-156-936","command":"uname -a","shell":"bash"}' | jq -r .commandId)

curl -s https://app.nebulassh.com/api/connector/result/$CID -H "X-Api-Key: nsk_XXXX"
# → {"isCompleted":true,"output":"Linux …\n","error":"","exitCode":0}

curl -fsSL https://app.nebulassh.com/api/connector/cli -o nebulassh && chmod +x nebulassh
export NEBULASSH_API_KEY=nsk_XXXXXXXXXXXXXXXXXXXX

./nebulassh agents                                    # list your agents
./nebulassh exec 510-393-156-936 "df -h && free -h"   # works for tunnel AND classic agents
./nebulassh tunnel-exec 510-393-156-936 "uptime"      # force the tunnel path

# Update package list
sudo apt update

# Install curl (HTTP client for API communication)
sudo apt install -y curl

# Install python3 (JSON parsing for CLI tool)
sudo apt install -y python3

# Optional: Install ca-certificates (for HTTPS/SSL)
sudo apt install -y ca-certificates

sudo yum install -y curl python3 ca-certificates

sudo pacman -S curl python ca-certificates

curl --version      # Must show version 7.x or 8.x
python3 --version   # Must show 3.6+

# Set relay URL (add to ~/.bashrc for persistence)
export NEBULASSH_RELAY=https://app.nebulassh.com

# Make permanent
echo 'export NEBULASSH_RELAY=https://app.nebulassh.com' >> ~/.bashrc
source ~/.bashrc

# Verify the relay is reachable (public endpoint — no key needed)
curl -sI https://app.nebulassh.com/api/connector/cli | head -1
# Should show: HTTP/2 200

# Listing agents now requires your API key (X-Api-Key); without it you get 401
curl -s -H "X-Api-Key: $NEBULASSH_API_KEY" https://app.nebulassh.com/api/connector/agents
# Returns your agents as JSON ([] if none). Get the key from Dashboard -> Agents & Connector.

sudo apt update && sudo apt install -y curl python3 ca-certificates && \
echo 'export NEBULASSH_RELAY=https://app.nebulassh.com' >> ~/.bashrc && \
export NEBULASSH_RELAY=https://app.nebulassh.com && \
echo "Setup complete! Now install the CLI tool (see next section)"

#!/bin/bash
#
# NebulaSSH CLI Client
# Remote command execution on Windows PCs via relay server
#
# Usage:
#   nebulassh agents                                    - List connected agents
#   nebulassh exec 123-456-789 "hostname"              - Run via PowerShell (default)
#   nebulassh exec 123-456-789 "dir C:\" cmd           - Run via CMD
#   nebulassh shell 123-456-789                        - Interactive shell mode
#

RELAY_URL="${NEBULASSH_RELAY:-https://app.nebulassh.com}"
API_KEY="${NEBULASSH_API_KEY:-}"
POLL_INTERVAL=1
MAX_WAIT=120

require_key() {
    if [ -z "$API_KEY" ]; then
        echo -e "${RED}[ERROR]${NC} Set NEBULASSH_API_KEY first."
        echo "Get your key from the NebulaSSH dashboard -> Agents & Connector."
        exit 1
    fi
}

RED='\033[0;31m'
GREEN='\033[0;32m'
YELLOW='\033[1;33m'
CYAN='\033[0;36m'
BOLD='\033[1m'
NC='\033[0m'

print_banner() {
    echo -e "${CYAN}"
    echo ' _   _      _           _        ____ ____  _   _ '
    echo '| \ | | ___| |__  _   _| | __ _ / ___/ ___|| | | |'
    echo '|  \| |/ _ \ '\''_ \| | | | |/ _` |\___ \___ \| |_| |'
    echo '| |\  |  __/ |_) | |_| | | (_| | ___) |__) |  _  |'
    echo '|_| \_|\___|_.__/ \__,_|_|\__,_||____/____/|_| |_|'
    echo -e "${NC}"
    echo -e "  ${BOLD}NebulaSSH CLI Client${NC} - Remote Windows Command Execution"
    echo ""
}

cmd_agents() {
    require_key
    echo -e "${BOLD}Your Agents:${NC}"
    echo ""
    response=$(curl -s -H "X-Api-Key: ${API_KEY}" "${RELAY_URL}/api/connector/agents")
    if [ -z "$response" ] || [ "$response" = "[]" ]; then
        echo -e "  ${YELLOW}No agents connected.${NC}"
        return
    fi
    echo -e "  ${BOLD}ID                  Machine          OS                          User        Status${NC}"
    echo "  ────────────────────────────────────────────────────────────────────────────────────────────"
    echo "$response" | python3 -c "
import sys, json
agents = json.load(sys.stdin)
for a in agents:
    aid = a.get('agentId', 'N/A')
    machine = a.get('machineName', 'N/A')[:16]
    os_ver = a.get('osVersion', 'N/A')[:28]
    user = a.get('username', 'N/A')[:10]
    online = 'Online' if a.get('isOnline') else 'Offline'
    print(f'  {aid:<20}{machine:<17}{os_ver:<30}{user:<12}{online}')
" 2>/dev/null
    echo ""
}

cmd_exec() {
    local agent_id="$1"
    local command="$2"
    local shell="${3:-powershell}"
    if [ -z "$agent_id" ] || [ -z "$command" ]; then
        echo -e "${RED}Usage: nebulassh exec <agent-id> <command> [powershell|cmd]${NC}"
        return 1
    fi
    require_key
    echo -e "${CYAN}[NebulaSSH]${NC} Sending to ${BOLD}${agent_id}${NC} (${shell}): ${command}"
    echo ""
    response=$(curl -s -X POST "${RELAY_URL}/api/connector/execute" \
        -H "Content-Type: application/json" \
        -H "X-Api-Key: ${API_KEY}" \
        -d "{\"agentId\":\"${agent_id}\",\"command\":\"${command}\",\"shell\":\"${shell}\"}")
    command_id=$(echo "$response" | python3 -c "import sys,json; print(json.load(sys.stdin).get('commandId',''))" 2>/dev/null)
    if [ -z "$command_id" ]; then
        error=$(echo "$response" | python3 -c "import sys,json; print(json.load(sys.stdin).get('error','Unknown error'))" 2>/dev/null)
        echo -e "${RED}[ERROR]${NC} ${error}"
        return 1
    fi
    waited=0
    while [ $waited -lt $MAX_WAIT ]; do
        result=$(curl -s -H "X-Api-Key: ${API_KEY}" "${RELAY_URL}/api/connector/result/${command_id}")
        is_completed=$(echo "$result" | python3 -c "import sys,json; print(json.load(sys.stdin).get('isCompleted', False))" 2>/dev/null)
        if [ "$is_completed" = "True" ] || [ "$is_completed" = "true" ]; then
            echo "$result" | python3 -c "
import sys, json
r = json.load(sys.stdin)
output = r.get('output', '')
error = r.get('error', '')
exit_code = r.get('exitCode', -1)
if output:
    print(output.rstrip())
if error:
    print('\033[0;31m' + error.rstrip() + '\033[0m')
print(f'\n\033[0;36m[NebulaSSH]\033[0m Exit code: {exit_code}')
" 2>/dev/null
            return 0
        fi
        sleep $POLL_INTERVAL
        waited=$((waited + POLL_INTERVAL))
        printf "\r  Waiting... %ds" "$waited"
    done
    echo ""
    echo -e "${RED}[TIMEOUT]${NC} Command did not complete within ${MAX_WAIT}s"
    return 1
}

cmd_shell() {
    local agent_id="$1"
    if [ -z "$agent_id" ]; then
        echo -e "${RED}Usage: nebulassh shell <agent-id>${NC}"
        return 1
    fi
    echo -e "${GREEN}[NebulaSSH Shell]${NC} Connected to ${BOLD}${agent_id}${NC}"
    echo -e "Prefix with ${BOLD}cmd:${NC} to use CMD. Type ${BOLD}exit${NC} to quit."
    echo ""
    while true; do
        echo -ne "${GREEN}nebulassh@${agent_id}${NC}> "
        read -r input
        [ -z "$input" ] && continue
        [ "$input" = "exit" ] || [ "$input" = "quit" ] && { echo -e "${CYAN}[NebulaSSH]${NC} Disconnected."; break; }
        shell="powershell"
        command="$input"
        if [[ "$input" == cmd:* ]]; then
            shell="cmd"
            command="${input#cmd:}"
            command="$(echo "$command" | sed 's/^ *//')"
        fi
        cmd_exec "$agent_id" "$command" "$shell"
        echo ""
    done
}

case "${1}" in
    agents|list|ls)
        print_banner
        cmd_agents
        ;;
    exec|run|e)
        cmd_exec "$2" "$3" "$4"
        ;;
    shell|sh|connect)
        print_banner
        cmd_shell "$2"
        ;;
    --relay|-r)
        RELAY_URL="$2"
        shift 2
        exec "$0" "$@"
        ;;
    --help|-h|help|"")
        print_banner
        echo "Usage: nebulassh <command> [options]"
        echo ""
        echo "Commands:"
        echo "  agents                                  List all connected Windows agents"
        echo "  exec  <agent-id> <command> [shell]      Execute a command (shell: powershell|cmd)"
        echo "  shell <agent-id>                        Interactive shell session"
        echo ""
        echo "Agent ID format: XXX-XXX-XXX (hardware-bound, persistent)"
        echo ""
        echo "Environment:"
        echo "  NEBULASSH_API_KEY  Your control-plane API key (required). Dashboard -> Agents & Connector."
        echo "  NEBULASSH_RELAY    Relay server URL (default: https://app.nebulassh.com)"
        echo ""
        echo "Examples:"
        echo "  nebulassh agents"
        echo "  nebulassh exec 123-456-789 \"Get-Process\" powershell"
        echo "  nebulassh exec 123-456-789 \"ipconfig /all\" cmd"
        echo "  nebulassh shell 123-456-789"
        echo ""
        ;;
    *)
        echo -e "${RED}Unknown command: $1${NC}"
        echo "Run 'nebulassh --help' for usage."
        exit 1
        ;;
esac

# Save the script (paste copied content)
sudo nano /usr/local/bin/nebulassh
# (Paste the script, then Ctrl+X, Y, Enter)

# Make executable
sudo chmod +x /usr/local/bin/nebulassh

# Verify installation
nebulassh --help

# Download and install CLI tool directly
curl -s https://app.nebulassh.com/api/connector/cli -o /usr/local/bin/nebulassh && \
chmod +x /usr/local/bin/nebulassh && \
nebulassh --help

# AI can use the CLI tool (export NEBULASSH_API_KEY first)
nebulassh exec 123-456-789-012 "Get-Process"

# Or call API directly with curl (the API key is required)
curl -s -X POST https://app.nebulassh.com/api/connector/execute \
  -H "Content-Type: application/json" \
  -H "X-Api-Key: $NEBULASSH_API_KEY" \
  -d '{"agentId":"123-456-789-012","command":"hostname","shell":"powershell"}'

# Set relay server
export NEBULASSH_RELAY=https://app.nebulassh.com

# Set your API key (required) - get it from Dashboard -> Agents & Connector
export NEBULASSH_API_KEY=nsk_your_key_here

# List the agents you own
./nebulassh agents

# Execute a command (PowerShell - default)
./nebulassh exec 123-456-789-012 "Get-Process | Select -First 5"

# Execute a command (CMD)
./nebulassh exec 123-456-789-012 "ipconfig /all" cmd

# Interactive shell session
./nebulassh shell 123-456-789-012

> Connect to NebulaSSH agent 123-456-789-012 and show me running services

> Check disk space on agent 456-789-012-345

> Run "Get-EventLog -LogName System -Newest 10" on agent 123-456-789-012

# All control-plane calls require your API key (X-Api-Key header).
KEY="nsk_your_key_here"

# List the agents you own
curl -s -H "X-Api-Key: $KEY" https://app.nebulassh.com/api/connector/agents

# Send a command
curl -s -X POST https://app.nebulassh.com/api/connector/execute \
  -H "Content-Type: application/json" \
  -H "X-Api-Key: $KEY" \
  -d '{"agentId":"123-456-789-012","command":"hostname","shell":"powershell"}'
# Returns: {"commandId":"abc123def456"}

# Get result (poll until isCompleted is true)
curl -s -H "X-Api-Key: $KEY" https://app.nebulassh.com/api/connector/result/abc123def456
# Returns: {"isCompleted":true,"output":"DESKTOP-PC\n","error":"","exitCode":0}

nebulassh exec ID "systeminfo"
nebulassh exec ID "hostname"
nebulassh exec ID "whoami"
nebulassh exec ID "[System.Environment]::OSVersion"

nebulassh exec ID "ipconfig /all" cmd
nebulassh exec ID "netstat -an" cmd
nebulassh exec ID "Get-NetIPAddress | Format-Table"
nebulassh exec ID "Test-NetConnection google.com -Port 443"

nebulassh exec ID "Get-Process | Sort-Object CPU -Descending | Select -First 10"
nebulassh exec ID "Get-Service | Where-Object Status -eq Running"
nebulassh exec ID "tasklist" cmd

nebulassh exec ID "Get-PSDrive -PSProvider FileSystem"
nebulassh exec ID "dir C:\" cmd
nebulassh exec ID "Get-ChildItem C:\Users -Recurse -Depth 1"

nebulassh exec ID "Get-EventLog -LogName System -Newest 5"
nebulassh exec ID "Get-EventLog -LogName Application -EntryType Error -Newest 10"

nebulassh exec ID "Get-ItemProperty HKLM:\Software\Microsoft\Windows\CurrentVersion\Uninstall\* | Select DisplayName, DisplayVersion | Sort DisplayName"

Upload (You → Agent):
  1. You upload file to app.nebulassh.com with agent ID + destination path
  2. Agent picks up the file during its next poll cycle
  3. Agent saves the file to the specified path

Download (Agent → You):
  1. You request a file from the agent with the remote file path
  2. Agent reads the file and uploads it to app.nebulassh.com
  3. You download the file from app.nebulassh.com

# Upload a file to the agent's C:\Temp folder
curl -X POST https://app.nebulassh.com/api/connector/upload \
  -F "agentId=123-456-789-012" \
  -F "remotePath=C:\Temp\myfile.zip" \
  -F "file=@/path/to/local/myfile.zip"

# Response:
# { "transferId": "abc123def456", "fileName": "myfile.zip", "fileSize": 1048576 }

# Step 1: Request the file
curl -X POST https://app.nebulassh.com/api/connector/download \
  -H "Content-Type: application/json" \
  -d '{"agentId":"123-456-789-012","remotePath":"C:\\Users\\admin\\Documents\\report.pdf"}'

# Response:
# { "transferId": "xyz789abc012" }

# Step 2: Poll until ready
curl -s https://app.nebulassh.com/api/connector/transfer/xyz789abc012/status
# { "isCompleted": true, "isError": false, "fileName": "report.pdf", "fileSize": 204800 }

# Step 3: Download the file
curl -o report.pdf https://app.nebulassh.com/api/connector/transfer/xyz789abc012/content

curl -s https://app.nebulassh.com/api/connector/transfer/{transferId}/status

# Response:
{
  "transferId": "abc123def456",
  "type": "upload",          // "upload" = sending to agent, "download" = getting from agent
  "isCompleted": true,
  "isError": false,
  "errorMessage": null,
  "fileName": "myfile.zip",
  "fileSize": 1048576
}

# POST /api/connector/execute
# Header: X-Api-Key: nsk_your_key_here
{
  "agentId": "123-456-789-012",
  "command": "Get-Process",
  "shell": "powershell"
}

# Response
{ "commandId": "abc123def456" }

# GET /api/connector/result/abc123def456
{
  "isCompleted": true,
  "output": "Handles  NPM(K)  PM(K) ...",
  "error": "",
  "exitCode": 0
}

# .mcp.json (or: claude mcp add)
{
  "mcpServers": {
    "nebulassh": {
      "type": "http",
      "url": "https://mcp.nebulassh.com/mcp",
      "headers": { "Authorization": "Bearer nsk_your_api_key_here" }
    }
  }
}

cd connector/nebulassh-mcp
npm install && npm run build
cp .env.example .env          # set NEBULASSH_RELAY / PORT
npm start                     # POST http://localhost:8848/mcp