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

# Configuration

> Config file, environment variables, and data directory layout.

# Configuration

## Config File

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

```toml theme={null}
[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)
```