wirecanal.json Configuration Reference

Basic form — works exactly as downloaded

The wirecanal.json downloaded from the "Setup" tab of the canal details works as is. It contains just these 2 keys.

{
  "access_key": "ck_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
  "forward_target": "localhost:3000"
}

Key	Required	Description
`access_key`	Required	The per-canal connection key (starts with `ck_`). This single key identifies which canal it is; settings such as the public hostname are fetched automatically from the cloud side. You can revoke and reissue it anytime from the dashboard.
`forward_target`	Required	The local destination that incoming traffic is delivered to. Written as `host:port`, e.g. `"localhost:3000"`. The Agent never connects to any destination other than the one written here (the fixed forwarding destination).

infoConfiguration is loaded at startup

After editing wirecanal.json, restart the Agent (for a Windows service, service stop → service start). Also, for a running Agent, the local wirecanal.json is the source of truth — the forwarding destination can never be rewritten from the cloud side. If the configuration is invalid, the Agent stops at startup with the reason displayed (it never keeps running with a broken configuration).

Commonly used options

When you need one, just add a single line to the basic form.

Key	Default	Description / example
`lang`	`"ja"`	Display language for startup messages and logs. For English, set `"lang": "en"`. Handy for servers at overseas sites.
`access_log`	`true`	Whether incoming requests are printed to the Agent's console. For quiet operation, set `"access_log": false`.
`auto_update`	`true`	Automatically replaces the Agent when a new version is released (applied only after signature verification; rolls back to the previous version on failure). Only if you want to disable it, set `"auto_update": false`.
`proxy_url`	none	For corporate networks that require a proxy. `"proxy_url": "http://proxy.example.co.jp:8080"` (for Basic auth, `http://user:pass@proxy:8080`). Environment-variable proxy settings are not consulted — the proxy is used only when this key is set. It applies only to outbound connections, not to the forwarding destination (your internal side).

Running multiple canals on one machine

A single Agent (one process) can open multiple canals at the same time, using the canals array (when you select multiple canals in the dashboard's Setup tab and download, the file is generated in this format).

{
  "canals": [
    { "access_key": "ck_xxxxxxxx...", "forward_target": "localhost:3000" },
    { "access_key": "ck_yyyyyyyy...", "forward_target": "localhost:8080" }
  ],
  "lang": "ja"
}

check_circleShared options such as lang, access_log, proxy_url, and auto_update go at the top level and apply to all canals (they cannot be written inside individual entries).
check_circlecanals cannot be combined with top-level access_key/forward_target (use one format or the other). Up to 32 entries can be bundled.
check_circleIf even one entry is misconfigured, the whole Agent refuses to start (it never leaves you in a half-published state).

MCP canal configuration (deciding which tools to expose)

For an MCP canal, wirecanal.json has 4 keys. Which tools are shown to outside AI is decided solely by this local file (it can never be changed from the cloud side — the allowlist ledger stays in your hands: the two-key design).

{
  "access_key": "ck_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
  "forward_target": "localhost:9310",
  "mode": "mcp",
  "tools": {
    "default": "deny",
    "allow": ["search_documents", "get_ticket"],
    "deny_destructive": true,
    "hide_denied_in_list": true
  }
}

Key	Default	Description
`mode`	auto	Generated by the dashboard according to the canal type (`"mcp"` for an MCP canal). There is no need to edit it by hand (if it disagrees with the canal type, the Agent stops at startup and tells you).
`tools.default`	`"deny"`	How tools not on the allowlist are treated. Keeping the default `deny` is recommended (with an empty `allow` list, you start safely from "connected, but all tools declined").
`tools.allow`	`[]`	The list of tool names that may be shown to outside AI (exact match).
`tools.deny_destructive`	`false`	When `true`, tools whose names indicate mutation — delete / drop / remove and the like — are denied as a group (takes precedence over the allowlist).
`tools.hide_denied_in_list`	`false`	When `true`, tools that are not allowed are not even included in the listing visible to AI (tools/list).

Advanced settings (normally no changes needed)

The options below can be left at their defaults. Add them only when you have a specific requirement.

Key	Default	Description
`forward_target` (detailed form)	—	Can also be written as an object instead of a string: `{"host": "127.0.0.1", "port": 3001, "scheme": "http"}`. If your forwarding destination serves HTTPS, use `"scheme": "https"`. Only localhost-type destinations are accepted; only when you need to target another internal hostname (FQDN), explicitly set `"allow_hostnames": true` (disallowed by default to prevent forwarding to unintended destinations).
`timeouts`	—	Reserved key (for future use. The current Agent runs on internal defaults, and writing this key does not change behavior). How long to wait for a response (default 120 seconds) can be changed in the server-side canal settings: the Setup tab of the canal details, or `response_timeout_sec` in the public API (paid plans, up to 3600 seconds).
`reconnect`	auto	Reconnection intervals. Backs off gradually from `base: "1s"` up to `max_interval: "30s"` and keeps retrying without giving up (designed for resident operation).
`limits`	—	Reserved key (for future use. The current Agent runs on internal defaults, and writing this key does not change behavior). Traffic control is performed on the server side (plans and the shared infrastructure).
`audit`	disabled	Keeps a local record of tool invocations: `{"enabled": true, "path": "log output path", "hash_chain": true}`. `hash_chain` is a format that can detect tampering with the records. Records stay inside your network by default (`ship_metadata_to_edge` defaults to `false`).
`kill_switch`	none	The location of an emergency-stop file: `{"file": "path"}`. The moment this file is created, all forwarding stops immediately (delete it to resume).

Handling precautions

check_circlewirecanal.json contains your connection key. Restrict read access to yourself (on Linux, chmod 600; on Windows, folder access permissions).
check_circleIf you suspect a key has leaked, you can revoke and reissue it immediately from the dashboard (the impact is limited to that single canal — and thanks to the fixed forwarding destination, the key cannot be used for any destination other than the one written in the file).
check_circleTo leave comments, keys starting with "__" (e.g. "__about") are ignored, so you can use them as notes.

Create a canal for free Back to the setup guide

wirecanal.json specification