tarmac-web Public

Watch 0 Fork 0 Star 0

Text · 2387 bytes Raw Blame History

  
        1
        # Socket & Protocol
      
        2
        
        3
        ## Socket location
      
        4
        
        5
        By default, the IPC socket is at:
      
        6
        
        7
        ```
      
        8
        /tmp/tarmac-$USER.sock
      
        9
        ```
      
        10
        
        11
        For example, `/tmp/tarmac-alice.sock`.
      
        12
        
        13
        Override with the `TARMAC_SOCKET` environment variable:
      
        14
        
        15
        ```bash
      
        16
        TARMAC_SOCKET=/tmp/my-tarmac.sock tarmac
      
        17
        ```
      
        18
        
        19
        ## Permissions
      
        20
        
        21
        The socket is created with mode `0600` (owner read/write only). Only the user who started tarmac can connect to it.
      
        22
        
        23
        ## Protocol
      
        24
        
        25
        The protocol is line-based JSON. Each request and response is a single JSON object terminated by a newline (`\n`).
      
        26
        
        27
        ### Request format
      
        28
        
        29
        ```json
      
        30
        {"command": "focus", "args": ["left"]}
      
        31
        ```
      
        32
        
        33
        | Field | Type | Required | Description |
      
        34
        |-------|------|----------|-------------|
      
        35
        | `command` | string | yes | The command name |
      
        36
        | `args` | string[] | no | Command arguments (defaults to `[]`) |
      
        37
        
        38
        ### Response format
      
        39
        
        40
        ```json
      
        41
        {"success": true, "data": {...}, "error": null}
      
        42
        ```
      
        43
        
        44
        | Field | Type | Description |
      
        45
        |-------|------|-------------|
      
        46
        | `success` | bool | Whether the command succeeded |
      
        47
        | `data` | any/null | Response data (for query commands) |
      
        48
        | `error` | string/null | Error message if `success` is false |
      
        49
        
        50
        ### Examples
      
        51
        
        52
        Successful command:
      
        53
        
        54
        ```json
      
        55
        → {"command":"workspace","args":["3"]}
      
        56
        ← {"success":true}
      
        57
        ```
      
        58
        
        59
        Query with data:
      
        60
        
        61
        ```json
      
        62
        → {"command":"get-focused","args":[]}
      
        63
        ← {"success":true,"data":{"window_id":1234,"app_name":"Firefox","title":"Home"}}
      
        64
        ```
      
        65
        
        66
        Error:
      
        67
        
        68
        ```json
      
        69
        → {"command":"invalid","args":[]}
      
        70
        ← {"success":false,"error":"unknown command: invalid"}
      
        71
        ```
      
        72
        
        73
        ## Raw socket access
      
        74
        
        75
        You can interact with the socket directly using `socat` or `nc`:
      
        76
        
        77
        ```bash
      
        78
        echo '{"command":"get-workspaces","args":[]}' | socat - UNIX-CONNECT:/tmp/tarmac-$USER.sock
      
        79
        ```
      
        80
        
        81
        Or keep a connection open for multiple commands:
      
        82
        
        83
        ```bash
      
        84
        socat READLINE UNIX-CONNECT:/tmp/tarmac-$USER.sock
      
        85
        ```
      
        86
        
        87
        Then type JSON requests interactively.
      
        88
        
        89
        ## Timeouts
      
        90
        
        91
        If a command doesn't complete within 5 seconds, the IPC server returns a timeout error:
      
        92
        
        93
        ```json
      
        94
        {"success": false, "error": "command timed out"}
      
        95
        ```
      
        96
        
        97
        This prevents stalled commands from blocking other IPC clients.
      
        98
        
        99
        ## Connection lifecycle
      
        100
        
        101
        Each IPC connection can send multiple requests sequentially. The connection stays open until the client closes it or the daemon shuts down.
      
        102
        
        103
        The one exception is the `subscribe` command, which switches the connection into streaming mode — see [Events & Subscribe](/docs/ipc/events-subscribe).
      
        104

1	# Socket & Protocol
2
3	## Socket location
4
5	By default, the IPC socket is at:
6
7	```
8	/tmp/tarmac-$USER.sock
9	```
10
11	For example, `/tmp/tarmac-alice.sock`.
12
13	Override with the `TARMAC_SOCKET` environment variable:
14
15	```bash
16	TARMAC_SOCKET=/tmp/my-tarmac.sock tarmac
17	```
18
19	## Permissions
20
21	The socket is created with mode `0600` (owner read/write only). Only the user who started tarmac can connect to it.
22
23	## Protocol
24
25	The protocol is line-based JSON. Each request and response is a single JSON object terminated by a newline (`\n`).
26
27	### Request format
28
29	```json
30	{"command": "focus", "args": ["left"]}
31	```
32
33	\| Field \| Type \| Required \| Description \|
34	\|-------\|------\|----------\|-------------\|
35	\| `command` \| string \| yes \| The command name \|
36	\| `args` \| string[] \| no \| Command arguments (defaults to `[]`) \|
37
38	### Response format
39
40	```json
41	{"success": true, "data": {...}, "error": null}
42	```
43
44	\| Field \| Type \| Description \|
45	\|-------\|------\|-------------\|
46	\| `success` \| bool \| Whether the command succeeded \|
47	\| `data` \| any/null \| Response data (for query commands) \|
48	\| `error` \| string/null \| Error message if `success` is false \|
49
50	### Examples
51
52	Successful command:
53
54	```json
55	→ {"command":"workspace","args":["3"]}
56	← {"success":true}
57	```
58
59	Query with data:
60
61	```json
62	→ {"command":"get-focused","args":[]}
63	← {"success":true,"data":{"window_id":1234,"app_name":"Firefox","title":"Home"}}
64	```
65
66	Error:
67
68	```json
69	→ {"command":"invalid","args":[]}
70	← {"success":false,"error":"unknown command: invalid"}
71	```
72
73	## Raw socket access
74
75	You can interact with the socket directly using `socat` or `nc`:
76
77	```bash
78	echo '{"command":"get-workspaces","args":[]}' \| socat - UNIX-CONNECT:/tmp/tarmac-$USER.sock
79	```
80
81	Or keep a connection open for multiple commands:
82
83	```bash
84	socat READLINE UNIX-CONNECT:/tmp/tarmac-$USER.sock
85	```
86
87	Then type JSON requests interactively.
88
89	## Timeouts
90
91	If a command doesn't complete within 5 seconds, the IPC server returns a timeout error:
92
93	```json
94	{"success": false, "error": "command timed out"}
95	```
96
97	This prevents stalled commands from blocking other IPC clients.
98
99	## Connection lifecycle
100
101	Each IPC connection can send multiple requests sequentially. The connection stays open until the client closes it or the daemon shuts down.
102
103	The one exception is the `subscribe` command, which switches the connection into streaming mode — see [Events & Subscribe](/docs/ipc/events-subscribe).
104