From e153eae8883a8b4628c584e9210399d3c83c07d5 Mon Sep 17 00:00:00 2001 From: Waishnav <86405648+Waishnav@users.noreply.github.com> Date: Fri, 30 Oct 2026 10:52:19 +0530 Subject: [PATCH 1/6] docs: lead installation with the one-command installer Co-Authored-By: Claude Opus 5.5 --- README.md | 21 ++++++----- website/docs/01-quickstart.mdx | 42 ++++++++++++++-------- website/docs/reference/troubleshooting.mdx | 19 +++------- 3 files changed, 42 insertions(+), 40 deletions(-) diff --git a/README.md b/README.md index 93c6174ea..b518068f9 100644 --- a/README.md +++ b/README.md @@ -60,25 +60,24 @@ The same `/mcp` endpoint serves the 2026-07-28 per-request protocol and automati ## Installation -DevSpace requires Node `>=22.19 <27`. - -Install the DevSpace CLI: +macOS, Linux, and WSL: ```bash -npm install -g @waishnav/devspace +curl -fsSL https://devspace.run/install | sh ``` -Then initialize DevSpace: +Windows (DevSpace also needs Git Bash): -```bash -devspace init +```powershell +powershell -c "irm https://devspace.run/install.ps1 | iex" ``` -Or run it without a global install: +The installer uses a compatible Node (`>=22.19 <27`) on your `PATH` or +downloads Node 24 LTS for DevSpace alone, installs without `sudo`, and starts +`devspace init`. Rerun it to update. -```bash -npx @waishnav/devspace init -``` +If you manage Node yourself, `npm install -g @waishnav/devspace` followed by +`devspace init` also works. During setup, DevSpace asks for: diff --git a/website/docs/01-quickstart.mdx b/website/docs/01-quickstart.mdx index d3f0438bf..ef473a4db 100644 --- a/website/docs/01-quickstart.mdx +++ b/website/docs/01-quickstart.mdx @@ -5,17 +5,32 @@ sidebar: icon: rocket --- -DevSpace requires Node `>=22.19 <27`, Git, and a Bash-compatible shell -(Git Bash or WSL on Windows). +DevSpace needs Git and a Bash-compatible shell (Git Bash or WSL on Windows). +The installer brings its own Node when yours is missing or outside +`>=22.19 <27`. - - ```bash - npx @waishnav/devspace init - ``` + + + + ```bash + curl -fsSL https://devspace.run/install | sh + ``` + + + ```powershell + powershell -c "irm https://devspace.run/install.ps1 | iex" + ``` + + + + The installer uses a compatible Node on your `PATH` or downloads a + checksum-verified Node 24 LTS for DevSpace alone, installs DevSpace without + `sudo`, puts `devspace` on your `PATH`, and starts `devspace init`. Rerun it + to update. - Or install the CLI globally with `npm install -g @waishnav/devspace` and run - `devspace init`. + Already manage Node yourself? `npm install -g @waishnav/devspace` and + `devspace init` work too. @@ -47,7 +62,7 @@ DevSpace requires Node `>=22.19 <27`, Git, and a Bash-compatible shell HTTPS origin of your tunnel (without `/mcp`). Then start the server: ```bash - npx @waishnav/devspace serve + devspace serve ``` Add `https://your-tunnel.example.com/mcp` as a connector and approve it @@ -62,8 +77,7 @@ DevSpace requires Node `>=22.19 <27`, Git, and a Bash-compatible shell ## Your first delegation From a project directory, ask your harness to delegate — or try the commands -yourself. They assume a global install; with npx, prefix each with -`npx @waishnav/devspace` instead of `devspace`. +yourself. ```bash devspace agents targets @@ -92,11 +106,11 @@ work in its own context. ## Check your setup ```bash -npx @waishnav/devspace doctor +devspace doctor ``` -`doctor` reports the resolved config, Node version and ABI, platform, Git, -Bash, public URL, allowed hosts, and native SQLite status. +`doctor` reports the resolved config, Node version, platform, Git, Bash, +public URL, allowed hosts, and SQLite status. diff --git a/website/docs/reference/troubleshooting.mdx b/website/docs/reference/troubleshooting.mdx index 7a5511ec0..cdb78c79d 100644 --- a/website/docs/reference/troubleshooting.mdx +++ b/website/docs/reference/troubleshooting.mdx @@ -3,11 +3,12 @@ title: Troubleshooting description: The setup issues people hit most, and the one-line fix for each. --- -Start with `npx @waishnav/devspace doctor` — it reports config, Node, Git, -Bash, public URL, allowed hosts, and native SQLite status. +Start with `devspace doctor` — it reports config, Node, Git, +Bash, public URL, allowed hosts, and SQLite status. - Use `npx @waishnav/devspace …`, or make sure npm's global bin directory is on + Open a new terminal so the installer's `PATH` change applies, or rerun the + installer. With an npm install, make sure npm's global bin directory is on your `PATH`. @@ -16,18 +17,6 @@ Bash, public URL, allowed hosts, and native SQLite status. or `mise`. - - Release starts check native dependencies before launching. A load failure - usually means they were built for a different Node runtime. Reinstall with - the Node you run DevSpace with, then rerun `doctor`: - - - global install: `npm install -g @waishnav/devspace` - - npx: remove only DevSpace's cached copy, then rerun the `npx` command. - With npm 11.2 or newer, find its key in `npm cache npx ls` and run - `npm cache npx rm `. With older npm, switch to a global install. - - local project install: `npm rebuild better-sqlite3` in that project - - Setup wants the origin (`https://host`); the client wants the endpoint (`https://host/mcp`). Fix it with From 12994b1b241031990b57d3f3ba066fc3b160e5c7 Mon Sep 17 00:00:00 2001 From: Waishnav <86405648+Waishnav@users.noreply.github.com> Date: Fri, 30 Oct 2026 12:01:33 +0530 Subject: [PATCH 2/6] feat(website): serve the installers at devspace.run/install A public/_redirects file 302s /install and /install.ps1 to the scripts on main. Blume's own redirects option was not usable here: it nests the path under the /docs basePath and emits an HTML meta-refresh page, which curl | sh would pipe into the shell. Cloudflare applies _redirects before serving any asset, so clients always get the script. The installer headers now use the short URLs. Co-Authored-By: Claude Opus 5.5 --- install/install.ps1 | 2 +- install/install.sh | 2 +- website/public/_redirects | 4 ++++ 3 files changed, 6 insertions(+), 2 deletions(-) create mode 100644 website/public/_redirects diff --git a/install/install.ps1 b/install/install.ps1 index fe9f802d9..c23ad0726 100644 --- a/install/install.ps1 +++ b/install/install.ps1 @@ -1,6 +1,6 @@ # DevSpace installer for Windows. # -# powershell -c "irm https://raw.githubusercontent.com/Waishnav/devspace/main/install/install.ps1 | iex" +# powershell -c "irm https://devspace.run/install.ps1 | iex" # # Mirrors install.sh: uses a compatible Node already on PATH, otherwise downloads a checksum-verified Node 24 LTS # for DevSpace alone, installs @waishnav/devspace into a user-owned npm prefix, writes `devspace` launchers that diff --git a/install/install.sh b/install/install.sh index d24fde400..c6e42fa22 100755 --- a/install/install.sh +++ b/install/install.sh @@ -1,7 +1,7 @@ #!/bin/sh # DevSpace installer for macOS, Linux, and WSL. # -# curl -fsSL https://raw.githubusercontent.com/Waishnav/devspace/main/install/install.sh | sh +# curl -fsSL https://devspace.run/install | sh # # Uses a compatible Node already on PATH, otherwise downloads a checksum-verified Node 24 LTS for DevSpace alone. # Installs @waishnav/devspace into a user-owned npm prefix (no sudo), writes `devspace` launchers that pin that diff --git a/website/public/_redirects b/website/public/_redirects new file mode 100644 index 000000000..4eab29b3c --- /dev/null +++ b/website/public/_redirects @@ -0,0 +1,4 @@ +# Short installer URLs. Cloudflare applies these before serving any asset, so the shell never receives HTML. +# 302 keeps the target changeable without clients caching it. +/install https://raw.githubusercontent.com/Waishnav/devspace/main/install/install.sh 302 +/install.ps1 https://raw.githubusercontent.com/Waishnav/devspace/main/install/install.ps1 302 From bac0ba9560237fc095bf7f3c103bfc173200f8af Mon Sep 17 00:00:00 2001 From: Waishnav <86405648+Waishnav@users.noreply.github.com> Date: Fri, 30 Oct 2026 11:15:21 +0530 Subject: [PATCH 3/6] feat(website): show the install command for the visitor's OS The hero and closing CTA get macOS / Linux, Windows, and npm tabs above the copy button. The page preselects Windows from the user agent and otherwise defaults to the curl command, and every tab group, copy button, and the nav Install button stay on the same choice. Replaces the npx init command, which the installer now covers. Co-Authored-By: Claude Opus 5.5 --- website/landing/content.ts | 9 +++- website/landing/home/InstallCommand.astro | 62 +++++++++++++++++++++++ website/landing/home/Landing.astro | 11 ++-- 3 files changed, 78 insertions(+), 4 deletions(-) create mode 100644 website/landing/home/InstallCommand.astro diff --git a/website/landing/content.ts b/website/landing/content.ts index 23a47d594..0aca9d915 100644 --- a/website/landing/content.ts +++ b/website/landing/content.ts @@ -1,7 +1,14 @@ // Copy shared by every landing variant, so the three designs differ in // presentation only and stay truthful to what DevSpace actually ships. -export const INSTALL = "npx @waishnav/devspace init"; +// The first method is the server-rendered default; the page switches to the visitor's OS on load. +export const INSTALL_METHODS = [ + { id: "unix", label: "macOS / Linux", command: "curl -fsSL https://devspace.run/install | sh" }, + { id: "windows", label: "Windows", command: 'powershell -c "irm https://devspace.run/install.ps1 | iex"' }, + { id: "npm", label: "npm", command: "npm install -g @waishnav/devspace" }, +] as const; + +export const INSTALL = INSTALL_METHODS[0].command; export const GITHUB = "https://github.com/Waishnav/devspace"; export const NPM = "https://www.npmjs.com/package/@waishnav/devspace"; export const DOCS = "/docs"; diff --git a/website/landing/home/InstallCommand.astro b/website/landing/home/InstallCommand.astro new file mode 100644 index 000000000..7034fdf88 --- /dev/null +++ b/website/landing/home/InstallCommand.astro @@ -0,0 +1,62 @@ +--- +// Tabs for choosing an install method. The script preselects the visitor's OS and keeps every tab group and +// every [data-install-command] button (whose data-copy and show the command) on the same choice. +import { INSTALL_METHODS } from "../content"; + +const [initial] = INSTALL_METHODS; +--- + +
+ {INSTALL_METHODS.map((method) => ( + + ))} +
+ + + + diff --git a/website/landing/home/Landing.astro b/website/landing/home/Landing.astro index a36e722cc..88dcb764f 100644 --- a/website/landing/home/Landing.astro +++ b/website/landing/home/Landing.astro @@ -8,6 +8,7 @@ import Icon from "../Icon.astro"; import PixelField from "./PixelField.astro"; import HeroStage from "./HeroStage.astro"; import WorkflowStage from "./WorkflowStage.astro"; +import InstallCommand from "./InstallCommand.astro"; import { Code } from "astro:components"; import { workbenchLightTheme } from "./theme"; import Logo from "../../logos/Logo.astro"; @@ -31,7 +32,7 @@ effort: high Roadmap GitHub - @@ -49,8 +50,9 @@ effort: high edits, runs tests, and shows you the diff. Then it lets that AI hand work to Codex, Claude Code, and other agents.

