From 447df9d2319c7ebd38f0cadc87ab1755553c8f03 Mon Sep 17 00:00:00 2001 From: Akshit Kr Nagpal Date: Thu, 19 Nov 2026 20:11:19 +0530 Subject: [PATCH 1/6] Add toolstile server to run Toolstile locally `npx toolstile server start` downloads the toolstile-server executable for this platform from the latest release, checks it against its published SHA-256 checksum and installs it in ~/.local/share/toolstile-server. On a new instance it runs init, asks for an email and prints the invitation link, then runs the server in the foreground and passes Ctrl-C on once so the server drains. install, upgrade and uninstall manage the executable: upgrade refuses while the instance runs, backs it up first and keeps the previous executable. Other server commands run toolstile-server directly. Co-Authored-By: Claude Opus 5.5 --- README.md | 31 +++++ src/cli.ts | 77 +++++++++++ src/server.ts | 317 ++++++++++++++++++++++++++++++++++++++++++++ test/server.test.ts | 179 +++++++++++++++++++++++++ 4 files changed, 604 insertions(+) create mode 100644 src/server.ts create mode 100644 test/server.test.ts diff --git a/README.md b/README.md index d222305..c2180f0 100644 --- a/README.md +++ b/README.md @@ -280,6 +280,37 @@ redirect. | `--workspace ` | `mcp setup` | Toolstile Cloud workspace the agents use (default: the last one, or personal) | | `--device-name ` | `mcp setup` | Name for this machine in the dashboard (default: its hostname) | +## Run Toolstile on your machine + +Toolstile's open-source server runs as one executable with its own embedded +database: no Docker, database server or Node.js setup. The CLI downloads it, +checks it against its published SHA-256 checksum and starts it: + +```sh +npx toolstile server start +``` + +On a new instance it asks for your email and prints an invitation link, then +runs the server at `http://127.0.0.1:4310` until you press Ctrl-C. Open the +link, create your account and follow the guided setup. Connect Claude Code to +your own server with: + +```sh +claude mcp add --transport http toolstile http://127.0.0.1:4310/mcp +``` + +| Command | What it does | +| --- | --- | +| `server start [--email ]` | Installs on first use, initializes and invites on a new instance, then runs the server | +| `server install [--release ] [--from ]` | Installs the latest release, a named one or a file you built | +| `server upgrade` | Refuses while the server runs; backs up the instance, then installs the latest release and keeps the previous executable | +| `server uninstall` | Removes the executable; your data and backups stay | +| `server bootstrap`, `operator`, `backup`, `restore`, `version` | Run the server's own commands | + +Builds exist for macOS on Apple silicon and Linux (x64 and arm64). The executable +lives in `~/.local/share/toolstile-server` (`$TOOLSTILE_SERVER_HOME`), its data in +`~/.local/share/toolstile` (`--data-dir` or `$TOOLSTILE_DATA_DIR`). + ## Use it from code ```ts diff --git a/src/cli.ts b/src/cli.ts index bae361e..e58dafc 100644 --- a/src/cli.ts +++ b/src/cli.ts @@ -6,6 +6,7 @@ import { createApi } from "./api.js"; import { renderCard, shareText, shareUrl } from "./card.js"; import { type Context, login, logout, proxy, setup, status, UserError, whoami } from "./commands.js"; import { runFix } from "./fix.js"; +import { install, passthrough, ServerError, split, start, uninstall, upgrade, type ServerContext } from "./server.js"; import { audit } from "./index.js"; import { redact, renderJson, renderReport, style } from "./report.js"; import type { Severity } from "./types.js"; @@ -20,6 +21,7 @@ Usage npx toolstile auth status List the servers this machine is signed in to npx toolstile whoami Show the account on the current server npx toolstile mcp setup Choose which agents here use Toolstile + npx toolstile server start Run your own Toolstile on this machine The auth, whoami and mcp commands work with Toolstile Cloud (the default), a self-hosted server (--server ) or the server on this machine (--local). @@ -136,6 +138,37 @@ Agents: claude-code, claude-desktop, cursor, codex, vscode, windsurf, devin, gem grok, opencode, kiro, antigravity `; +const SERVER_HELP = `toolstile server: run your own Toolstile on this machine + +Usage + npx toolstile server start [--email ] [options] + npx toolstile server install [--release ] [--from ] + npx toolstile server upgrade [--release ] [--from ] + npx toolstile server uninstall + npx toolstile server ... + +start downloads toolstile-server, a single executable with its own database, +on first use. On a new instance it asks for your email and prints an +invitation link, then runs the server until you press Ctrl-C. Open the link, +create your account and follow the guided setup. + +upgrade refuses while the server is running, backs up the instance first and +keeps the executable it replaces. uninstall keeps your data. Other commands +run toolstile-server directly; see its local operation guide: +https://github.com/toolstile/toolstile/blob/main/docs/local-operation.md + +Options for start + --email
Invite this account without asking + --data-dir Instance folder (default ~/.local/share/toolstile, or TOOLSTILE_DATA_DIR) + --origin New instance only: its address (default http://127.0.0.1:4310) + --listen
New instance only: interface to listen on (default 127.0.0.1) + --port New instance only: port (default 4310) + +Options for install and upgrade + --release A specific release (default: the latest) + --from Install a toolstile-server you built or downloaded yourself +`; + function version(): string { const pkg = JSON.parse(readFileSync(new URL("../package.json", import.meta.url), "utf8")) as { version: string }; return pkg.version; @@ -326,10 +359,54 @@ async function command(argv: string[]): Promise { } } +async function server(argv: string[]): Promise { + const [action, ...rest] = argv; + if (!action || action === "-h" || action === "--help" || action === "help") { + process.stdout.write(SERVER_HELP); + return action ? 0 : 2; + } + if (rest.includes("-h") || rest.includes("--help")) { + if (["start", "install", "upgrade", "uninstall"].includes(action)) { + process.stdout.write(SERVER_HELP); + return 0; + } + } + const ctx: ServerContext = { + home: homedir(), + env: process.env, + platform: process.platform, + arch: process.arch, + fetch: (...args) => fetch(...args), + stdin: process.stdin, + stdout: process.stdout, + stderr: process.stderr, + style: style(process.stderr.isTTY === true && !process.env.NO_COLOR), + }; + try { + if (action === "start") return await start(ctx, rest); + if (action === "install") { + const { own, rest: unknown } = split(rest, ["--release", "--from"]); + if (unknown.length) throw new ServerError(`Unknown option: ${unknown[0]}`); + await install(ctx, { release: own["--release"], from: own["--from"] }); + return 0; + } + if (action === "upgrade") return await upgrade(ctx, rest); + if (action === "uninstall") return uninstall(ctx); + return await passthrough(ctx, argv); + } catch (error) { + if (error instanceof ServerError) { + process.stderr.write(`toolstile: ${error.message}\n`); + return 1; + } + throw error; + } +} + async function main(): Promise { const argv = process.argv.slice(2); if (argv[0] === "whoami") return command(["auth", ...argv]); if (argv[0] === "auth" || argv[0] === "mcp") return command(argv); + if (argv[0] === "server") return server(argv.slice(1)); const help = argv[0] === "audit" ? AUDIT_HELP : HELP; let args: ReturnType; try { diff --git a/src/server.ts b/src/server.ts new file mode 100644 index 0000000..582c976 --- /dev/null +++ b/src/server.ts @@ -0,0 +1,317 @@ +import { spawn } from "node:child_process"; +import { createHash } from "node:crypto"; +import { createReadStream, createWriteStream, existsSync, mkdirSync, readFileSync, renameSync, rmSync } from "node:fs"; +import { homedir } from "node:os"; +import { join, resolve } from "node:path"; +import { createInterface } from "node:readline"; +import { Readable, Transform } from "node:stream"; +import { pipeline } from "node:stream/promises"; +import { createBrotliDecompress } from "node:zlib"; +import type { Style } from "./report.js"; + +/** Where release executables are published; `TOOLSTILE_SERVER_DOWNLOAD_URL` replaces it. */ +export const RELEASES = "https://github.com/toolstile/toolstile/releases"; +/** Platforms with a published `toolstile-server` build. */ +export const PLATFORMS = ["darwin-arm64", "linux-arm64", "linux-x64"]; +const NAME = "toolstile-server"; + +export interface ServerContext { + home: string; + env: Record; + platform: NodeJS.Platform; + arch: string; + fetch: typeof fetch; + stdin: NodeJS.ReadableStream & { isTTY?: boolean }; + stdout: NodeJS.WritableStream & { isTTY?: boolean }; + stderr: NodeJS.WritableStream & { isTTY?: boolean }; + style: Style; + /** Runs the executable with inherited stdio and resolves to its exit code. */ + run?: (file: string, args: string[]) => Promise; +} + +/** A failure explained to the user; exits 1 without a stack trace. */ +export class ServerError extends Error {} + +/** `TOOLSTILE_SERVER_HOME`, else `toolstile-server` in the per-user data folder. */ +export function serverHome({ home, env }: Pick): string { + if (env.TOOLSTILE_SERVER_HOME) return resolve(env.TOOLSTILE_SERVER_HOME); + return join(env.XDG_DATA_HOME ?? join(home, ".local", "share"), NAME); +} +export const executablePath = (ctx: Pick) => join(serverHome(ctx), NAME); + +/** The instance folder `toolstile-server` uses: `--data-dir`, `TOOLSTILE_DATA_DIR` or its default. */ +export function dataDir(ctx: Pick, args: string[]): string { + const i = args.findIndex((a) => a === "--data-dir" || a.startsWith("--data-dir=")); + const given = i === -1 ? undefined : args[i]!.includes("=") ? args[i]!.slice(args[i]!.indexOf("=") + 1) : args[i + 1]; + return resolve(given ?? ctx.env.TOOLSTILE_DATA_DIR ?? join(ctx.home, ".local", "share", "toolstile")); +} + +function target(ctx: Pick): string { + const id = `${ctx.platform}-${ctx.arch}`; + if (!PLATFORMS.includes(id)) + throw new ServerError( + `There is no toolstile-server build for ${id} yet (available: ${PLATFORMS.join(", ")}). Run it from source instead: https://github.com/toolstile/toolstile/blob/main/docs/local-operation.md`, + ); + return `${NAME}-${id}`; +} + +/** Release download folder for `release` (`latest` or a tag). */ +export function downloadBase(ctx: Pick, release = "latest"): string { + const custom = ctx.env.TOOLSTILE_SERVER_DOWNLOAD_URL; + if (custom) { + const url = new URL(custom); + if (url.protocol !== "https:" && !(url.protocol === "http:" && /^(localhost|127\.\d+\.\d+\.\d+|\[::1\])$/.test(url.hostname))) + throw new ServerError("TOOLSTILE_SERVER_DOWNLOAD_URL must use https://"); + return url.href.replace(/\/$/, ""); + } + return release === "latest" ? `${RELEASES}/latest/download` : `${RELEASES}/download/${encodeURIComponent(release)}`; +} + +const say = (ctx: ServerContext, text = "") => ctx.stderr.write(`${text}\n`); + +function runner(ctx: ServerContext) { + return ( + ctx.run ?? + ((file: string, args: string[]) => + new Promise((done, fail) => { + // In its own process group, Ctrl-C reaches only this process, which passes each + // signal on once: the server treats a second SIGINT as "stop without draining". + const child = spawn(file, args, { stdio: "inherit", detached: true }); + const signals = ["SIGINT", "SIGTERM", "SIGHUP"] as const; + const forward = (signal: NodeJS.Signals) => child.kill(signal); + for (const signal of signals) process.on(signal, forward); + child.once("error", fail); + child.once("exit", (code, signal) => { + for (const s of signals) process.off(s, forward); + done(code ?? (signal ? 1 : 0)); + }); + })) + ); +} + +/** Output of a short command, for `version`. */ +function capture(file: string, args: string[]): Promise { + return new Promise((done, fail) => { + const child = spawn(file, args, { stdio: ["ignore", "pipe", "pipe"] }); + let out = ""; + child.stdout.on("data", (chunk) => (out += chunk)); + child.once("error", fail); + child.once("exit", (code) => (code === 0 ? done(out.trim()) : fail(new Error(`exited with ${code}`)))); + }); +} + +async function get(ctx: ServerContext, url: string): Promise { + let response: Response; + try { + response = await ctx.fetch(url, { redirect: "follow" }); + } catch (error) { + throw new ServerError(`Could not download ${url}: ${(error as Error).message}`); + } + if (response.status === 404) + throw new ServerError(`${url} was not found. Check the release name, or that this release has a build for your platform.`); + if (!response.ok || !response.body) throw new ServerError(`Downloading ${url} failed (HTTP ${response.status})`); + return response; +} + +/** Counts bytes through the stream and redraws a progress line on a terminal. */ +function progress(ctx: ServerContext, total: number) { + let seen = 0; + let shown = -1; + return new Transform({ + transform(chunk: Buffer, _encoding, next) { + seen += chunk.length; + const percent = total ? Math.floor((seen / total) * 100) : -1; + if (ctx.stderr.isTTY && percent !== shown) { + shown = percent; + const mb = (seen / 1048576).toFixed(1); + ctx.stderr.write(`\r ${total ? `${percent}% ` : ""}${mb} MB`); + } + next(null, chunk); + }, + flush(done) { + if (ctx.stderr.isTTY) ctx.stderr.write("\r\x1b[2K"); + done(); + }, + }); +} + +/** + * Download (or copy `from`), verify and install the executable, keeping the one it replaces + * as `toolstile-server.previous`. Returns the installed version. + */ +export async function install(ctx: ServerContext, options: { release?: string; from?: string } = {}): Promise { + const destination = executablePath(ctx); + mkdirSync(serverHome(ctx), { recursive: true, mode: 0o700 }); + const temporary = `${destination}.download-${process.pid}`; + try { + if (options.from) { + const source = resolve(options.from); + if (!existsSync(source)) throw new ServerError(`${source} does not exist`); + say(ctx, `Installing ${source}`); + const output = createWriteStream(temporary, { mode: 0o755 }); + if (source.endsWith(".br")) await pipeline(createReadStream(source), createBrotliDecompress(), output); + else await pipeline(createReadStream(source), output); + } else { + const name = target(ctx); + const base = downloadBase(ctx, options.release); + const sums = await (await get(ctx, `${base}/${name}.sha256`)).text(); + const expected = sums.trim().split(/\s+/)[0] ?? ""; + if (!/^[a-f0-9]{64}$/.test(expected)) throw new ServerError(`${base}/${name}.sha256 is not a SHA-256 checksum`); + const response = await get(ctx, `${base}/${name}.br`); + say(ctx, `Downloading ${name} (${options.release ?? "latest"})`); + const hash = createHash("sha256"); + await pipeline( + Readable.fromWeb(response.body as import("node:stream/web").ReadableStream), + progress(ctx, Number(response.headers.get("content-length")) || 0), + createBrotliDecompress(), + new Transform({ + transform(chunk: Buffer, _encoding, next) { + hash.update(chunk); + next(null, chunk); + }, + }), + createWriteStream(temporary, { mode: 0o755 }), + ); + if (hash.digest("hex") !== expected) + throw new ServerError("The download does not match its published checksum, so it was not installed. Try again."); + } + let version: string; + try { + version = await capture(temporary, ["version"]); + } catch (error) { + throw new ServerError(`The downloaded executable does not run on this machine (${(error as Error).message})`); + } + if (existsSync(destination)) renameSync(destination, `${destination}.previous`); + renameSync(temporary, destination); + say(ctx, `Installed toolstile-server ${version} at ${destination}`); + return version; + } finally { + rmSync(temporary, { force: true }); + } +} + +/** Whether a process still owns the instance's database, as the server records it. */ +export function running(directory: string): number | undefined { + try { + const pid = Number(readFileSync(join(directory, "pglite.owner"), "utf8")); + if (!Number.isSafeInteger(pid) || pid < 1) return undefined; + process.kill(pid, 0); + return pid; + } catch { + return undefined; + } +} + +async function ask(ctx: ServerContext, question: string): Promise { + const lines = createInterface({ input: ctx.stdin, output: ctx.stderr }); + try { + return await new Promise((done) => lines.question(question, (answer) => done(answer.trim()))); + } finally { + lines.close(); + } +} + +/** Options only `init` reads; `start` passes them on when it creates the instance. */ +const INIT_OPTIONS = ["--origin", "--listen", "--port"]; + +/** Separate `names` (each taking a value) from the other arguments. */ +export function split(args: string[], names: string[]) { + const own: Record = {}; + const rest: string[] = []; + const forward: string[] = []; + for (let i = 0; i < args.length; i++) { + const a = args[i]!; + const eq = a.indexOf("="); + const name = eq === -1 ? a : a.slice(0, eq); + if (names.includes(name)) { + const value = eq === -1 ? args[++i] : a.slice(eq + 1); + if (value === undefined || value.startsWith("-")) throw new ServerError(`${name} needs a value`); + own[name] = value; + forward.push(name, value); + } else rest.push(a); + } + return { own, rest, forward }; +} + +/** + * `toolstile server start`: install on first use, initialize and invite the first account on + * a new instance, then run the server in the foreground. + */ +export async function start(ctx: ServerContext, args: string[]): Promise { + const { own, rest: other } = split(args, ["--email", "--data-dir"]); + const { forward: initArgs, rest } = split(other, INIT_OPTIONS); + const run = runner(ctx); + const executable = executablePath(ctx); + if (!existsSync(executable)) await install(ctx); + const directory = dataDir(ctx, own["--data-dir"] ? ["--data-dir", own["--data-dir"]] : []); + const pid = running(directory); + if (pid) throw new ServerError(`The instance in ${directory} is already running (process ${pid})`); + const data = ["--data-dir", directory]; + let email = own["--email"]; + if (!existsSync(join(directory, "instance.json"))) { + if ((await run(executable, ["init", ...initArgs, ...data])) !== 0) return 1; + if (!email && ctx.stdin.isTTY) email = await ask(ctx, "Email for your account (enter to skip): "); + if (!email) say(ctx, "Invite an account later with: npx toolstile server bootstrap you@example.com"); + } else if (initArgs.length) + throw new ServerError(`${directory} is already initialized; --origin, --listen and --port apply only to a new instance.`); + if (email) { + if ((await run(executable, ["bootstrap", email, ...data])) !== 0) return 1; + say(ctx, ctx.style.dim("Open the invitation link once the server is listening, then create your account.")); + } + const origin = instanceOrigin(directory); + if (origin) say(ctx, `Connect Claude Code: claude mcp add --transport http toolstile ${origin}/mcp`); + return run(executable, ["start", ...rest, ...data]); +} + +function instanceOrigin(directory: string): string | undefined { + try { + const origin = JSON.parse(readFileSync(join(directory, "instance.json"), "utf8")).origin; + return typeof origin === "string" ? origin : undefined; + } catch { + return undefined; + } +} + +/** Install a newer executable after backing up a stopped instance. */ +export async function upgrade(ctx: ServerContext, args: string[]): Promise { + const { own, rest } = split(args, ["--release", "--from"]); + const executable = executablePath(ctx); + if (!existsSync(executable)) { + await install(ctx, { release: own["--release"], from: own["--from"] }); + return 0; + } + const directory = dataDir(ctx, rest); + const pid = running(directory); + if (pid) throw new ServerError(`Stop the server first (process ${pid}), then upgrade.`); + const current = await capture(executable, ["version"]).catch(() => "unknown"); + if (existsSync(join(directory, "instance.json"))) { + const backup = join(serverHome(ctx), "backups", `${new Date().toISOString().replace(/[:.]/g, "-")}-${current.replace(/[^\w.-]/g, "_")}`); + mkdirSync(join(serverHome(ctx), "backups"), { recursive: true, mode: 0o700 }); + if ((await runner(ctx)(executable, ["backup", backup, "--data-dir", directory])) !== 0) + throw new ServerError("The backup failed, so nothing was upgraded."); + say(ctx, `Backed up the instance to ${backup}`); + } + const next = await install(ctx, { release: own["--release"], from: own["--from"] }); + say(ctx, `Upgraded ${current} → ${next}. The previous executable is ${executable}.previous; start the server to apply migrations.`); + return 0; +} + +/** Remove the executables; the instance and its backups stay. */ +export function uninstall(ctx: ServerContext): number { + const executable = executablePath(ctx); + if (!existsSync(executable)) { + say(ctx, "toolstile-server is not installed."); + return 0; + } + rmSync(executable, { force: true }); + rmSync(`${executable}.previous`, { force: true }); + say(ctx, `Removed ${executable}. Instance data and backups were kept.`); + return 0; +} + +/** Run an installed `toolstile-server` command. */ +export async function passthrough(ctx: ServerContext, args: string[]): Promise { + const executable = executablePath(ctx); + if (!existsSync(executable)) throw new ServerError("toolstile-server is not installed. Run: npx toolstile server install"); + return runner(ctx)(executable, args); +} diff --git a/test/server.test.ts b/test/server.test.ts new file mode 100644 index 0000000..58dc26e --- /dev/null +++ b/test/server.test.ts @@ -0,0 +1,179 @@ +import { createHash } from "node:crypto"; +import { existsSync, mkdirSync, mkdtempSync, readFileSync, readdirSync, rmSync, writeFileSync } from "node:fs"; +import { tmpdir } from "node:os"; +import { join } from "node:path"; +import { PassThrough } from "node:stream"; +import { brotliCompressSync } from "node:zlib"; +import { afterEach, beforeEach, describe, expect, it } from "vite-plus/test"; +import { style } from "../src/report.js"; +import { + dataDir, + downloadBase, + executablePath, + install, + type ServerContext, + ServerError, + serverHome, + start, + uninstall, + upgrade, +} from "../src/server.js"; + +let home: string; +beforeEach(() => { + home = mkdtempSync(join(tmpdir(), "toolstile-server-")); +}); +afterEach(() => rmSync(home, { recursive: true, force: true })); + +/** A stand-in for toolstile-server: a script that prints its version. */ +const script = (version: string) => Buffer.from(`#!/bin/sh\necho ${version}\n`); +const sha256 = (data: Buffer) => createHash("sha256").update(data).digest("hex"); + +function context(files: Record = {}, overrides: Partial = {}) { + const requests: string[] = []; + const calls: string[][] = []; + const stderr = new PassThrough(); + let err = ""; + stderr.on("data", (chunk) => (err += chunk)); + const ctx: ServerContext = { + home, + env: { TOOLSTILE_SERVER_DOWNLOAD_URL: "https://releases.test/v1" }, + platform: "linux", + arch: "x64", + fetch: (async (url: string) => { + requests.push(url); + const file = files[url.replace("https://releases.test/v1/", "")]; + return file === undefined ? new Response("missing", { status: 404 }) : new Response(typeof file === "string" ? file : new Uint8Array(file)); + }) as typeof fetch, + stdin: new PassThrough(), + stdout: new PassThrough(), + stderr, + style: style(false), + run: async (file, args) => { + calls.push([file, ...args]); + return 0; + }, + ...overrides, + }; + return { ctx, requests, calls, stderr: () => err }; +} + +function release(version: string, checksum?: string) { + const executable = script(version); + return { + "toolstile-server-linux-x64.br": brotliCompressSync(executable), + "toolstile-server-linux-x64.sha256": `${checksum ?? sha256(executable)} toolstile-server-linux-x64\n`, + }; +} + +describe.skipIf(process.platform === "win32")("toolstile server", () => { + it("keeps the executable apart from the instance it serves", () => { + const { ctx } = context(); + expect(serverHome(ctx)).toBe(join(home, ".local", "share", "toolstile-server")); + expect(serverHome({ home, env: { XDG_DATA_HOME: join(home, "xdg") } })).toBe(join(home, "xdg", "toolstile-server")); + expect(dataDir(ctx, [])).toBe(join(home, ".local", "share", "toolstile")); + expect(dataDir({ home, env: { TOOLSTILE_DATA_DIR: "/srv/a" } }, [])).toBe("/srv/a"); + expect(dataDir(ctx, ["start", "--data-dir", "/srv/b"])).toBe("/srv/b"); + expect(dataDir(ctx, ["--data-dir=/srv/c"])).toBe("/srv/c"); + }); + + it("downloads the latest release or a named one, and only over HTTPS", () => { + expect(downloadBase({ env: {} })).toBe("https://github.com/toolstile/toolstile/releases/latest/download"); + expect(downloadBase({ env: {} }, "v1.2.0")).toBe("https://github.com/toolstile/toolstile/releases/download/v1.2.0"); + expect(downloadBase({ env: { TOOLSTILE_SERVER_DOWNLOAD_URL: "http://127.0.0.1:9000/" } })).toBe("http://127.0.0.1:9000"); + expect(() => downloadBase({ env: { TOOLSTILE_SERVER_DOWNLOAD_URL: "http://example.com" } })).toThrow(ServerError); + }); + + it("installs a verified download and keeps the executable it replaces", async () => { + const first = context(release("1.0.0")); + expect(await install(first.ctx)).toBe("1.0.0"); + expect(first.requests).toEqual([ + "https://releases.test/v1/toolstile-server-linux-x64.sha256", + "https://releases.test/v1/toolstile-server-linux-x64.br", + ]); + const path = executablePath(first.ctx); + expect(readFileSync(path)).toEqual(script("1.0.0")); + expect(await install(context(release("1.1.0")).ctx)).toBe("1.1.0"); + expect(readFileSync(path)).toEqual(script("1.1.0")); + expect(readFileSync(`${path}.previous`)).toEqual(script("1.0.0")); + }); + + it("refuses a download that does not match its checksum and leaves nothing behind", async () => { + const { ctx } = context(release("1.0.0", "0".repeat(64))); + await expect(install(ctx)).rejects.toThrow(/does not match its published checksum/); + expect(readdirSync(serverHome(ctx))).toEqual([]); + }); + + it("explains a missing release and an unsupported platform", async () => { + await expect(install(context().ctx)).rejects.toThrow(/was not found/); + await expect(install(context(release("1.0.0"), { platform: "win32" }).ctx)).rejects.toThrow(/no toolstile-server build for win32-x64/); + }); + + it("installs a local build, compressed or not", async () => { + const { ctx } = context(); + const raw = join(home, "toolstile-server"); + writeFileSync(raw, script("2.0.0")); + expect(await install(ctx, { from: raw })).toBe("2.0.0"); + writeFileSync(`${raw}.br`, brotliCompressSync(script("2.1.0"))); + expect(await install(ctx, { from: `${raw}.br` })).toBe("2.1.0"); + }); + + it("initializes and invites on first start, then serves the same folder", async () => { + const { ctx, calls } = context(release("1.0.0")); + const data = join(home, "instance"); + const code = await start(ctx, ["--data-dir", data, "--email", "you@example.com", "--port", "4500"]); + expect(code).toBe(0); + const exe = executablePath(ctx); + expect(calls).toEqual([ + [exe, "init", "--port", "4500", "--data-dir", data], + [exe, "bootstrap", "you@example.com", "--data-dir", data], + [exe, "start", "--data-dir", data], + ]); + }); + + it("starts an existing instance without initializing it again", async () => { + const { ctx, calls } = context(release("1.0.0")); + const data = join(home, "instance"); + mkdirSync(data); + writeFileSync(join(data, "instance.json"), JSON.stringify({ origin: "http://127.0.0.1:4310" })); + await start(ctx, ["--data-dir", data]); + expect(calls.map((c) => c[1])).toEqual(["start"]); + await expect(start(ctx, ["--data-dir", data, "--port", "1"])).rejects.toThrow(/already initialized/); + }); + + it("refuses to start or upgrade an instance that is running", async () => { + const { ctx } = context(release("1.0.0")); + await install(ctx); + const data = join(home, "instance"); + mkdirSync(data); + writeFileSync(join(data, "instance.json"), "{}"); + writeFileSync(join(data, "pglite.owner"), String(process.pid)); + await expect(start(ctx, ["--data-dir", data])).rejects.toThrow(/already running/); + await expect(upgrade(ctx, ["--data-dir", data])).rejects.toThrow(/Stop the server first/); + }); + + it("backs up a stopped instance before upgrading", async () => { + const { ctx, calls } = context(release("1.0.0")); + await install(ctx); + const data = join(home, "instance"); + mkdirSync(data); + writeFileSync(join(data, "instance.json"), "{}"); + expect(await upgrade(ctx, ["--data-dir", data])).toBe(0); + expect(calls).toHaveLength(1); + expect(calls[0]!.slice(1, 2)).toEqual(["backup"]); + expect(calls[0]![2]).toContain(join(serverHome(ctx), "backups")); + expect(calls[0]!.slice(3)).toEqual(["--data-dir", data]); + expect(existsSync(`${executablePath(ctx)}.previous`)).toBe(true); + }); + + it("uninstalls the executables and keeps the instance", async () => { + const { ctx } = context(release("1.0.0")); + await install(ctx); + const data = join(home, ".local", "share", "toolstile"); + mkdirSync(data, { recursive: true }); + writeFileSync(join(data, "instance.json"), "{}"); + expect(uninstall(ctx)).toBe(0); + expect(existsSync(executablePath(ctx))).toBe(false); + expect(existsSync(join(data, "instance.json"))).toBe(true); + }); +}); From 2d38561650c6f755afdf302bad28487ca8d0be76 Mon Sep 17 00:00:00 2001 From: Akshit Kr Nagpal Date: Thu, 19 Nov 2026 20:18:54 +0530 Subject: [PATCH 2/6] Pass Ctrl-C on once, check redirects and guard upgrade Co-Authored-By: Claude Opus 5.5 --- src/server.ts | 75 ++++++++++++++++++++++++++++++++------------- test/server.test.ts | 26 +++++++++++++++- 2 files changed, 79 insertions(+), 22 deletions(-) diff --git a/src/server.ts b/src/server.ts index 582c976..831f307 100644 --- a/src/server.ts +++ b/src/server.ts @@ -60,7 +60,7 @@ export function downloadBase(ctx: Pick, release = "latest" const custom = ctx.env.TOOLSTILE_SERVER_DOWNLOAD_URL; if (custom) { const url = new URL(custom); - if (url.protocol !== "https:" && !(url.protocol === "http:" && /^(localhost|127\.\d+\.\d+\.\d+|\[::1\])$/.test(url.hostname))) + if (!allowed(url)) throw new ServerError("TOOLSTILE_SERVER_DOWNLOAD_URL must use https://"); return url.href.replace(/\/$/, ""); } @@ -78,7 +78,14 @@ function runner(ctx: ServerContext) { // signal on once: the server treats a second SIGINT as "stop without draining". const child = spawn(file, args, { stdio: "inherit", detached: true }); const signals = ["SIGINT", "SIGTERM", "SIGHUP"] as const; - const forward = (signal: NodeJS.Signals) => child.kill(signal); + // npx also passes Ctrl-C on to this process, so one keypress can arrive twice; + // a deliberate second Ctrl-C a moment later still forces the stop. + let last = 0; + const forward = (signal: NodeJS.Signals) => { + if (Date.now() - last < 1000) return; + last = Date.now(); + child.kill(signal); + }; for (const signal of signals) process.on(signal, forward); child.once("error", fail); child.once("exit", (code, signal) => { @@ -100,17 +107,35 @@ function capture(file: string, args: string[]): Promise { }); } +/** HTTPS, or HTTP to a loopback host for a local test release. */ +function allowed(url: URL) { + return url.protocol === "https:" || (url.protocol === "http:" && /^(localhost|127\.\d+\.\d+\.\d+|\[::1\])$/.test(url.hostname)); +} + async function get(ctx: ServerContext, url: string): Promise { - let response: Response; - try { - response = await ctx.fetch(url, { redirect: "follow" }); - } catch (error) { - throw new ServerError(`Could not download ${url}: ${(error as Error).message}`); + // Follow redirects here, so every hop (GitHub sends release files to its storage host) + // meets the same transport rule as the first. + let current = new URL(url); + for (let hop = 0; hop < 6; hop++) { + if (!allowed(current)) throw new ServerError(`Refusing to download from ${current.origin}: it is not HTTPS`); + let response: Response; + try { + response = await ctx.fetch(current.href, { redirect: "manual" }); + } catch (error) { + throw new ServerError(`Could not download ${url}: ${(error as Error).message}`); + } + const location = response.headers.get("location"); + if (response.status >= 300 && response.status < 400 && location) { + await response.body?.cancel(); + current = new URL(location, current); + continue; + } + if (response.status === 404) + throw new ServerError(`${url} was not found. Check the release name, or that this release has a build for your platform.`); + if (!response.ok || !response.body) throw new ServerError(`Downloading ${url} failed (HTTP ${response.status})`); + return response; } - if (response.status === 404) - throw new ServerError(`${url} was not found. Check the release name, or that this release has a build for your platform.`); - if (!response.ok || !response.body) throw new ServerError(`Downloading ${url} failed (HTTP ${response.status})`); - return response; + throw new ServerError(`Downloading ${url} redirected too many times`); } /** Counts bytes through the stream and redraws a progress line on a terminal. */ @@ -120,11 +145,12 @@ function progress(ctx: ServerContext, total: number) { return new Transform({ transform(chunk: Buffer, _encoding, next) { seen += chunk.length; - const percent = total ? Math.floor((seen / total) * 100) : -1; - if (ctx.stderr.isTTY && percent !== shown) { - shown = percent; + // Redraw each percent, or each megabyte when the size is unknown. + const step = total ? Math.floor((seen / total) * 100) : Math.floor(seen / 1048576); + if (ctx.stderr.isTTY && step !== shown) { + shown = step; const mb = (seen / 1048576).toFixed(1); - ctx.stderr.write(`\r ${total ? `${percent}% ` : ""}${mb} MB`); + ctx.stderr.write(`\r ${total ? `${step}% ` : ""}${mb} MB`); } next(null, chunk); }, @@ -239,7 +265,9 @@ export function split(args: string[], names: string[]) { */ export async function start(ctx: ServerContext, args: string[]): Promise { const { own, rest: other } = split(args, ["--email", "--data-dir"]); - const { forward: initArgs, rest } = split(other, INIT_OPTIONS); + const { own: init, forward: initArgs, rest } = split(other, INIT_OPTIONS); + // The server's own default origin names port 4310 whatever port it listens on. + if (init["--port"] && !init["--origin"]) initArgs.push("--origin", `http://127.0.0.1:${init["--port"]}`); const run = runner(ctx); const executable = executablePath(ctx); if (!existsSync(executable)) await install(ctx); @@ -274,17 +302,22 @@ function instanceOrigin(directory: string): string | undefined { /** Install a newer executable after backing up a stopped instance. */ export async function upgrade(ctx: ServerContext, args: string[]): Promise { - const { own, rest } = split(args, ["--release", "--from"]); + const { own, rest } = split(args, ["--release", "--from", "--data-dir"]); + if (rest.length) throw new ServerError(`Unknown option: ${rest[0]}`); + const directory = dataDir(ctx, own["--data-dir"] ? ["--data-dir", own["--data-dir"]] : []); + const pid = running(directory); + if (pid) throw new ServerError(`Stop the server first (process ${pid}), then upgrade.`); const executable = executablePath(ctx); + const initialized = existsSync(join(directory, "instance.json")); if (!existsSync(executable)) { + // Without the executable that wrote the instance there is nothing to back it up with. + if (initialized) + throw new ServerError(`toolstile-server is not installed here, so ${directory} cannot be backed up first. Back it up with the executable that runs it, then use: npx toolstile server install`); await install(ctx, { release: own["--release"], from: own["--from"] }); return 0; } - const directory = dataDir(ctx, rest); - const pid = running(directory); - if (pid) throw new ServerError(`Stop the server first (process ${pid}), then upgrade.`); const current = await capture(executable, ["version"]).catch(() => "unknown"); - if (existsSync(join(directory, "instance.json"))) { + if (initialized) { const backup = join(serverHome(ctx), "backups", `${new Date().toISOString().replace(/[:.]/g, "-")}-${current.replace(/[^\w.-]/g, "_")}`); mkdirSync(join(serverHome(ctx), "backups"), { recursive: true, mode: 0o700 }); if ((await runner(ctx)(executable, ["backup", backup, "--data-dir", directory])) !== 0) diff --git a/test/server.test.ts b/test/server.test.ts index 58dc26e..d30bda2 100644 --- a/test/server.test.ts +++ b/test/server.test.ts @@ -104,6 +104,19 @@ describe.skipIf(process.platform === "win32")("toolstile server", () => { expect(readdirSync(serverHome(ctx))).toEqual([]); }); + it("follows redirects only to HTTPS", async () => { + const files = release("1.0.0"); + const fetchVia = (target: string) => + (async (url: string) => { + if (url.startsWith("https://releases.test/")) + return new Response(null, { status: 302, headers: { location: `${target}/${url.split("/").at(-1)}` } }); + const file = files[url.split("/").at(-1) as keyof typeof files]; + return new Response(typeof file === "string" ? file : new Uint8Array(file)); + }) as typeof fetch; + expect(await install(context({}, { fetch: fetchVia("https://storage.test") }).ctx)).toBe("1.0.0"); + await expect(install(context({}, { fetch: fetchVia("http://storage.test") }).ctx)).rejects.toThrow(/not HTTPS/); + }); + it("explains a missing release and an unsupported platform", async () => { await expect(install(context().ctx)).rejects.toThrow(/was not found/); await expect(install(context(release("1.0.0"), { platform: "win32" }).ctx)).rejects.toThrow(/no toolstile-server build for win32-x64/); @@ -125,7 +138,7 @@ describe.skipIf(process.platform === "win32")("toolstile server", () => { expect(code).toBe(0); const exe = executablePath(ctx); expect(calls).toEqual([ - [exe, "init", "--port", "4500", "--data-dir", data], + [exe, "init", "--port", "4500", "--origin", "http://127.0.0.1:4500", "--data-dir", data], [exe, "bootstrap", "you@example.com", "--data-dir", data], [exe, "start", "--data-dir", data], ]); @@ -152,6 +165,17 @@ describe.skipIf(process.platform === "win32")("toolstile server", () => { await expect(upgrade(ctx, ["--data-dir", data])).rejects.toThrow(/Stop the server first/); }); + it("upgrades only an instance it can back up, with the options it knows", async () => { + const { ctx } = context(release("1.0.0")); + const data = join(home, "instance"); + mkdirSync(data); + writeFileSync(join(data, "instance.json"), "{}"); + await expect(upgrade(ctx, ["--data-dir", data])).rejects.toThrow(/cannot be backed up first/); + expect(existsSync(executablePath(ctx))).toBe(false); + await install(ctx); + await expect(upgrade(ctx, ["--data-di", data])).rejects.toThrow(/Unknown option: --data-di/); + }); + it("backs up a stopped instance before upgrading", async () => { const { ctx, calls } = context(release("1.0.0")); await install(ctx); From bb530e32b7387dcf02a4262d618643f951d03a43 Mon Sep 17 00:00:00 2001 From: Akshit Kr Nagpal Date: Thu, 19 Nov 2026 20:22:14 +0530 Subject: [PATCH 3/6] Drop only repeated Ctrl-C, reject empty option values Co-Authored-By: Claude Opus 5.5 --- src/server.ts | 14 +++++++------- test/server.test.ts | 4 +++- 2 files changed, 10 insertions(+), 8 deletions(-) diff --git a/src/server.ts b/src/server.ts index 831f307..7421726 100644 --- a/src/server.ts +++ b/src/server.ts @@ -80,10 +80,12 @@ function runner(ctx: ServerContext) { const signals = ["SIGINT", "SIGTERM", "SIGHUP"] as const; // npx also passes Ctrl-C on to this process, so one keypress can arrive twice; // a deliberate second Ctrl-C a moment later still forces the stop. - let last = 0; + let interrupted = 0; const forward = (signal: NodeJS.Signals) => { - if (Date.now() - last < 1000) return; - last = Date.now(); + if (signal === "SIGINT") { + if (Date.now() - interrupted < 1000) return; + interrupted = Date.now(); + } child.kill(signal); }; for (const signal of signals) process.on(signal, forward); @@ -251,7 +253,7 @@ export function split(args: string[], names: string[]) { const name = eq === -1 ? a : a.slice(0, eq); if (names.includes(name)) { const value = eq === -1 ? args[++i] : a.slice(eq + 1); - if (value === undefined || value.startsWith("-")) throw new ServerError(`${name} needs a value`); + if (!value || value.startsWith("-")) throw new ServerError(`${name} needs a value`); own[name] = value; forward.push(name, value); } else rest.push(a); @@ -265,9 +267,7 @@ export function split(args: string[], names: string[]) { */ export async function start(ctx: ServerContext, args: string[]): Promise { const { own, rest: other } = split(args, ["--email", "--data-dir"]); - const { own: init, forward: initArgs, rest } = split(other, INIT_OPTIONS); - // The server's own default origin names port 4310 whatever port it listens on. - if (init["--port"] && !init["--origin"]) initArgs.push("--origin", `http://127.0.0.1:${init["--port"]}`); + const { forward: initArgs, rest } = split(other, INIT_OPTIONS); const run = runner(ctx); const executable = executablePath(ctx); if (!existsSync(executable)) await install(ctx); diff --git a/test/server.test.ts b/test/server.test.ts index d30bda2..95d7bfc 100644 --- a/test/server.test.ts +++ b/test/server.test.ts @@ -138,7 +138,7 @@ describe.skipIf(process.platform === "win32")("toolstile server", () => { expect(code).toBe(0); const exe = executablePath(ctx); expect(calls).toEqual([ - [exe, "init", "--port", "4500", "--origin", "http://127.0.0.1:4500", "--data-dir", data], + [exe, "init", "--port", "4500", "--data-dir", data], [exe, "bootstrap", "you@example.com", "--data-dir", data], [exe, "start", "--data-dir", data], ]); @@ -174,6 +174,8 @@ describe.skipIf(process.platform === "win32")("toolstile server", () => { expect(existsSync(executablePath(ctx))).toBe(false); await install(ctx); await expect(upgrade(ctx, ["--data-di", data])).rejects.toThrow(/Unknown option: --data-di/); + await expect(upgrade(ctx, ["--data-dir="])).rejects.toThrow(/--data-dir needs a value/); + await expect(upgrade(ctx, ["--from="])).rejects.toThrow(/--from needs a value/); }); it("backs up a stopped instance before upgrading", async () => { From b94e2e6e414d7e87a2e560ce64f5373b775d8a82 Mon Sep 17 00:00:00 2001 From: Akshit Kr Nagpal Date: Sun, 22 Nov 2026 11:15:57 +0530 Subject: [PATCH 4/6] Let the server's setup link create the first account A new loopback instance prints a one-time setup link when it starts, so server start no longer asks for an email. --email still creates an invitation, and other new instances are pointed at bootstrap. Co-Authored-By: Claude Opus 5.5 --- README.md | 11 ++++++----- src/server.ts | 37 +++++++++++++++++++++---------------- test/server.test.ts | 41 +++++++++++++++++++++++++++++++++++++++++ 3 files changed, 68 insertions(+), 21 deletions(-) diff --git a/README.md b/README.md index c2180f0..78a21b8 100644 --- a/README.md +++ b/README.md @@ -290,10 +290,11 @@ checks it against its published SHA-256 checksum and starts it: npx toolstile server start ``` -On a new instance it asks for your email and prints an invitation link, then -runs the server at `http://127.0.0.1:4310` until you press Ctrl-C. Open the -link, create your account and follow the guided setup. Connect Claude Code to -your own server with: +On a new instance it runs the server at `http://127.0.0.1:4310` until you press +Ctrl-C and prints a one-time setup link (it works once and expires after 15 +minutes; each start prints a new one until an account exists). Open it, create +your account and follow the guided setup. Connect Claude Code to your own +server with: ```sh claude mcp add --transport http toolstile http://127.0.0.1:4310/mcp @@ -301,7 +302,7 @@ claude mcp add --transport http toolstile http://127.0.0.1:4310/mcp | Command | What it does | | --- | --- | -| `server start [--email ]` | Installs on first use, initializes and invites on a new instance, then runs the server | +| `server start [--email ]` | Installs on first use and initializes a new instance, then runs the server. `--email` prints an invitation link for that address instead, for instances other people reach over the network | | `server install [--release ] [--from ]` | Installs the latest release, a named one or a file you built | | `server upgrade` | Refuses while the server runs; backs up the instance, then installs the latest release and keeps the previous executable | | `server uninstall` | Removes the executable; your data and backups stay | diff --git a/src/server.ts b/src/server.ts index 7421726..e054c35 100644 --- a/src/server.ts +++ b/src/server.ts @@ -3,7 +3,6 @@ import { createHash } from "node:crypto"; import { createReadStream, createWriteStream, existsSync, mkdirSync, readFileSync, renameSync, rmSync } from "node:fs"; import { homedir } from "node:os"; import { join, resolve } from "node:path"; -import { createInterface } from "node:readline"; import { Readable, Transform } from "node:stream"; import { pipeline } from "node:stream/promises"; import { createBrotliDecompress } from "node:zlib"; @@ -230,15 +229,6 @@ export function running(directory: string): number | undefined { } } -async function ask(ctx: ServerContext, question: string): Promise { - const lines = createInterface({ input: ctx.stdin, output: ctx.stderr }); - try { - return await new Promise((done) => lines.question(question, (answer) => done(answer.trim()))); - } finally { - lines.close(); - } -} - /** Options only `init` reads; `start` passes them on when it creates the instance. */ const INIT_OPTIONS = ["--origin", "--listen", "--port"]; @@ -275,22 +265,37 @@ export async function start(ctx: ServerContext, args: string[]): Promise const pid = running(directory); if (pid) throw new ServerError(`The instance in ${directory} is already running (process ${pid})`); const data = ["--data-dir", directory]; - let email = own["--email"]; - if (!existsSync(join(directory, "instance.json"))) { + const email = own["--email"]; + const fresh = !existsSync(join(directory, "instance.json")); + if (fresh) { if ((await run(executable, ["init", ...initArgs, ...data])) !== 0) return 1; - if (!email && ctx.stdin.isTTY) email = await ask(ctx, "Email for your account (enter to skip): "); - if (!email) say(ctx, "Invite an account later with: npx toolstile server bootstrap you@example.com"); } else if (initArgs.length) throw new ServerError(`${directory} is already initialized; --origin, --listen and --port apply only to a new instance.`); + const origin = instanceOrigin(directory); if (email) { if ((await run(executable, ["bootstrap", email, ...data])) !== 0) return 1; say(ctx, ctx.style.dim("Open the invitation link once the server is listening, then create your account.")); + } else if (fresh && !(origin && isLoopbackOrigin(origin))) { + // A loopback instance prints its own one-time setup link when it starts with no accounts. + say(ctx, "Invite the first account with: npx toolstile server bootstrap you@example.com"); } - const origin = instanceOrigin(directory); - if (origin) say(ctx, `Connect Claude Code: claude mcp add --transport http toolstile ${origin}/mcp`); + // On a new loopback instance the server prints this line with its setup link. + if (origin && !(fresh && isLoopbackOrigin(origin))) + say(ctx, `Connect Claude Code: claude mcp add --transport http toolstile ${origin}/mcp`); return run(executable, ["start", ...rest, ...data]); } +/** True for `http://` origins on 127.0.0.0/8, `localhost` or `[::1]`. */ +export function isLoopbackOrigin(origin: string): boolean { + try { + const url = new URL(origin); + const host = url.hostname; + return url.protocol === "http:" && (host === "localhost" || host === "[::1]" || /^127(\.\d{1,3}){3}$/.test(host)); + } catch { + return false; + } +} + function instanceOrigin(directory: string): string | undefined { try { const origin = JSON.parse(readFileSync(join(directory, "instance.json"), "utf8")).origin; diff --git a/test/server.test.ts b/test/server.test.ts index 95d7bfc..a5c691f 100644 --- a/test/server.test.ts +++ b/test/server.test.ts @@ -11,6 +11,7 @@ import { downloadBase, executablePath, install, + isLoopbackOrigin, type ServerContext, ServerError, serverHome, @@ -144,6 +145,46 @@ describe.skipIf(process.platform === "win32")("toolstile server", () => { ]); }); + it("leaves the first account to the server's setup link on a new loopback instance", async () => { + const { ctx, calls, stderr } = context(release("1.0.0")); + const data = join(home, "instance"); + const run = ctx.run; + ctx.run = async (file, args) => { + if (args[0] === "init") { + mkdirSync(data, { recursive: true }); + writeFileSync(join(data, "instance.json"), JSON.stringify({ origin: "http://127.0.0.1:4310" })); + } + return run!(file, args); + }; + expect(await start(ctx, ["--data-dir", data])).toBe(0); + expect(calls.map((c) => c[1])).toEqual(["init", "start"]); + expect(stderr()).not.toMatch(/bootstrap|Connect Claude Code/); + }); + + it("points a new non-loopback instance at bootstrap", async () => { + const { ctx, stderr } = context(release("1.0.0")); + const data = join(home, "instance"); + const run = ctx.run; + ctx.run = async (file, args) => { + if (args[0] === "init") { + mkdirSync(data, { recursive: true }); + writeFileSync(join(data, "instance.json"), JSON.stringify({ origin: "https://tools.example.com" })); + } + return run!(file, args); + }; + expect(await start(ctx, ["--data-dir", data])).toBe(0); + expect(stderr()).toMatch(/server bootstrap you@example.com/); + expect(stderr()).toMatch(/Connect Claude Code: .*https:\/\/tools.example.com\/mcp/); + }); + + it("recognizes loopback origins", () => { + expect(isLoopbackOrigin("http://127.0.0.1:4310")).toBe(true); + expect(isLoopbackOrigin("http://localhost:4310")).toBe(true); + expect(isLoopbackOrigin("http://[::1]:4310")).toBe(true); + expect(isLoopbackOrigin("https://127.0.0.1:4310")).toBe(false); + expect(isLoopbackOrigin("http://192.168.1.2:4310")).toBe(false); + }); + it("starts an existing instance without initializing it again", async () => { const { ctx, calls } = context(release("1.0.0")); const data = join(home, "instance"); From e9afa786c8133ec4271ff7ff7489488476bf7e49 Mon Sep 17 00:00:00 2001 From: Akshit Kr Nagpal Date: Sun, 22 Nov 2026 11:26:16 +0530 Subject: [PATCH 5/6] Point a new non-loopback instance at start --email and drop unused stdin bootstrap needs the database the running server holds, so the hint now asks to restart with --email (keeping --data-dir). The help text describes the setup link, and the server context no longer carries stdin. Co-Authored-By: Claude Opus 5.5 --- src/cli.ts | 11 ++++++----- src/server.ts | 14 ++++++++------ test/server.test.ts | 3 +-- 3 files changed, 15 insertions(+), 13 deletions(-) diff --git a/src/cli.ts b/src/cli.ts index e58dafc..3991336 100644 --- a/src/cli.ts +++ b/src/cli.ts @@ -148,9 +148,11 @@ Usage npx toolstile server ... start downloads toolstile-server, a single executable with its own database, -on first use. On a new instance it asks for your email and prints an -invitation link, then runs the server until you press Ctrl-C. Open the link, -create your account and follow the guided setup. +on first use, then runs the server until you press Ctrl-C. A new instance on +this machine (the default http://127.0.0.1:4310) prints a one-time setup link: +open it, create your account and follow the guided setup. For a new instance +with another address, or to invite a specific account, pass --email: start +then prints an invitation link for it. upgrade refuses while the server is running, backs up the instance first and keeps the executable it replaces. uninstall keeps your data. Other commands @@ -158,7 +160,7 @@ run toolstile-server directly; see its local operation guide: https://github.com/toolstile/toolstile/blob/main/docs/local-operation.md Options for start - --email
Invite this account without asking + --email
Print an invitation link for this account before starting --data-dir Instance folder (default ~/.local/share/toolstile, or TOOLSTILE_DATA_DIR) --origin New instance only: its address (default http://127.0.0.1:4310) --listen
New instance only: interface to listen on (default 127.0.0.1) @@ -377,7 +379,6 @@ async function server(argv: string[]): Promise { platform: process.platform, arch: process.arch, fetch: (...args) => fetch(...args), - stdin: process.stdin, stdout: process.stdout, stderr: process.stderr, style: style(process.stderr.isTTY === true && !process.env.NO_COLOR), diff --git a/src/server.ts b/src/server.ts index e054c35..8dd9174 100644 --- a/src/server.ts +++ b/src/server.ts @@ -7,6 +7,7 @@ import { Readable, Transform } from "node:stream"; import { pipeline } from "node:stream/promises"; import { createBrotliDecompress } from "node:zlib"; import type { Style } from "./report.js"; +import { isLoopback } from "./servers.js"; /** Where release executables are published; `TOOLSTILE_SERVER_DOWNLOAD_URL` replaces it. */ export const RELEASES = "https://github.com/toolstile/toolstile/releases"; @@ -20,7 +21,6 @@ export interface ServerContext { platform: NodeJS.Platform; arch: string; fetch: typeof fetch; - stdin: NodeJS.ReadableStream & { isTTY?: boolean }; stdout: NodeJS.WritableStream & { isTTY?: boolean }; stderr: NodeJS.WritableStream & { isTTY?: boolean }; style: Style; @@ -272,15 +272,18 @@ export async function start(ctx: ServerContext, args: string[]): Promise } else if (initArgs.length) throw new ServerError(`${directory} is already initialized; --origin, --listen and --port apply only to a new instance.`); const origin = instanceOrigin(directory); + const loopback = origin !== undefined && isLoopbackOrigin(origin); if (email) { if ((await run(executable, ["bootstrap", email, ...data])) !== 0) return 1; say(ctx, ctx.style.dim("Open the invitation link once the server is listening, then create your account.")); - } else if (fresh && !(origin && isLoopbackOrigin(origin))) { + } else if (fresh && !loopback) { // A loopback instance prints its own one-time setup link when it starts with no accounts. - say(ctx, "Invite the first account with: npx toolstile server bootstrap you@example.com"); + // bootstrap needs the database the running server holds, so it has to run before start. + const dir = own["--data-dir"] ? ` --data-dir ${own["--data-dir"]}` : ""; + say(ctx, `No account exists yet. Stop the server (Ctrl-C), then run: npx toolstile server start --email you@example.com${dir}`); } // On a new loopback instance the server prints this line with its setup link. - if (origin && !(fresh && isLoopbackOrigin(origin))) + if (origin && !(fresh && loopback)) say(ctx, `Connect Claude Code: claude mcp add --transport http toolstile ${origin}/mcp`); return run(executable, ["start", ...rest, ...data]); } @@ -289,8 +292,7 @@ export async function start(ctx: ServerContext, args: string[]): Promise export function isLoopbackOrigin(origin: string): boolean { try { const url = new URL(origin); - const host = url.hostname; - return url.protocol === "http:" && (host === "localhost" || host === "[::1]" || /^127(\.\d{1,3}){3}$/.test(host)); + return url.protocol === "http:" && isLoopback(url.hostname); } catch { return false; } diff --git a/test/server.test.ts b/test/server.test.ts index a5c691f..ef4d5fa 100644 --- a/test/server.test.ts +++ b/test/server.test.ts @@ -46,7 +46,6 @@ function context(files: Record = {}, overrides: Partial const file = files[url.replace("https://releases.test/v1/", "")]; return file === undefined ? new Response("missing", { status: 404 }) : new Response(typeof file === "string" ? file : new Uint8Array(file)); }) as typeof fetch, - stdin: new PassThrough(), stdout: new PassThrough(), stderr, style: style(false), @@ -173,7 +172,7 @@ describe.skipIf(process.platform === "win32")("toolstile server", () => { return run!(file, args); }; expect(await start(ctx, ["--data-dir", data])).toBe(0); - expect(stderr()).toMatch(/server bootstrap you@example.com/); + expect(stderr()).toMatch(/server start --email you@example.com/); expect(stderr()).toMatch(/Connect Claude Code: .*https:\/\/tools.example.com\/mcp/); }); From de674fca6fb52151b71e569eda14417c4df8ed26 Mon Sep 17 00:00:00 2001 From: Akshit Kr Nagpal Date: Sun, 22 Nov 2026 11:27:38 +0530 Subject: [PATCH 6/6] Quote the data folder in the --email hint and name loopback origins in help Co-Authored-By: Claude Opus 5.5 --- src/cli.ts | 9 +++++---- src/server.ts | 6 +++++- test/server.test.ts | 13 ++++++++++--- 3 files changed, 20 insertions(+), 8 deletions(-) diff --git a/src/cli.ts b/src/cli.ts index 3991336..393437d 100644 --- a/src/cli.ts +++ b/src/cli.ts @@ -149,10 +149,11 @@ Usage start downloads toolstile-server, a single executable with its own database, on first use, then runs the server until you press Ctrl-C. A new instance on -this machine (the default http://127.0.0.1:4310) prints a one-time setup link: -open it, create your account and follow the guided setup. For a new instance -with another address, or to invite a specific account, pass --email: start -then prints an invitation link for it. +this machine (an http:// origin on localhost, 127.0.0.0/8 or [::1]; the +default is http://127.0.0.1:4310) prints a one-time setup link: open it, +create your account and follow the guided setup. For a new instance with any +other origin, or to invite a specific account, pass --email: start then +prints an invitation link for it. upgrade refuses while the server is running, backs up the instance first and keeps the executable it replaces. uninstall keeps your data. Other commands diff --git a/src/server.ts b/src/server.ts index 8dd9174..dda0748 100644 --- a/src/server.ts +++ b/src/server.ts @@ -279,7 +279,7 @@ export async function start(ctx: ServerContext, args: string[]): Promise } else if (fresh && !loopback) { // A loopback instance prints its own one-time setup link when it starts with no accounts. // bootstrap needs the database the running server holds, so it has to run before start. - const dir = own["--data-dir"] ? ` --data-dir ${own["--data-dir"]}` : ""; + const dir = own["--data-dir"] ? ` --data-dir ${shellQuote(directory)}` : ""; say(ctx, `No account exists yet. Stop the server (Ctrl-C), then run: npx toolstile server start --email you@example.com${dir}`); } // On a new loopback instance the server prints this line with its setup link. @@ -288,6 +288,10 @@ export async function start(ctx: ServerContext, args: string[]): Promise return run(executable, ["start", ...rest, ...data]); } +/** Quotes a path for a POSIX shell (the server runs on macOS and Linux only). */ +export const shellQuote = (value: string) => + /^[\w./~-]+$/.test(value) ? value : `'${value.replaceAll("'", "'\\''")}'`; + /** True for `http://` origins on 127.0.0.0/8, `localhost` or `[::1]`. */ export function isLoopbackOrigin(origin: string): boolean { try { diff --git a/test/server.test.ts b/test/server.test.ts index ef4d5fa..4fc303e 100644 --- a/test/server.test.ts +++ b/test/server.test.ts @@ -12,6 +12,7 @@ import { executablePath, install, isLoopbackOrigin, + shellQuote, type ServerContext, ServerError, serverHome, @@ -160,9 +161,9 @@ describe.skipIf(process.platform === "win32")("toolstile server", () => { expect(stderr()).not.toMatch(/bootstrap|Connect Claude Code/); }); - it("points a new non-loopback instance at bootstrap", async () => { + it("points a new non-loopback instance at start --email with a quoted folder", async () => { const { ctx, stderr } = context(release("1.0.0")); - const data = join(home, "instance"); + const data = join(home, "Toolstile Data"); const run = ctx.run; ctx.run = async (file, args) => { if (args[0] === "init") { @@ -172,10 +173,16 @@ describe.skipIf(process.platform === "win32")("toolstile server", () => { return run!(file, args); }; expect(await start(ctx, ["--data-dir", data])).toBe(0); - expect(stderr()).toMatch(/server start --email you@example.com/); + expect(stderr()).toContain(`npx toolstile server start --email you@example.com --data-dir '${data}'`); expect(stderr()).toMatch(/Connect Claude Code: .*https:\/\/tools.example.com\/mcp/); }); + it("quotes paths for the shell", () => { + expect(shellQuote("/tmp/toolstile-data")).toBe("/tmp/toolstile-data"); + expect(shellQuote("/tmp/Toolstile Data")).toBe("'/tmp/Toolstile Data'"); + expect(shellQuote("/tmp/it's")).toBe("'/tmp/it'\\''s'"); + }); + it("recognizes loopback origins", () => { expect(isLoopbackOrigin("http://127.0.0.1:4310")).toBe(true); expect(isLoopbackOrigin("http://localhost:4310")).toBe(true);