Configuration

Config File

Located at ~/.codewire/config.toml. Used for standalone mode (node, relay, sessions).

[node]
name = "my-node"                          # Node name
listen = "0.0.0.0:9100"                   # Direct WebSocket (optional)
external_url = "wss://host/ws"            # Advertised URL
relay_url = "https://relay.codewire.sh"   # Opt-in remote access

Platform Config

Platform mode stores its configuration separately in ~/.codewire/:

platform.json — server URL, auth tokens, selected org/resource
Created automatically by cw setup

Platform config is independent of the standalone config — you can use both modes simultaneously.

Environment Variables

Environment variables override config file values.

Variable	Overrides	Description
`CODEWIRE_NODE_NAME`	`node.name`	Node display name
`CODEWIRE_LISTEN`	`node.listen`	WebSocket listen address
`CODEWIRE_EXTERNAL_URL`	`node.external_url`	Advertised URL for clients
`CODEWIRE_RELAY_URL`	`node.relay_url`	Relay server URL
`CODEWIRE_TOKEN`	—	Auth token (useful in containers)

Data Directory

~/.codewire/ contains all runtime state.

~/.codewire/
|-- codewire.sock         # Unix domain socket
|-- codewire.pid          # Node PID file
|-- token                 # Auth token (direct WS fallback)
|-- config.toml           # Standalone configuration
|-- platform.json         # Platform mode configuration
|-- servers.toml          # Saved remote servers
|-- sessions.json         # Session metadata
`-- sessions/
    |-- 1/
    |   |-- output.log    # Captured PTY output
    |   `-- events.jsonl  # Metadata event log
    `-- 2/
        |-- output.log
        `-- events.jsonl

Global Flags

All commands accept these global flags:

Flag	Description
`--server <name\|url>`	Connect to a remote server or relay
`--token <token>`	Authentication token for remote connections

Wire Protocol

Binary frame-based protocol used over both Unix socket and WebSocket.

Frame Format:
+----------+---------------+----------------------+
| type     | length        | payload              |
| 1 byte   | 4 bytes (BE)  | up to 16 MB          |
+----------+---------------+----------------------+

type = 0x00  Control  -- JSON-encoded Request/Response
type = 0x01  Data     -- Raw bytes (PTY I/O)

WebSocket Mapping:
Text   frames -- Control messages (JSON)
Binary frames -- Data messages (raw bytes)

​Configuration

​Config File

​Platform Config

​Environment Variables

​Data Directory

​Global Flags

​Wire Protocol