+
- @@ -144,8 +146,9 @@ effort: high

Stop deciding what to prompt next.

+
- Star on GitHub → @@ -209,6 +212,8 @@ effort: high .btn--ghost:hover { border-color: var(--ink); } .btn--lg { padding: 16px 24px; } .btn code { font: inherit; } + .btn--command { max-width: 100%; text-align: left; } + .btn--command code { overflow-wrap: anywhere; } .btn__idle, .btn__done { display: inline-flex; } .btn__done, .btn[data-copied] .btn__idle { display: none; } .btn[data-copied] .btn__done { display: inline-flex; } From 025608e8d11cfc027d2fa219c46a156fd7cae379 Mon Sep 17 00:00:00 2001 From: Waishnav <86405648+Waishnav@users.noreply.github.com> Date: Fri, 30 Oct 2026 12:38:45 +0530 Subject: [PATCH 4/6] feat(install): default the installers to the latest release v1.1 is stable, so latest no longer needs install scripts. Co-Authored-By: Claude Opus 5.5 --- install/install.ps1 | 6 ++---- install/install.sh | 6 ++---- 2 files changed, 4 insertions(+), 8 deletions(-) diff --git a/install/install.ps1 b/install/install.ps1 index c23ad0726..d94348881 100644 --- a/install/install.ps1 +++ b/install/install.ps1 @@ -6,16 +6,14 @@ # for DevSpace alone, installs @waishnav/devspace into a user-owned npm prefix, writes `devspace` launchers that # pin that Node, then runs `devspace init`. Rerun it to update. DevSpace itself also needs Git Bash on Windows. # -# Environment overrides: DEVSPACE_VERSION (default: beta), DEVSPACE_INSTALL_DIR, DEVSPACE_BIN_DIR, DEVSPACE_NO_INIT=1, +# Environment overrides: DEVSPACE_VERSION (default: latest), DEVSPACE_INSTALL_DIR, DEVSPACE_BIN_DIR, DEVSPACE_NO_INIT=1, # DEVSPACE_NO_MODIFY_PATH=1, DEVSPACE_PACKAGE_SPEC (see install.sh). $ErrorActionPreference = "Stop" $ProgressPreference = "SilentlyContinue" $Package = "@waishnav/devspace" -# v1.1 is the first release installable without install scripts, and it is still on the beta tag. -# Switch this to latest once v1.1 ships as stable. -$Version = if ($env:DEVSPACE_VERSION) { $env:DEVSPACE_VERSION } else { "beta" } +$Version = if ($env:DEVSPACE_VERSION) { $env:DEVSPACE_VERSION } else { "latest" } $PackageSpec = if ($env:DEVSPACE_PACKAGE_SPEC) { $env:DEVSPACE_PACKAGE_SPEC } else { "$Package@$Version" } $InstallDir = if ($env:DEVSPACE_INSTALL_DIR) { $env:DEVSPACE_INSTALL_DIR } else { Join-Path $env:LOCALAPPDATA "devspace\install" } $BinDir = if ($env:DEVSPACE_BIN_DIR) { $env:DEVSPACE_BIN_DIR } else { Join-Path $env:LOCALAPPDATA "devspace\bin" } diff --git a/install/install.sh b/install/install.sh index c6e42fa22..9e5afe6db 100755 --- a/install/install.sh +++ b/install/install.sh @@ -8,7 +8,7 @@ # Node, then runs `devspace init`. Rerun it to update. # # Environment overrides: -# DEVSPACE_VERSION npm version or dist-tag to install (default: beta) +# DEVSPACE_VERSION npm version or dist-tag to install (default: latest) # DEVSPACE_INSTALL_DIR runtime and package location (default: ~/.local/share/devspace/install) # DEVSPACE_BIN_DIR launcher location (default: ~/.local/bin) # DEVSPACE_NO_INIT=1 skip running `devspace init` afterwards @@ -18,9 +18,7 @@ set -eu PACKAGE="@waishnav/devspace" -# v1.1 is the first release installable without install scripts, and it is still on the beta tag. -# Switch this to latest once v1.1 ships as stable. -VERSION="${DEVSPACE_VERSION:-beta}" +VERSION="${DEVSPACE_VERSION:-latest}" PACKAGE_SPEC="${DEVSPACE_PACKAGE_SPEC:-$PACKAGE@$VERSION}" INSTALL_DIR="${DEVSPACE_INSTALL_DIR:-$HOME/.local/share/devspace/install}" BIN_DIR="${DEVSPACE_BIN_DIR:-$HOME/.local/bin}" From 4ee35fff3e91c8a0d7ae9f2f9d7f8484b18b9ef7 Mon Sep 17 00:00:00 2001 From: Waishnav <86405648+Waishnav@users.noreply.github.com> Date: Fri, 30 Oct 2026 18:09:57 +0530 Subject: [PATCH 5/6] fix(website): restore 1.0.x SQLite repair and use toggle buttons Keep the better-sqlite3 troubleshooting entry, scoped to 1.0.x installs that still ship the native module, and lead with upgrading. The install method picker had tab roles without tab keyboard behavior; it is a group of toggle buttons with aria-pressed instead. Co-Authored-By: Claude Opus 5.5 --- website/docs/reference/troubleshooting.mdx | 13 +++++++++++++ website/landing/home/InstallCommand.astro | 12 ++++++------ 2 files changed, 19 insertions(+), 6 deletions(-) diff --git a/website/docs/reference/troubleshooting.mdx b/website/docs/reference/troubleshooting.mdx index cdb78c79d..e606f516a 100644 --- a/website/docs/reference/troubleshooting.mdx +++ b/website/docs/reference/troubleshooting.mdx @@ -17,6 +17,19 @@ Bash, public URL, allowed hosts, and SQLite status. or `mise`. + + DevSpace 1.1 uses Node's built-in SQLite, so this only affects 1.0.x + installs, whose native SQLite module was built for a different Node runtime. + The simplest fix is to upgrade with the installer above. To stay on 1.0.x, + reinstall with the Node you run DevSpace with, then rerun `doctor`: + + - global install: `npm install -g @waishnav/devspace@1.0.8` + - npx: remove only DevSpace's cached copy, then rerun the `npx` command. + With npm 11.2 or newer, find its key in `npm cache npx ls` and run + `npm cache npx rm `. With older npm, switch to a global install. + - local project install: `npm rebuild better-sqlite3` in that project + + Setup wants the origin (`https://host`); the client wants the endpoint (`https://host/mcp`). Fix it with diff --git a/website/landing/home/InstallCommand.astro b/website/landing/home/InstallCommand.astro index 7034fdf88..f5a5ccf45 100644 --- a/website/landing/home/InstallCommand.astro +++ b/website/landing/home/InstallCommand.astro @@ -1,16 +1,16 @@ --- -// Tabs for choosing an install method. The script preselects the visitor's OS and keeps every tab group and +// Toggle buttons for choosing an install method. The script preselects the visitor's OS and keeps every group and // every [data-install-command] button (whose data-copy and show the command) on the same choice. import { INSTALL_METHODS } from "../content"; const [initial] = INSTALL_METHODS; --- -
+
{INSTALL_METHODS.map((method) => ( ))}
@@ -22,7 +22,7 @@ const [initial] = INSTALL_METHODS; font: inherit; color: var(--muted); cursor: pointer; } .install__tab:hover { color: var(--ink); } - .install__tab[aria-selected="true"] { color: var(--ink); border-bottom-color: var(--ink); } + .install__tab[aria-pressed="true"] { color: var(--ink); border-bottom-color: var(--ink); }