Install a server — Commentware

A server on this computer or on another machine from the installer, and the connection between it and the extension.

Install the Chrome extension and a server on this computer with one command, connect the two, and leave your first comment. At the end, Commentware is running in Chrome against a server you run yourself.

If somebody else runs your server, you need none of this: Connect to a server is the step that is yours. Members get only the steps for their own setup from the setup page.

Prerequisites

Chrome.
An invite code. Select Request access on the homepage to ask for one. A browser that holds a code shows it on /lounge/account/, under “Your invite code”.

1. Run a server

The server can run on the same computer as your browser, or on a machine you reach over the network — a box on your desk, a VM, or one the team shares. This step is the first; the second is for a server on another machine.

On this computer

The usual one, and the one to take if you are not sure. One command installs the extension and the server.

Run the command for your system:
macOS and Linux
```
curl -fsSL https://commentware.com/install/extension-and-server.sh | sh
```
It lands in ~/Commentware/bin, which it adds to your PATH. Open a new terminal afterwards. Run this command again to update the extension and the server.
Windows
```
iwr -useb https://commentware.com/install/extension-and-server.ps1 | iex
```
PowerShell 5.1, which is what Windows ships. It lands in %USERPROFILE%\Commentware\bin, which it adds to your Path. Open a new terminal afterwards.
When the installer prints Commentware is invite-only for now. Enter your invite code:, type your code and press Enter. Run the installer has the details.
If the installer prints that no Node.js was found, or that the one it found is too old for the server, answer its question. Press Enter to download Node.js from nodejs.org into ~/Commentware/node, where only Commentware uses it. Answer n to stop: the extension stays installed and the server is not, and the setup page still opens, so load the extension from it. To go on, install Node.js 24 or later, then run the command again.
Copy the connection string the installer prints once the server is running. Keys are stored hashed, so this is the only moment it is legible, and connecting the extension in step 2 may need it. If it prints none because a server database already existed on this machine, mint one for admin:
```
commentware users generate 1
```
If an AI agent’s MCP client is on this computer and not yet connected, the installer lists the ones it found under the connection string and asks whether to connect them. It asks on a first install only. Press Enter to give each a user and a key of its own, written into its own config, or type n to skip. Connect the clients on the server’s machine does the same later.
Follow the page the installer opens in Chrome to load the extension. It opens after the installer has finished with the server. If the page has a Connect to the server section at its end, leave that for step 2 below.
Open a new terminal, so that commentware is on its PATH. The installer added ~/Commentware/bin to your shell’s startup files (the user Path on Windows), and a terminal that was already open has not read them.

The installer starts the server on 7042 at 127.0.0.1, which is reachable from this machine and nowhere else, and it runs in the background until you stop it. It takes the defaults at the questions a first start asks. Those settings live in this machine’s own config file, and commentware.config.json lists every key it may hold.

Use one install per machine: a first install by the installer stops when a commentware from a package manager is already on PATH, and afterwards its own comes first. Learn more about how the install works. Learn more about what the first start does. If the connection string scrolled away, see the connection string scrolled away.

On a machine you reach over the network

On that machine, run the command for its system. It installs the server alone, with no extension:
macOS and Linux
```
curl -fsSL https://commentware.com/install/server.sh | sh
```
It lands in ~/Commentware/bin, which it adds to your PATH. Open a new terminal afterwards. Run this command again to update the server.
Windows
```
iwr -useb https://commentware.com/install/server.ps1 | iex
```
PowerShell 5.1, which is what Windows ships. It lands in %USERPROFILE%\Commentware\bin, which it adds to your Path. Open a new terminal afterwards.
When the installer asks for your invite code, type it and press Enter.
If the installer prints that no Node.js was found, or that the one it found is too old, answer its question as in step 3 above.
Open a new terminal on that machine, or reconnect over ssh, so that commentware is on its PATH.

Then decide how your browser reaches the server — two ways, and the first is usually right:

Forward a port, over SSH or whatever tunnel you already use. The server stays on 127.0.0.1 and nothing is exposed. Mint the connection string with the port you reach it on rather than the one it bound: commentware users new alex --port 8443.
Bind an interface and put a reverse proxy with TLS in front of it. The installer started the server on 127.0.0.1, so stop it with commentware stop, then start it again with commentware start --host 0.0.0.0, which binds wider and warns while it does: this server speaks plaintext, so without TLS in front of it everything it accepts crosses the network in the clear. --host is a decision per run rather than a setting, so it is never written to the config file and every start needs it. That is for a proxy on another machine. A proxy on the server’s own machine reaches it on loopback, so the server keeps 127.0.0.1 and needs no --host. Either way, tell the server the address you reach it at, once — publicOrigin in commentware.config.json, or --public-origin on start. Until you do, a server reached at a name it was never told answers 403 to the extension’s first call. See the publicOrigin key.

The same binary is meant to run both ways. Manage a server has the rest of it — where the data goes, the config file a command uses, and one server per database.

2. Connect the two

This step needs the Chrome extension loaded into Chrome, which step 1 on this computer did. If the server is on another machine, see Install the Chrome extension.

On the setup page, under Connect to the server, select Connect to this server. If the page has no such section, open the connection string in Chrome. Either way it lands on /ext/auth/ on this site, in a tab of its own.
Select Connect in the small window the extension opens. Nothing connects without that press, and the /ext/auth/ tab closes itself.

If no window appears, see opening a connection string does nothing. To hold more than one server, see hold several servers.

Your first comment

Press Alt+C — ⌥C on a Mac — on any page. The comment overlay opens over it.
Press the toolbar’s first button to arm a crosshair, then click the thing you want to talk about.
Type, and press Enter to send. The page is photographed as you see it the moment you place the pin.

That is the whole product. Comment on a page covers replying, mentioning somebody, attaching a file and resolving a thread.

Check that it worked

Your first comment’s pin is on the page where you placed it, and it is still there after you reload the page.

What you did

Installed the extension and a server you run yourself, and connected the extension to it with a connection string.
Left a comment pinned to an element on a page.

Next steps

Comment on a page: reply, mention somebody, attach a file and resolve a thread.
Manage a server: where the data goes, and reaching it from another machine.
Work with an AI agent: point an agent at the same threads.