also looking at this
docs: the documentation the README points at
#63
9 files
+509
-10
| @@ -0,0 +1,92 @@ | ||
| 1 | # Configuration | |
| 2 | ||
| 3 | There are two ways to configure Uplink, and which one applies depends on how you installed it. | |
| 4 | ||
| 5 | - **The app** reads `~/Library/Application Support/Uplink/settings.json`, which the menubar writes. | |
| 6 | You do not normally edit it by hand. | |
| 7 | - **From source** reads `.env`. The service picks up edits by itself, once no run is in progress. | |
| 8 | ||
| 9 | Both end up in the same shape. `config/uplink.ts` holds the defaults, and every key can be | |
| 10 | overridden by its `UPLINK_*` variable. | |
| 11 | ||
| 12 | ## What the menubar sets | |
| 13 | ||
| 14 | | Setting | What it is | | |
| 15 | | --- | --- | | |
| 16 | | Who can text it | The handles allowed to command Uplink. Empty means this Mac's own Messages handles, the "text yourself" setup | | |
| 17 | | Agent | Claude Code or Codex, for the whole installation. A thread can override it by texting `claude` or `codex` | | |
| 18 | | Model | The model alias for runs. Empty means the CLI's default | | |
| 19 | | Where runs start | The directory a run uses when a text names no path | | |
| 20 | | Open at login | Whether the LaunchAgent starts it | | |
| 21 | | Paused | Read nothing, answer nothing, until resumed | | |
| 22 | ||
| 23 | A `settings.json` this build cannot read falls back per field rather than refusing to start, so a | |
| 24 | hand edit with a typo cannot stop the app. | |
| 25 | ||
| 26 | ## Every variable | |
| 27 | ||
| 28 | These are the `.env` names. The app builds the same environment from its settings. | |
| 29 | ||
| 30 | ### Who and where | |
| 31 | ||
| 32 | | Variable | Default | What it does | | |
| 33 | | --- | --- | --- | | |
| 34 | | `UPLINK_ALLOWED` | empty | Comma separated handles allowed to command it. Empty means your own | | |
| 35 | | `UPLINK_WORKDIR` | `~` | Where a run starts when a text names no path | | |
| 36 | ||
| 37 | Anyone on that list can make an agent act on your Mac. List only yourself. | |
| 38 | ||
| 39 | ### Which agent | |
| 40 | ||
| 41 | | Variable | Default | What it does | | |
| 42 | | --- | --- | --- | | |
| 43 | | `UPLINK_ENGINE` | `claude` | `claude` or `codex` | | |
| 44 | | `CLAUDE_CODE_OAUTH_TOKEN` | none | From `claude setup-token`. Encrypt it with `./buddy env:set` | | |
| 45 | | `UPLINK_CLAUDE_MODEL` | empty | Model alias. `UPLINK_MODEL` is the older name and still works | | |
| 46 | | `UPLINK_CLAUDE_BIN` | found | Where the `claude` binary is, if it is not on PATH | | |
| 47 | | `UPLINK_CODEX_BIN` | found | Where `codex` is. Uplink also looks inside ChatGPT.app, which bundles one | | |
| 48 | | `UPLINK_CODEX_MODEL` | empty | Model the agent should use | | |
| 49 | | `UPLINK_CODEX_PERMISSION` | `bypass` | How much Codex may do without asking. Also `danger-full-access`, `workspace-write`, `read-only` | | |
| 50 | ||
| 51 | Codex keeps its own credentials under `CODEX_HOME`, so there is no token to put in `.env`. | |
| 52 | ||
| 53 | "Found" means Uplink looks where each installer puts the binary, because launchd hands a background | |
| 54 | service a bare PATH and `claude` from your shell is not necessarily findable. | |
| 55 | ||
| 56 | ### Replies | |
| 57 | ||
| 58 | | Variable | Default | What it does | | |
| 59 | | --- | --- | --- | | |
| 60 | | `UPLINK_MAX_CHARS` | `1200` | Characters per text. Longer replies are split | | |
| 61 | | `UPLINK_MAX_PARTS` | `3` | Parts sent at once. The rest waits for `more` | | |
| 62 | | `UPLINK_REPLY_PREFIX` | `🛰 ` | Every reply starts with this | | |
| 63 | | `UPLINK_ACK_AFTER_MS` | `20000` | "Working on it" once a run passes this. 0 disables | | |
| 64 | | `UPLINK_PROGRESS_EVERY_MS` | `600000` | A progress line this often. 0 disables | | |
| 65 | ||
| 66 | The prefix matters for more than looks: it is how Uplink tells its own replies apart from new | |
| 67 | commands in a thread with yourself. | |
| 68 | ||
| 69 | ### Timing | |
| 70 | ||
| 71 | | Variable | Default | What it does | | |
| 72 | | --- | --- | --- | | |
| 73 | | `UPLINK_POLL_MS` | `2000` | How often to look for new texts | | |
| 74 | | `UPLINK_TIMEOUT_MS` | `5400000` | How long one run may take before it is stopped | | |
| 75 | | `UPLINK_CATCH_UP_MS` | `1800000` | On start, skip commands older than this | | |
| 76 | | `UPLINK_SESSION_IDLE_MS` | `21600000` | A thread idle longer than this starts a fresh agent session | | |
| 77 | ||
| 78 | `UPLINK_CATCH_UP_MS` is why a Mac waking after a night asleep does not replay the whole night. A | |
| 79 | text older than it is not run, and you get one reply saying so rather than silence. | |
| 80 | ||
| 81 | ## Where things live | |
| 82 | ||
| 83 | | Path | What it is | | |
| 84 | | --- | --- | | |
| 85 | | `~/Library/Application Support/Uplink/settings.json` | The app's settings | | |
| 86 | | `~/Library/Application Support/Uplink/uplink.sqlite` | Conversations and runs | | |
| 87 | | `~/Library/Application Support/Uplink/license.json` | The last answer the licence server gave | | |
| 88 | | `~/Library/Logs/Uplink.log` | The log, rotated at 5 MB to `Uplink.log.1` | | |
| 89 | | `~/Library/LaunchAgents/com.stacksjs.uplink.plist` | What starts it at login | | |
| 90 | ||
| 91 | Two things are in the Keychain rather than in a file, both under the service | |
| 92 | `com.stacksjs.uplink`: the account `claude-oauth-token` and the account `license-key`. | |