Configuration Reference

ChatRoom's main runtime configuration is stored at:

~/.chatroom/config.json

The file is created automatically when you run chatroom init. By default, the configuration directory has 0700 permissions and the configuration file has 0600 permissions.

If no directory is specified with --root, ChatRoom allows access to the following directory by default:

~/Projects

If the directory does not exist, chatroom init creates it automatically.

config.json contains the ownerToken. It is the owner credential for your ChatRoom instance. Do not publish it, commit it to a Git repository, or send it to anyone else.

Complete Configuration Example

After initialization, the configuration has the following structure. ownerToken is generated randomly by ChatRoom; the value below is only a placeholder:

{
  "allowedRoots": [
    "/home/user/Projects"
  ],
  "dataDir": "/home/user/.chatroom",
  "databasePath": "/home/user/.chatroom/chatroom.sqlite",
  "server": {
    "host": "127.0.0.1",
    "port": 8765
  },
  "auth": {
    "localWebAuth": false,
    "ownerToken": "<generated-owner-token>",
    "mcpPublicBaseUrl": null,
    "webPublicBaseUrl": null,
    "allowedRedirectHosts": [
      "chatgpt.com",
      "localhost",
      "127.0.0.1"
    ]
  },
  "audit": {
    "maxPayloadBytes": 524288
  },
  "process": {
    "maxOutputBytes": 524288,
    "defaultTimeoutMs": 1800000,
    "maxCompletedProcesses": 200
  },
  "agents": {
    "acp": [],
    "external": []
  }
}

ChatRoom validates the configuration strictly. Invalid field types, out-of-range ports, or unsupported fields cause startup to fail instead of being silently ignored.

allowedRoots

allowedRoots defines the project root directories that ChatRoom may open and manage. It is also one of the most important filesystem security boundaries.

Default value:

{
  "allowedRoots": ["/home/user/Projects"]
}

You can configure multiple roots:

{
  "allowedRoots": [
    "/home/user/Projects",
    "/srv/projects"
  ]
}

At startup, ChatRoom resolves these paths to absolute paths. Only projects located within an allowed root can be opened and managed as normal Workspaces.

Restart ChatRoom after changing allowedRoots.

dataDir

dataDir is ChatRoom's runtime data directory.

Default value:

~/.chatroom

For example:

{
  "dataDir": "/home/user/.chatroom"
}

Runtime data such as ChatRoom-managed Worktrees is stored under this directory. Unless you have a specific data-directory layout in mind, there is usually no need to change it.

databasePath

databasePath specifies the location of the ChatRoom SQLite database.

Default value:

~/.chatroom/chatroom.sqlite

The database stores persistent state such as Workspaces, audit records, OAuth state, Web sessions, and Agent run records.

If databasePath is omitted from the configuration, ChatRoom uses:

<dataDir>/chatroom.sqlite

You can also override it temporarily with an environment variable:

CHATROOM_DATABASE=/path/to/chatroom.sqlite chatroom serve

The environment variable takes precedence over databasePath in the configuration file.

server

server controls the address and port used by the ChatRoom HTTP server.

Default value:

{
  "server": {
    "host": "127.0.0.1",
    "port": 8765
  }
}

server.host

By default, ChatRoom listens only on the local loopback address:

127.0.0.1

This is the recommended configuration. In most cases, use Caddy, Nginx, Cloudflare Tunnel, Tailscale Funnel, or another secure ingress method to expose the local service instead of making ChatRoom listen directly on all network interfaces.

If you change server.host to a non-loopback address, for example:

{
  "server": {
    "host": "0.0.0.0",
    "port": 8765
  }
}

then you must also enable:

{
  "auth": {
    "localWebAuth": true
  }
}

Otherwise, ChatRoom refuses to start.

server.port

Default port:

8765

The valid range is 1 to 65535.

You can temporarily override it with an environment variable:

CHATROOM_SERVER_PORT=9000 chatroom serve

auth

auth controls WebUI authentication, local owner authentication, and remote MCP OAuth behavior.

auth.localWebAuth

Default value:

false

When ChatRoom listens only on 127.0.0.1, localhost, or ::1, the local WebUI does not require authentication by default.

If ChatRoom listens directly on a non-loopback address, this option must be set to:

true

When enabled, the WebUI must establish a session through ChatRoom's owner authentication mechanism.

auth.ownerToken

ownerToken is the owner credential for the ChatRoom instance.

chatroom init automatically generates a random token and writes it to the configuration file. For example:

{
  "auth": {
    "ownerToken": "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
  }
}

It is mainly used for:

• confirming the owner's identity on the authorization page when ChatGPT connects to ChatRoom through OAuth;
• establishing an owner session when WebUI authentication is enabled;
• other operations that require confirmation of instance ownership.

If any of localWebAuth, mcpPublicBaseUrl, or webPublicBaseUrl is enabled, ownerToken must not be empty. Otherwise, ChatRoom refuses to start.

If the token is exposed, generate and replace it instead of continuing to use the old token.

auth.mcpPublicBaseUrl

mcpPublicBaseUrl tells ChatRoom which public HTTPS base URL external clients use to access the instance's MCP service.

Default value:

null

For a self-hosted public MCP endpoint, for example:

{
  "auth": {
    "mcpPublicBaseUrl": "https://mcp.example.com"
  }
}

The corresponding MCP endpoint is:

https://mcp.example.com/mcp

