commentware.config.json

commentware.config.json names the server that every commentware command run in its directory, or below it, addresses. Learn more about how a command finds its server.

A file that keeps a directory’s comments under .tmp/, on its own port and name:

{
  "db": "./.tmp/comments/data.db",
  "port": 7100,
  "name": "Design review"
}

Every key is optional. A key that is left out takes its default, and so does every key but $schema when it is set to null. To write one, see Give a directory its own server.

Which file a command uses

A command reads one file, the first of these that answers, and takes every value from it:

1. The file --config names. A path that does not exist is refused.
2. The nearest commentware.config.json in the directory the command runs in, or in any directory above it.
3. Your own config file, below.
4. No file: every key takes its default.

The files are never merged. On start, --port, --host, --name and --public-origin win over the file.

commentware where prints the file in force, the database, the blobs directory, the port, the host and the name, without opening or creating anything. It adds the publicOrigin the file sets, as reached, and the version its $schema line names, as schema.

Your own config file

It takes the same keys as commentware.config.json, and commentware init -g writes it. A broken one is refused, not skipped.

Keys

One entry per key, in the order the schema declares them.

$schema

Type: a URL · Default: none

The JSON Schema this file is written against. Ignored by the server.

commentware init writes it, pointing at https://commentware.com/schema/v1/commentware.config.schema.json. An editor that reads it completes key names, checks types and shows what each key means. The document there is generated from the declaration the server validates against.

The v1 in the URL is the version of the format. It moves only when the format stops accepting a file it used to accept: a key removed, or a type narrowed. A key added, a type widened or a description reworded does not move it. Every version the site still publishes stays at its own URL.

When the line names an older version than the CLI enforces, commentware where says so. Point the line at the newer URL to clear it.

db

Type: a path · Default: this machine’s own database, in Where the data goes

Path to the sqlite file. Relative paths resolve against this file's own directory.

commentware init in a directory writes ./.tmp/comments/data.db. Only commentware start creates a database; every other command refuses a path with none.

blobs

Type: a path · Default: a blobs directory beside the database

Directory for screenshots and attachments. Follows the database when absent.

A relative path resolves against the file’s own directory, as for db.

port

Type: an integer from 1 to 65535, or a ${VAR} reference · Default: 7042 · Flag: --port on start and init

Port the server binds, and the port a printed URL names.

A string is accepted only where a ${VAR} reference produced it, so "port": "7100" written by hand is refused.

host

Type: an interface address or a hostname · Default: 127.0.0.1 · Flag: --host on start

Interface the server binds. Anything but loopback is reachable from off this machine.

Binding anything but loopback prints a warning, because the server speaks plain HTTP. See Choose the port and the interface.

name

Type: a string of 1 to 80 characters · Default: Commentware · Flag: --name on start and init

How this server introduces itself. At most 80 characters — every client displays a longer name cut to this length, so a longer one here would be silently trimmed everywhere it is shown.

publicOrigin

Type: an origin · Default: none, and addresses name what the server binds · Flag: --public-origin on start

The address clients reach this server at, when a proxy stands in front of it. Scheme, host and optional port — no path, no query, no fragment. Links, permalinks and the OAuth issuer are built from it; the server still binds host and port.

Everything the server hands out is built from it: the connection string, the MCP and discovery URLs, every permalink an agent is given, and the OAuth issuer. Without it, each of those names the address the server binds.

A proxy on the same machine as the server, which reaches it on loopback:

{ "host": "127.0.0.1", "port": 7042, "publicOrigin": "https://comments.example.com" }

A proxy on another machine needs the server bound to an interface that machine can reach, with --host on every start. See On a machine you reach over the network.

• The value is an origin and nothing more: a scheme, a host, and a port when it is not the default one. A path, a query, a fragment or a trailing slash is refused, by the server and by an editor reading $schema.
• A running server keeps the address it started with, and so does every connection string minted while it runs. Restart the server after setting or changing it.
• An https:// origin makes the server an OAuth authorization server, so an agent can sign in through a browser. An http:// origin with a real hostname does not, because an access token would cross the network in clear text, and the server keeps accepting the access key.
• A client authorized against the old address signs in again, because a token is bound to the address it was issued at.
• The server answers only to addresses it knows. A request whose Host header names any other is refused with a 403, starting with the extension’s first call. It knows the host of publicOrigin, the name passed to --host, localhost and any name under it, and any IP address written as a literal. An mDNS .local name, a container or Service name, a tailnet name or a hostname from a LAN /etc/hosts is refused until it is in publicOrigin or bound with --host. The refusal names the address it received and the addresses it answers to.

Which way to let somebody else reach a server, and when a proxy is the one, is in Reach it from another browser.

Values from the environment

Any value may contain ${VAR}, replaced with that environment variable when the file is read. A file that is committed can then carry a value that differs per machine:

{
  "db": "./.tmp/comments/data.db",
  "port": "${DEV_PORT}"
}

• An unset or empty variable is refused, never substituted. The refusal names the file, the key and the variable.
• A malformed reference is refused. ${not a name} is not read as text.
• $${ is a literal ${. A lone $ is itself, so a path needs no escaping.
• Only a variable the file names is read. Nothing else in the environment changes what the file says.

What a file may not hold

• A setting. hub-origin, screenshots, resolved-purge-days and bundle-idle-days are stored in the database and changed with commentware settings set. One written here is refused by name, with the command that changes it. See Settings.
• An access key. There is no field for one. See Manage users and access keys.
• Any other key. An unknown key is refused, and the refusal lists the keys that work.

Every refusal names the file it read. See Troubleshooting.