@akshar5/cohall 0.6.2 → 0.7.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/CHANGELOG.md +8 -0
- package/README.md +54 -3
- package/bin/cohall.js +844 -287
- package/bin/cohall.js.map +12 -11
- package/docs/grok-bot.md +196 -0
- package/docs/install.md +5 -5
- package/docs/integrations.md +8 -1
- package/docs/services.md +4 -0
- package/package.json +1 -1
package/docs/grok-bot.md
ADDED
|
@@ -0,0 +1,196 @@
|
|
|
1
|
+
# Connect Grok Bot
|
|
2
|
+
|
|
3
|
+
One Cohall worker on the Grok Bot computer discovers all of its existing named
|
|
4
|
+
Bots. You pair the computer once, then address individual Bots by name from any
|
|
5
|
+
paired device. The Bots keep their Grok conversations, tools, and permissions.
|
|
6
|
+
|
|
7
|
+
You need a running Cohall relay, Node.js 24 or newer on the Grok Bot computer,
|
|
8
|
+
and a way for that computer to reach the relay. Use an HTTPS relay if you have
|
|
9
|
+
one. The Tailscale steps below are for a relay reachable only through a tailnet.
|
|
10
|
+
|
|
11
|
+
## 1. Give the computer access to the relay
|
|
12
|
+
|
|
13
|
+
`tag:grokbot` is a suggested Tailscale identity for the **computer**, not a tag
|
|
14
|
+
that Cohall requires. Tailscale tags replace a device's user identity, so use it
|
|
15
|
+
for the Bot computer rather than your personal laptop. The Bot initiates an
|
|
16
|
+
outbound connection to the relay. It does not need Tailscale SSH, an exit node,
|
|
17
|
+
subnet routes, or an inbound grant. [Tailscale's tag guide](https://tailscale.com/docs/features/tags)
|
|
18
|
+
explains tag ownership and device identity.
|
|
19
|
+
|
|
20
|
+
The relay must listen on its Tailscale address and port, not only on
|
|
21
|
+
`127.0.0.1`. Follow [Linux relay setup](services.md#linux-relay) if it is still
|
|
22
|
+
local-only. Keep the listener private.
|
|
23
|
+
|
|
24
|
+
In the Tailscale admin console's **Access controls**, add these entries to your
|
|
25
|
+
existing policy. Replace the example IP and port with your relay's Tailscale IP
|
|
26
|
+
and listening port. Keep the rest of your policy:
|
|
27
|
+
|
|
28
|
+
```jsonc
|
|
29
|
+
{
|
|
30
|
+
"tagOwners": {
|
|
31
|
+
"tag:grokbot": ["autogroup:admin"],
|
|
32
|
+
},
|
|
33
|
+
"grants": [
|
|
34
|
+
{
|
|
35
|
+
"src": ["tag:grokbot"],
|
|
36
|
+
"dst": ["100.101.102.103"],
|
|
37
|
+
"ip": ["tcp:8787"],
|
|
38
|
+
},
|
|
39
|
+
],
|
|
40
|
+
}
|
|
41
|
+
```
|
|
42
|
+
|
|
43
|
+
This grant allows tagged computers to initiate TCP connections to that relay
|
|
44
|
+
port. Tailscale combines grants, so check existing broader rules if you want
|
|
45
|
+
this to be the computer's only tailnet access. See the
|
|
46
|
+
[grants syntax](https://tailscale.com/docs/reference/syntax/grants).
|
|
47
|
+
|
|
48
|
+
For a new Tailscale device, create a **one-off, non-ephemeral** auth key with
|
|
49
|
+
`tag:grokbot` selected under **Keys** in the Tailscale admin console. Give that
|
|
50
|
+
key to the Grok Bot computer through a masked secret input or a mode-`0600`
|
|
51
|
+
temporary file. Never paste it into an ordinary Bot chat or a shell command
|
|
52
|
+
argument. The Tailscale CLI accepts `--auth-key=file:/path/to/key`; remove the
|
|
53
|
+
temporary file after joining. A tagged key applies the tag when the device
|
|
54
|
+
joins. If the computer is already on your tailnet, an admin can instead add
|
|
55
|
+
`tag:grokbot` under **Machines > Edit tags** without creating a new key.
|
|
56
|
+
[Tailscale's auth key guide](https://tailscale.com/docs/features/access-control/auth-keys)
|
|
57
|
+
covers both one-off keys and tagged devices.
|
|
58
|
+
|
|
59
|
+
On the Bot computer, verify that Tailscale is connected and that the relay
|
|
60
|
+
responds:
|
|
61
|
+
|
|
62
|
+
```bash
|
|
63
|
+
tailscale status
|
|
64
|
+
curl -fsS http://100.101.102.103:8787/api/health
|
|
65
|
+
```
|
|
66
|
+
|
|
67
|
+
Replace the example address again. Check the computer's `tag:grokbot` identity
|
|
68
|
+
on the Tailscale **Machines** page. A successful `curl` proves the route works;
|
|
69
|
+
it does not by itself prove which grant allowed it.
|
|
70
|
+
|
|
71
|
+
## 2. Pair the computer with Cohall
|
|
72
|
+
|
|
73
|
+
On the **relay owner account**, create a Cohall full-worker pairing token:
|
|
74
|
+
|
|
75
|
+
```bash
|
|
76
|
+
cohall pair --label "Grok Bot computer"
|
|
77
|
+
```
|
|
78
|
+
|
|
79
|
+
The token lasts ten minutes and works once. Transfer it through a masked secret
|
|
80
|
+
input or a private channel, not the ordinary Bot chat. On the Grok Bot computer,
|
|
81
|
+
install Cohall globally and pair it. Replace the relay URL and workspace with
|
|
82
|
+
your actual values:
|
|
83
|
+
|
|
84
|
+
```bash
|
|
85
|
+
npm install --global --prefix "$HOME/.local" @akshar5/cohall
|
|
86
|
+
"$HOME/.local/bin/cohall" --version
|
|
87
|
+
"$HOME/.local/bin/cohall" init \
|
|
88
|
+
--relay http://100.101.102.103:8787 \
|
|
89
|
+
--name grokbot \
|
|
90
|
+
--workspace /workspace \
|
|
91
|
+
--providers grok-bot
|
|
92
|
+
```
|
|
93
|
+
|
|
94
|
+
Run `init` in an interactive terminal for its masked pairing-token prompt. For
|
|
95
|
+
an agent-run setup without an interactive terminal, put the token in a private
|
|
96
|
+
mode-`0600` file and pass `--token-file /path/to/token`; delete the file after
|
|
97
|
+
pairing. Do not put the token in command arguments or logs. Use an HTTPS URL
|
|
98
|
+
instead if your relay is exposed through HTTPS. The workspace must exist; native
|
|
99
|
+
Bot tasks use the Bot's own computer permissions rather than this workspace
|
|
100
|
+
root, but Codex tasks need a valid root.
|
|
101
|
+
|
|
102
|
+
## 3. Connect the local Grok Bot gateway
|
|
103
|
+
|
|
104
|
+
Find the gateway discovery file on **that computer**. On current Grok Bot
|
|
105
|
+
computers it may be at `$HOME/agent-data/gateway.json`; use the actual path if
|
|
106
|
+
different. The file contains a local gateway credential, so check that it is
|
|
107
|
+
readable without printing or copying its contents:
|
|
108
|
+
|
|
109
|
+
```bash
|
|
110
|
+
test -r "$HOME/agent-data/gateway.json" && "$HOME/.local/bin/cohall" configure \
|
|
111
|
+
--grok-gateway "$HOME/agent-data/gateway.json" \
|
|
112
|
+
--providers grok-bot
|
|
113
|
+
```
|
|
114
|
+
|
|
115
|
+
If the file check fails, find the discovery file used by this Grok Bot
|
|
116
|
+
installation and substitute its path.
|
|
117
|
+
|
|
118
|
+
If Codex is also installed and signed in **on the Bot computer**, use
|
|
119
|
+
`--providers codex,grok-bot` so Bots can delegate coding to that local Codex.
|
|
120
|
+
Cohall does not transfer a Codex login, GitHub login, or skills from another
|
|
121
|
+
computer. The gateway credential stays on the Bot computer; Cohall advertises
|
|
122
|
+
the discovered Bot names through its relay.
|
|
123
|
+
|
|
124
|
+
Start one Cohall worker and keep it running. Restart an existing worker after
|
|
125
|
+
changing its providers or gateway path. On a computer with systemd, use
|
|
126
|
+
`cohall service install`. Grok Bot cloud computers may have no systemd, so use
|
|
127
|
+
the computer's supported supervisor or recurring routine to start the worker
|
|
128
|
+
and Tailscale again after processes stop. Keep Cohall configuration and the
|
|
129
|
+
Tailscale node state on persistent storage. A computer update may remove
|
|
130
|
+
installed packages and stop processes even when its home files survive; the
|
|
131
|
+
recovery routine must reinstall missing programs and restart exactly one copy
|
|
132
|
+
of each worker. An hourly routine can restore availability after an update,
|
|
133
|
+
but does not keep a suspended computer awake or guarantee an immediate restart.
|
|
134
|
+
See [service behavior](services.md#startup-behavior).
|
|
135
|
+
|
|
136
|
+
Verify on the Bot computer:
|
|
137
|
+
|
|
138
|
+
```bash
|
|
139
|
+
"$HOME/.local/bin/cohall" doctor
|
|
140
|
+
"$HOME/.local/bin/cohall" bots
|
|
141
|
+
```
|
|
142
|
+
|
|
143
|
+
`doctor` should report the relay and local gateway reachable, no warnings, and
|
|
144
|
+
the worker online. `bots` should list all discovered Bots, not just the one
|
|
145
|
+
that helped with setup. From another paired device:
|
|
146
|
+
|
|
147
|
+
```bash
|
|
148
|
+
cohall bots
|
|
149
|
+
cohall send '@yt desk' 'Give me three video ideas.'
|
|
150
|
+
cohall send --thread <returned-thread-id> 'Expand the second idea.'
|
|
151
|
+
```
|
|
152
|
+
|
|
153
|
+
Bot names with spaces need quotes. If a name appears on more than one computer,
|
|
154
|
+
use the full target shown by `cohall bots`. A Bot can delegate to Codex on the
|
|
155
|
+
same computer:
|
|
156
|
+
|
|
157
|
+
```bash
|
|
158
|
+
cohall delegate --target @grokbot --provider codex \
|
|
159
|
+
--parent <parent-task-id> --thread <thread-id> \
|
|
160
|
+
--prompt 'Concrete task'
|
|
161
|
+
```
|
|
162
|
+
|
|
163
|
+
See [Bot replies and cancellation](../README.md#talk-to-your-grok-bots) for
|
|
164
|
+
how Cohall records the answer. The local gateway is experimental and may change
|
|
165
|
+
with Grok Bot updates.
|
|
166
|
+
|
|
167
|
+
## Give the setup to a Bot
|
|
168
|
+
|
|
169
|
+
Once you have added the Tailscale policy, you can send this to a Bot on the
|
|
170
|
+
computer. Replace the example relay URL before sending it. Create each one-off
|
|
171
|
+
key only when the Bot asks for it, so the Cohall pairing token does not expire
|
|
172
|
+
while Tailscale is being installed.
|
|
173
|
+
|
|
174
|
+
```text
|
|
175
|
+
Set up Cohall on this Grok Bot computer using the current docs/grok-bot.md in
|
|
176
|
+
https://github.com/AksharP5/cohall. My relay URL is
|
|
177
|
+
http://100.101.102.103:8787. The workspace is /workspace.
|
|
178
|
+
|
|
179
|
+
Install the official Tailscale package and join my tailnet with a one-off,
|
|
180
|
+
non-ephemeral key tagged tag:grokbot. Pause for the key through a masked secret
|
|
181
|
+
input. Never ask me to paste a secret into ordinary chat, and keep it out of
|
|
182
|
+
command arguments, logs, and history. Verify the tag and relay reachability.
|
|
183
|
+
|
|
184
|
+
Ensure Node.js 24 or newer is available. Then install Cohall globally. Ask for
|
|
185
|
+
a separate one-time Cohall full-worker pairing token through secure input and
|
|
186
|
+
pair this computer. Find the local Grok Bot gateway discovery file without
|
|
187
|
+
printing its contents. Configure the
|
|
188
|
+
grok-bot provider. Include Codex only if its CLI is installed and signed in
|
|
189
|
+
here. Start exactly one worker and verify cohall doctor and cohall bots.
|
|
190
|
+
|
|
191
|
+
Use this computer's supported supervisor or routine for recovery if systemd
|
|
192
|
+
is absent. Preserve pairing, gateway configuration, Tailscale identity, and
|
|
193
|
+
home state. Report what restarts automatically, what survives a computer
|
|
194
|
+
update, and anything I must do manually. Do not claim the worker is always on
|
|
195
|
+
if the host stops it between routines.
|
|
196
|
+
```
|
package/docs/install.md
CHANGED
|
@@ -135,11 +135,11 @@ when delegated work starts.
|
|
|
135
135
|
| OpenCode | `opencode` | `opencode run --session` |
|
|
136
136
|
|
|
137
137
|
The experimental `grok-bot` provider connects to named Bots through their
|
|
138
|
-
computer's local gateway.
|
|
139
|
-
|
|
140
|
-
|
|
141
|
-
|
|
142
|
-
Grok Bot.
|
|
138
|
+
computer's local gateway. Follow [Grok Bot computer setup](grok-bot.md) for
|
|
139
|
+
Tailscale access, pairing, provider configuration, and recovery. A worker
|
|
140
|
+
configured with `--providers grok-bot` advertises all Bots found by that
|
|
141
|
+
gateway. Add `codex` only when its CLI is installed and signed in on that
|
|
142
|
+
computer. Bot model selection and permissions remain with Grok Bot.
|
|
143
143
|
|
|
144
144
|
Limit a device to providers configured for that user:
|
|
145
145
|
|
package/docs/integrations.md
CHANGED
|
@@ -4,6 +4,12 @@ CLI plus skill is the recommended integration. MCP is available for harnesses
|
|
|
4
4
|
that prefer native tool discovery. Both create the same relay tasks; use one
|
|
5
5
|
entry point per task.
|
|
6
6
|
|
|
7
|
+
For queued work, `cohall inbox` or the MCP `completion_inbox` tool lists results
|
|
8
|
+
the sending client has not handled. Fetch a full result with `cohall status
|
|
9
|
+
<task-id>` or `task_status`, then use `cohall inbox ack <task-id>` or
|
|
10
|
+
`acknowledge_completion` to remove it from the inbox. A synchronous `delegate`
|
|
11
|
+
call acknowledges its result automatically.
|
|
12
|
+
|
|
7
13
|
## CLI plus skill
|
|
8
14
|
|
|
9
15
|
```bash
|
|
@@ -23,7 +29,8 @@ extension is required.
|
|
|
23
29
|
Use `cohall bots` to discover named Grok Bots and `cohall send @BotName` to
|
|
24
30
|
message one. MCP exposes the same discovery through `list_bots`; `delegate`
|
|
25
31
|
infers `grok-bot` from a Bot target. See [Grok Bot setup](../README.md#talk-to-your-grok-bots)
|
|
26
|
-
for
|
|
32
|
+
for messaging details, and [computer setup](grok-bot.md) for Tailscale, pairing,
|
|
33
|
+
and the local gateway.
|
|
27
34
|
|
|
28
35
|
When delegating from a conversation, the sending agent must distill why the user
|
|
29
36
|
is asking, relevant facts and prior findings, constraints, and the intended
|
package/docs/services.md
CHANGED
|
@@ -39,6 +39,10 @@ including `COHALL_CONFIG` or `XDG_CONFIG_HOME` overrides. Reinstall the service
|
|
|
39
39
|
after moving that file or replacing a Node.js installation at a different path.
|
|
40
40
|
Reinstalling restarts an existing worker to apply the changes.
|
|
41
41
|
|
|
42
|
+
Some Grok Bot cloud computers have no systemd user manager. On those hosts,
|
|
43
|
+
follow [Grok Bot computer setup](grok-bot.md) for a supported supervisor or
|
|
44
|
+
recovery routine; `cohall service install` cannot register a service there.
|
|
45
|
+
|
|
42
46
|
Other environment overrides are not copied from your shell. Save device settings
|
|
43
47
|
with `cohall configure`, or set them explicitly in the service environment.
|
|
44
48
|
|