Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
32 changes: 32 additions & 0 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -280,6 +280,38 @@ redirect.
| `--workspace <slug>` | `mcp setup` | Toolstile Cloud workspace the agents use (default: the last one, or personal) |
| `--device-name <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 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
```

| Command | What it does |
| --- | --- |
| `server start [--email <you@example.com>]` | 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 <tag>] [--from <file>]` | 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
Expand Down
79 changes: 79 additions & 0 deletions src/cli.ts
Original file line number Diff line number Diff line change
Expand Up @@ -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";
Expand All @@ -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 <url>) or the server on this machine (--local).
Expand Down Expand Up @@ -136,6 +138,40 @@ 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 <you@example.com>] [options]
npx toolstile server install [--release <tag>] [--from <file>]
npx toolstile server upgrade [--release <tag>] [--from <file>]
npx toolstile server uninstall
npx toolstile server <bootstrap|operator|backup|restore|init|version> ...

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 (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
run toolstile-server directly; see its local operation guide:
https://github.com/toolstile/toolstile/blob/main/docs/local-operation.md

Options for start
--email <address> Print an invitation link for this account before starting
--data-dir <path> Instance folder (default ~/.local/share/toolstile, or TOOLSTILE_DATA_DIR)
--origin <url> New instance only: its address (default http://127.0.0.1:4310)
--listen <address> New instance only: interface to listen on (default 127.0.0.1)
--port <port> New instance only: port (default 4310)

Options for install and upgrade
--release <tag> A specific release (default: the latest)
--from <file> 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;
Expand Down Expand Up @@ -326,10 +362,53 @@ async function command(argv: string[]): Promise<number> {
}
}

async function server(argv: string[]): Promise<number> {
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),
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<number> {
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<typeof parseArgs>;
try {
Expand Down
Loading