Skip to main content

​
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.
VariableOverridesDescription
CODEWIRE_NODE_NAMEnode.nameNode display name
CODEWIRE_LISTENnode.listenWebSocket listen address
CODEWIRE_EXTERNAL_URLnode.external_urlAdvertised URL for clients
CODEWIRE_RELAY_URLnode.relay_urlRelay 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:
FlagDescription
--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)