tarmac-web Public

Watch 0 Fork 0 Star 0
Text · 3437 bytes Raw Blame History
1 # First Run
2
3 ## Grant Accessibility permissions
4
5 tarmac uses the macOS Accessibility API to move and resize windows. You must grant it permission before it can do anything.
6
7 1. Open **System Settings** (or System Preferences on older macOS)
8 2. Navigate to **Privacy & Security → Accessibility**
9 3. Click the lock icon to make changes
10 4. Click **+** and add the `tarmac` binary (typically `/usr/local/bin/tarmac`)
11 5. Ensure the checkbox next to tarmac is enabled
12
13 <img
14 src="/accessibility-permissions.png"
15 alt="macOS System Settings — Privacy & Security — Accessibility panel with tarmac enabled"
16 width={800}
17 height={600}
18 className="rounded-lg border border-surface-200 dark:border-surface-700 my-6"
19 loading="lazy"
20 />
21
22 If you skip this step, tarmac will detect the missing permission at startup and print a message telling you to grant it. It will not crash, but it won't be able to manage any windows.
23
24 > If you've rebuilt tarmac from source, macOS may revoke the permission because the binary signature changed. You'll need to remove and re-add it.
25
26 ## Starting tarmac
27
28 Run the daemon from a terminal:
29
30 ```bash
31 tarmac
32 ```
33
34 tarmac runs in the foreground and logs to stderr. You'll see output like:
35
36 ```
37 INFO tarmac: config loaded from /Users/you/.config/tarmac/init.lua
38 INFO tarmac: IPC server listening at /tmp/tarmac-you.sock
39 INFO tarmac: found 2 monitors, managing 8 windows
40 ```
41
42 ### Running in the background
43
44 To run tarmac as a background process:
45
46 ```bash
47 tarmac &>/dev/null &
48 ```
49
50 Or use a login item / launchd agent to start it automatically on login. A basic plist:
51
52 ```bash
53 mkdir -p ~/Library/LaunchAgents
54 ```
55
56 Create `~/Library/LaunchAgents/com.gardesk.tarmac.plist`:
57
58 ```xml
59 <?xml version="1.0" encoding="UTF-8"?>
60 <!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN"
61 "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
62 <plist version="1.0">
63 <dict>
64 <key>Label</key>
65 <string>com.gardesk.tarmac</string>
66 <key>ProgramArguments</key>
67 <array>
68 <string>/usr/local/bin/tarmac</string>
69 </array>
70 <key>RunAtLoad</key>
71 <true/>
72 <key>KeepAlive</key>
73 <true/>
74 <key>StandardOutPath</key>
75 <string>/tmp/tarmac.out.log</string>
76 <key>StandardErrorPath</key>
77 <string>/tmp/tarmac.err.log</string>
78 <key>EnvironmentVariables</key>
79 <dict>
80 <key>RUST_LOG</key>
81 <string>tarmac=info</string>
82 </dict>
83 </dict>
84 </plist>
85 ```
86
87 Load it:
88
89 ```bash
90 launchctl load ~/Library/LaunchAgents/com.gardesk.tarmac.plist
91 ```
92
93 ## Default config
94
95 On first run, if `~/.config/tarmac/init.lua` doesn't exist, tarmac uses built-in defaults:
96
97 - **Modifier key:** Command
98 - **Gaps:** 0 (no gaps)
99 - **Focus follows mouse:** enabled
100 - **Mouse follows focus:** enabled
101 - **Borders:** disabled (set `border_width > 0` to enable)
102 - **Terminal:** `open -na WezTerm`
103
104 All default keybindings are listed in [Default Binds](/docs/keybindings/defaults).
105
106 ## Stopping tarmac
107
108 Press `Ctrl+C` in the terminal where tarmac is running, or:
109
110 ```bash
111 kill $(pgrep tarmac)
112 ```
113
114 If using launchd:
115
116 ```bash
117 launchctl unload ~/Library/LaunchAgents/com.gardesk.tarmac.plist
118 ```
119
120 When tarmac exits, windows return to their previous floating state — macOS handles them as normal.
121
122 ## Logging
123
124 Control log verbosity with `RUST_LOG`:
125
126 ```bash
127 RUST_LOG=tarmac=debug tarmac # verbose
128 RUST_LOG=tarmac=info tarmac # normal (default)
129 RUST_LOG=tarmac=warn tarmac # quiet
130 ```
131
132 This uses the standard Rust `tracing` crate filter syntax.
133