GumRun

Start · Stop · Restart your dev / web servers from VS Code — without dropping into a terminal manually every time.

Supports Go, Node.js, Python, Rust, .NET, Java, PHP, Ruby, Elixir, Deno, Bun out of the box, plus any custom command.

Features

• ▶ One-click Start / Stop / Restart — from the activity-bar sidebar or the status bar
• 🌍 Machine-wide projects (NEW v0.5) — register projects once at ~/.gumrun/projects.json and they show up in any VS Code window, regardless of which folder you opened. Useful when you keep switching between projects but want one place to launch them all.
• 🖱 Right-click a project to Open Folder, Open in New Window, or Reveal in File Explorer — jump straight to the code from the sidebar
• 🐍 Python venv auto-wire (NEW v0.5) — when a venv/, .venv/, or env/ is present, GumRun rewrites detected commands to use the venv interpreter (venv\Scripts\python.exe run.py, ... -m flask run, etc.) so you don't have to activate manually
• 🔍 Auto-detect services in your project (go.mod, package.json, Cargo.toml, manage.py, pom.xml, Gemfile, *.csproj, …)
• 📁 Add From File… — pick any file (Makefile, package.json, Cargo.toml, .sh, .ps1, *.go, *.py, …) and GumRun figures out how to run it; supports multi-target picks (Makefile targets, npm scripts, cargo bins)
• 🎯 Real port detection — reads config.yaml, config.toml, .env, appsettings.json, npm script --port flags, and app.run(port=…) in Python source, so GumRun uses the actual port your project listens on
• 🧩 Multiple services per project — run frontend + backend together (e.g. npm run dev + go run ./cmd/api)
• 🌐 Open in Browser — jump to your dev server URL
• 🎨 Live status icons — green (running), yellow (starting), grey (stopped)
• ⚙️ Per-service environment variables, working directory, and command
• 🛑 Graceful stop — sends Ctrl+C first, then disposes terminal

Built-in Presets

Quick Start

1. Install GumRun
2. Click the green ▶ icon in the activity bar (left side)
3. Click Add Project… (the + icon at the top) and pick any folder on disk — GumRun remembers it machine-wide
4. From the project's right-click menu, pick Auto-detect Services, Add Service, or Add From File…
5. Click any service to start it. Click again to stop.

Once a project is registered, it stays visible from any VS Code window — even ones where the folder isn't open. Right-click the project to Open Folder, Open in New Window, or Reveal in File Explorer.

Coming from v0.4? If you already have .vscode/gumrun.json in a workspace folder, GumRun imports it into the machine-wide registry the next time it activates. The workspace file is left untouched.

Add From File… examples

Port detection

When you add a service GumRun reads project config to use the real port, not a hardcoded default:

Python venv

If venv/, .venv/, or env/ exists in the project root, detected commands are rewritten to use the venv interpreter directly — no shell activation needed:

Works on Windows (Scripts\python.exe) and POSIX (bin/python) layouts.

Configuration

GumRun keeps a single machine-wide registry at ~/.gumrun/projects.json. Projects here are visible from any VS Code window:

{
  "projects": [
    {
      "id": "p-abc12345",
      "name": "my-api",
      "rootPath": "/Users/me/code/my-api",
      "services": [
        {
          "id": "svc-abc123",
          "name": "API",
          "language": "go",
          "command": "go run ./cmd/api",
          "cwd": "${workspaceFolder}",
          "url": "http://localhost:8080",
          "ports": [8080]
        },
        {
          "id": "svc-def456",
          "name": "Web",
          "language": "node",
          "command": "npm run dev",
          "cwd": "${workspaceFolder}/frontend",
          "url": "http://localhost:5173",
          "ports": [5173],
          "env": { "NODE_ENV": "development" }
        }
      ]
    }
  ]
}

${workspaceFolder} inside a service resolves to the project's rootPath (not the open VS Code workspace), so services run correctly even when their project folder is not the one currently open.

Legacy workspace config

.vscode/gumrun.json (v0.4 format) is still recognised — on activation GumRun imports any workspace folder that has one into the machine-wide registry. After import the workspace file is informational only; edits should go through the GumRun sidebar or ~/.gumrun/projects.json.

Status Bar

Click the status bar item (bottom-left) to toggle the primary service:

• ▶ name → click to start
• ⏹ name → click to stop

Configure which service shows up via gumRun.statusBar.serviceName.

Commands (Command Palette)

Settings

Tip — restart-after-edit

For projects where you edit code and need to bounce the server:

1. Click the service in the GumRun sidebar — it goes from green → grey
2. Click again — server restarts

Or use GumRun: Restart from the Command Palette (and bind it to a keyboard shortcut for one-key restart).

Companion extensions

Part of the Gum Suite:

• 🟢 GumRun — start / stop / restart dev servers
• 🟦 GumGo Preview — Go HTML template preview with click-to-jump
• 🟣 GumDotNet Form Viewer — preview C# / VB.NET WinForms designer files

License

MIT