Setting this field does not automatically create a public connection or reverse proxy. You still need to configure Caddy, Nginx, a tunnel, or another network ingress to forward public HTTPS traffic to ChatRoom's local port.

If you only use ChatRoom locally, leave this as null.

auth.webPublicBaseUrl

webPublicBaseUrl specifies the public base URL used when the WebUI is exposed externally.

Default value:

null

For example:

{
  "auth": {
    "webPublicBaseUrl": "https://chatroom.example.com"
  }
}

Like mcpPublicBaseUrl, this setting only declares the external address. It does not create the public network connection itself.

If the WebUI does not need public access, leave this as null.

auth.allowedRedirectHosts

allowedRedirectHosts is the host allowlist for OAuth callback URLs.

Default value:

[
  "chatgpt.com",
  "localhost",
  "127.0.0.1"
]

When ChatGPT or another OAuth client registers a redirect URL, its hostname must be present in this list.

Remote OAuth redirects must use HTTPS. Only loopback addresses such as localhost, 127.0.0.1, and ::1 may use HTTP.

You normally do not need to change this setting when using ChatGPT. If you need to connect another OAuth client, add its callback host explicitly. Avoid overly broad allowlist entries.

audit

audit controls how operation audit records are stored.

audit.maxPayloadBytes

Default value:

524288

That is 512 KiB.

It limits the maximum JSON payload size saved for the input, output, or error data of a single audit event. When the limit is exceeded, ChatRoom truncates the record instead of writing unbounded output to the database.

Allowed range:

4096 to 16777216 bytes

That is 4 KiB to 16 MiB.

Increasing this value preserves more complete large inputs and outputs in the WebUI, but also increases database storage usage.

process

process controls output limits, timeouts, and runtime history retention for commands and PTY processes supervised by ChatRoom.

process.maxOutputBytes

Default value:

524288

That is 512 KiB.

It limits the amount of stdout and stderr retained in memory for each supervised process. Once the limit is exceeded, ChatRoom keeps output within a bounded range to prevent unbounded memory growth.

Allowed range:

4096 to 67108864 bytes

That is 4 KiB to 64 MiB.

process.defaultTimeoutMs

Default value:

1800000

That is 30 minutes.

This is the default timeout used when ChatRoom starts a command without an explicitly specified timeout.

Allowed range:

1000 to 86400000 ms

That is 1 second to 24 hours.

process.maxCompletedProcesses

Default value:

200

This controls how many completed process records are retained in runtime memory.

Allowed range:

0 to 10000

Set it to 0 to retain no completed-process runtime history.

agents

Under Development

Agent configuration is still under development and is not supported in the current version. The information below only documents the reserved configuration structure. Do not rely on or use this feature yet.

agents is an advanced configuration section reserved for registering ACP Agents or ordinary external CLI Agents.

Default configuration:

{
  "agents": {
    "acp": [],
    "external": []
  }
}

You do not need to configure this section to use ChatRoom's normal MCP file, Git, process, or Worktree features.

ACP Agent

Example:

{
  "agents": {
    "acp": [
      {
        "name": "example-acp",
        "command": "example-acp-agent",
        "args": [],
        "permissionPolicy": "deny",
        "capabilities": {
          "filesystem": "read",
          "process": "none",
          "network": "denied"
        }
      }
    ],
    "external": []
  }
}

Field reference:

Field	Description
name	Unique Agent name within ChatRoom
command	ACP Agent executable to run
args	Additional command-line arguments passed when starting the Agent
permissionPolicy	ACP permission request policy: deny or allow-once
capabilities.filesystem	Filesystem capability declaration: none, read, or write
capabilities.process	Process capability declaration: none or execute
capabilities.network	Network capability declaration: denied or allowed

permissionPolicy: "deny" rejects permission requests from the ACP Agent. allow-once only automatically selects an ACP-provided one-time permission option and never grants persistent permission.

External CLI Agent

external is reserved for registering an ordinary command-line program as an Agent Provider. For example:

{
  "agents": {
    "acp": [],
    "external": [
      {
        "name": "my-agent",
        "command": "my-agent-cli",
        "args": ["--mode", "chat"],
        "capabilities": {
          "filesystem": "read",
          "process": "none",
          "network": "denied"
        }
      }
    ]
  }
}

When ChatRoom starts an Agent, the command runs from the corresponding Workspace root and the prompt is passed as the final command-line argument.

capabilities is the capability set declared and matched by the Provider. This is an advanced extension interface. Do not enable broader permissions unless you fully understand the behavior of the corresponding Agent.

Environment Variable Overrides

ChatRoom currently supports the following configuration-related environment variables:

Environment variable	Purpose
CHATROOM_CONFIG	Selects a configuration file instead of the default ~/.chatroom/config.json
CHATROOM_DATABASE	Overrides databasePath
CHATROOM_SERVER_PORT	Overrides server.port

For example, to start ChatRoom with a different configuration file:

CHATROOM_CONFIG=/etc/chatroom/config.json chatroom serve

These overrides affect only the current process and do not modify the original config.json automatically.

After Changing the Configuration

ChatRoom currently reads its configuration at startup. After changing config.json, restart ChatRoom:

chatroom serve

If ChatRoom is managed by systemd, Docker, or another process manager, restart the instance through the corresponding service management mechanism.

You can check whether the current configuration loads correctly with:

chatroom doctor

doctor displays the current configuration file path, allowed roots, database path, listening address, and public MCP/Web status.