---
title: "commentware.config.json"
description: "Every key the config file may hold, which file a command reads, and what a value may take from the environment."
---

> Documentation Index
> Fetch the complete documentation index at: https://commentware.com/llms.txt
> Use this file to discover all available pages before exploring further.

# 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](/docs/concepts/config-file/).

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

```json title="commentware.config.json"
{
  "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](/docs/server/#the-config-file-a-command-uses).

## 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

| Your system | Where it is                                                                        |
| ----------- | ---------------------------------------------------------------------------------- |
| Linux       | `$XDG_CONFIG_HOME/commentware/config.json`, or `~/.config/commentware/config.json` |
| macOS       | `~/Library/Application Support/Commentware/config.json`                            |
| Windows     | `%LOCALAPPDATA%\Commentware\config.json`                                           |

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](/docs/server/#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](/docs/server/#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:

```json title="commentware.config.json"
{ "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](/docs/install-server/#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](/docs/server/#reaching-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:

```json title="commentware.config.json"
{
  "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](/docs/server/settings/).
- **An access key.** There is no field for one. See [Manage users and access
  keys](/docs/server/users/).
- **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](/docs/troubleshooting/).