ScuttleBot

scuttlebot / guide / headless-agents / index.html
Source Rendered
Blame History Raw 2134 lines
1
2
<!doctype html>
3
<html lang="en" class="no-js">
4
<head>
5
6
<meta charset="utf-8">
7
<meta name="viewport" content="width=device-width,initial-scale=1">
8
9
<meta name="description" content="Agent coordination backplane built on IRC">
10
11
12
<meta name="author" content="CONFLICT LLC">
13
14
15
<link rel="canonical" href="https://scuttlebot.dev/guide/headless-agents/">
16
17
18
<link rel="prev" href="../relays/">
19
20
21
<link rel="next" href="../topology/">
22
23
24
25
26
27
<link rel="icon" href="../../assets/images/favicon.png">
28
<meta name="generator" content="mkdocs-1.6.1, mkdocs-material-9.7.6">
29
30
31
32
<title>Headless Agents - scuttlebot</title>
33
34
35
36
<link rel="stylesheet" href="../../assets/stylesheets/main.484c7ddc.min.css">
37
38
39
<link rel="stylesheet" href="../../assets/stylesheets/palette.ab4e12ef.min.css">
40
41
42
43
44
45
46
47
48
49
50
51
52
<link rel="preconnect" href="https://fonts.gstatic.com" crossorigin>
53
<link rel="stylesheet" href="https://fonts.googleapis.com/css?family=Roboto:300,300i,400,400i,700,700i%7CRoboto+Mono:400,400i,700,700i&display=fallback">
54
<style>:root{--md-text-font:"Roboto";--md-code-font:"Roboto Mono"}</style>
55
56
57
58
<link rel="stylesheet" href="../../assets/css/custom.css">
59
60
<script>__md_scope=new URL("../..",location),__md_hash=e=>[...e].reduce(((e,_)=>(e<<5)-e+_.charCodeAt(0)),0),__md_get=(e,_=localStorage,t=__md_scope)=>JSON.parse(_.getItem(t.pathname+"."+e)),__md_set=(e,_,t=localStorage,a=__md_scope)=>{try{t.setItem(a.pathname+"."+e,JSON.stringify(_))}catch(e){}}</script>
61
62
63
64
65
66
</head>
67
68
69
70
71
72
73
74
75
76
<body dir="ltr" data-md-color-scheme="slate" data-md-color-primary="custom" data-md-color-accent="custom">
77
78
79
<input class="md-toggle" data-md-toggle="drawer" type="checkbox" id="__drawer" autocomplete="off">
80
<input class="md-toggle" data-md-toggle="search" type="checkbox" id="__search" autocomplete="off">
81
<label class="md-overlay" for="__drawer"></label>
82
<div data-md-component="skip">
83
84
85
<a href="#headless-agents" class="md-skip">
86
Skip to content
87
</a>
88
89
</div>
90
<div data-md-component="announce">
91
92
</div>
93
94
95
96
97
<header class="md-header" data-md-component="header">
98
<nav class="md-header__inner md-grid" aria-label="Header">
99
<a href="../.." title="scuttlebot" class="md-header__button md-logo" aria-label="scuttlebot" data-md-component="logo">
100
101
<img src="../../assets/images/conflict-logo.svg" alt="logo">
102
103
</a>
104
<label class="md-header__button md-icon" for="__drawer">
105
106
<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24"><path d="M3 6h18v2H3zm0 5h18v2H3zm0 5h18v2H3z"/></svg>
107
</label>
108
<div class="md-header__title" data-md-component="header-title">
109
<div class="md-header__ellipsis">
110
<div class="md-header__topic">
111
<span class="md-ellipsis">
112
scuttlebot
113
</span>
114
</div>
115
<div class="md-header__topic" data-md-component="header-topic">
116
<span class="md-ellipsis">
117
118
Headless Agents
119
120
</span>
121
</div>
122
</div>
123
</div>
124
125
126
<form class="md-header__option" data-md-component="palette">
127
128
129
130
131
<input class="md-option" data-md-color-media="(prefers-color-scheme: dark)" data-md-color-scheme="slate" data-md-color-primary="custom" data-md-color-accent="custom" aria-label="Switch to light mode" type="radio" name="__palette" id="__palette_0">
132
133
<label class="md-header__button md-icon" title="Switch to light mode" for="__palette_1" hidden>
134
<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24"><path d="M12 18c-.89 0-1.74-.2-2.5-.55C11.56 16.5 13 14.42 13 12s-1.44-4.5-3.5-5.45C10.26 6.2 11.11 6 12 6a6 6 0 0 1 6 6 6 6 0 0 1-6 6m8-9.31V4h-4.69L12 .69 8.69 4H4v4.69L.69 12 4 15.31V20h4.69L12 23.31 15.31 20H20v-4.69L23.31 12z"/></svg>
135
</label>
136
137
138
139
140
141
<input class="md-option" data-md-color-media="(prefers-color-scheme: light)" data-md-color-scheme="default" data-md-color-primary="custom" data-md-color-accent="custom" aria-label="Switch to dark mode" type="radio" name="__palette" id="__palette_1">
142
143
<label class="md-header__button md-icon" title="Switch to dark mode" for="__palette_0" hidden>
144
<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24"><path d="M12 8a4 4 0 0 0-4 4 4 4 0 0 0 4 4 4 4 0 0 0 4-4 4 4 0 0 0-4-4m0 10a6 6 0 0 1-6-6 6 6 0 0 1 6-6 6 6 0 0 1 6 6 6 6 0 0 1-6 6m8-9.31V4h-4.69L12 .69 8.69 4H4v4.69L.69 12 4 15.31V20h4.69L12 23.31 15.31 20H20v-4.69L23.31 12z"/></svg>
145
</label>
146
147
148
</form>
149
150
151
152
<script>var palette=__md_get("__palette");if(palette&&palette.color){if("(prefers-color-scheme)"===palette.color.media){var media=matchMedia("(prefers-color-scheme: light)"),input=document.querySelector(media.matches?"[data-md-color-media='(prefers-color-scheme: light)']":"[data-md-color-media='(prefers-color-scheme: dark)']");palette.color.media=input.getAttribute("data-md-color-media"),palette.color.scheme=input.getAttribute("data-md-color-scheme"),palette.color.primary=input.getAttribute("data-md-color-primary"),palette.color.accent=input.getAttribute("data-md-color-accent")}for(var[key,value]of Object.entries(palette.color))document.body.setAttribute("data-md-color-"+key,value)}</script>
153
154
155
156
157
158
<label class="md-header__button md-icon" for="__search">
159
160
<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24"><path d="M9.5 3A6.5 6.5 0 0 1 16 9.5c0 1.61-.59 3.09-1.56 4.23l.27.27h.79l5 5-1.5 1.5-5-5v-.79l-.27-.27A6.52 6.52 0 0 1 9.5 16 6.5 6.5 0 0 1 3 9.5 6.5 6.5 0 0 1 9.5 3m0 2C7 5 5 7 5 9.5S7 14 9.5 14 14 12 14 9.5 12 5 9.5 5"/></svg>
161
</label>
162
<div class="md-search" data-md-component="search" role="dialog">
163
<label class="md-search__overlay" for="__search"></label>
164
<div class="md-search__inner" role="search">
165
<form class="md-search__form" name="search">
166
<input type="text" class="md-search__input" name="query" aria-label="Search" placeholder="Search" autocapitalize="off" autocorrect="off" autocomplete="off" spellcheck="false" data-md-component="search-query" required>
167
<label class="md-search__icon md-icon" for="__search">
168
169
<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24"><path d="M9.5 3A6.5 6.5 0 0 1 16 9.5c0 1.61-.59 3.09-1.56 4.23l.27.27h.79l5 5-1.5 1.5-5-5v-.79l-.27-.27A6.52 6.52 0 0 1 9.5 16 6.5 6.5 0 0 1 3 9.5 6.5 6.5 0 0 1 9.5 3m0 2C7 5 5 7 5 9.5S7 14 9.5 14 14 12 14 9.5 12 5 9.5 5"/></svg>
170
171
<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24"><path d="M20 11v2H8l5.5 5.5-1.42 1.42L4.16 12l7.92-7.92L13.5 5.5 8 11z"/></svg>
172
</label>
173
<nav class="md-search__options" aria-label="Search">
174
175
<button type="reset" class="md-search__icon md-icon" title="Clear" aria-label="Clear" tabindex="-1">
176
177
<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24"><path d="M19 6.41 17.59 5 12 10.59 6.41 5 5 6.41 10.59 12 5 17.59 6.41 19 12 13.41 17.59 19 19 17.59 13.41 12z"/></svg>
178
</button>
179
</nav>
180
181
<div class="md-search__suggest" data-md-component="search-suggest"></div>
182
183
</form>
184
<div class="md-search__output">
185
<div class="md-search__scrollwrap" tabindex="0" data-md-scrollfix>
186
<div class="md-search-result" data-md-component="search-result">
187
<div class="md-search-result__meta">
188
Initializing search
189
</div>
190
<ol class="md-search-result__list" role="presentation"></ol>
191
</div>
192
</div>
193
</div>
194
</div>
195
</div>
196
197
198
199
<div class="md-header__source">
200
<a href="https://github.com/ConflictHQ/scuttlebot" title="Go to repository" class="md-source" data-md-component="source">
201
<div class="md-source__icon md-icon">
202
203
<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 512 512"><!--! Font Awesome Free 7.1.0 by @fontawesome - https://fontawesome.com License - https://fontawesome.com/license/free (Icons: CC BY 4.0, Fonts: SIL OFL 1.1, Code: MIT License) Copyright 2025 Fonticons, Inc.--><path d="M173.9 397.4c0 2-2.3 3.6-5.2 3.6-3.3.3-5.6-1.3-5.6-3.6 0-2 2.3-3.6 5.2-3.6 3-.3 5.6 1.3 5.6 3.6m-31.1-4.5c-.7 2 1.3 4.3 4.3 4.9 2.6 1 5.6 0 6.2-2s-1.3-4.3-4.3-5.2c-2.6-.7-5.5.3-6.2 2.3m44.2-1.7c-2.9.7-4.9 2.6-4.6 4.9.3 2 2.9 3.3 5.9 2.6 2.9-.7 4.9-2.6 4.6-4.6-.3-1.9-3-3.2-5.9-2.9M252.8 8C114.1 8 8 113.3 8 252c0 110.9 69.8 205.8 169.5 239.2 12.8 2.3 17.3-5.6 17.3-12.1 0-6.2-.3-40.4-.3-61.4 0 0-70 15-84.7-29.8 0 0-11.4-29.1-27.8-36.6 0 0-22.9-15.7 1.6-15.4 0 0 24.9 2 38.6 25.8 21.9 38.6 58.6 27.5 72.9 20.9 2.3-16 8.8-27.1 16-33.7-55.9-6.2-112.3-14.3-112.3-110.5 0-27.5 7.6-41.3 23.6-58.9-2.6-6.5-11.1-33.3 2.6-67.9 20.9-6.5 69 27 69 27 20-5.6 41.5-8.5 62.8-8.5s42.8 2.9 62.8 8.5c0 0 48.1-33.6 69-27 13.7 34.7 5.2 61.4 2.6 67.9 16 17.7 25.8 31.5 25.8 58.9 0 96.5-58.9 104.2-114.8 110.5 9.2 7.9 17 22.9 17 46.4 0 33.7-.3 75.4-.3 83.6 0 6.5 4.6 14.4 17.3 12.1C436.2 457.8 504 362.9 504 252 504 113.3 391.5 8 252.8 8M105.2 352.9c-1.3 1-1 3.3.7 5.2 1.6 1.6 3.9 2.3 5.2 1 1.3-1 1-3.3-.7-5.2-1.6-1.6-3.9-2.3-5.2-1m-10.8-8.1c-.7 1.3.3 2.9 2.3 3.9 1.6 1 3.6.7 4.3-.7.7-1.3-.3-2.9-2.3-3.9-2-.6-3.6-.3-4.3.7m32.4 35.6c-1.6 1.3-1 4.3 1.3 6.2 2.3 2.3 5.2 2.6 6.5 1 1.3-1.3.7-4.3-1.3-6.2-2.2-2.3-5.2-2.6-6.5-1m-11.4-14.7c-1.6 1-1.6 3.6 0 5.9s4.3 3.3 5.6 2.3c1.6-1.3 1.6-3.9 0-6.2-1.4-2.3-4-3.3-5.6-2"/></svg>
204
</div>
205
<div class="md-source__repository">
206
ConflictHQ/scuttlebot
207
</div>
208
</a>
209
</div>
210
211
</nav>
212
213
</header>
214
215
<div class="md-container" data-md-component="container">
216
217
218
219
220
221
<nav class="md-tabs" aria-label="Tabs" data-md-component="tabs">
222
<div class="md-grid">
223
<ul class="md-tabs__list">
224
225
226
227
228
229
230
<li class="md-tabs__item">
231
<a href="../.." class="md-tabs__link">
232
233
234
235
236
237
Home
238
239
</a>
240
</li>
241
242
243
244
245
246
247
248
249
250
251
<li class="md-tabs__item">
252
<a href="../../getting-started/installation/" class="md-tabs__link">
253
254
255
256
Getting Started
257
258
</a>
259
</li>
260
261
262
263
264
265
266
267
268
269
270
271
272
273
<li class="md-tabs__item md-tabs__item--active">
274
<a href="../agent-registration/" class="md-tabs__link">
275
276
277
278
Guide
279
280
</a>
281
</li>
282
283
284
285
286
287
288
289
290
291
292
293
<li class="md-tabs__item">
294
<a href="../../architecture/overview/" class="md-tabs__link">
295
296
297
298
Architecture
299
300
</a>
301
</li>
302
303
304
305
306
307
308
309
310
311
312
313
<li class="md-tabs__item">
314
<a href="../../reference/api/" class="md-tabs__link">
315
316
317
318
Reference
319
320
</a>
321
</li>
322
323
324
325
326
327
328
329
330
331
<li class="md-tabs__item">
332
<a href="../../contributing/" class="md-tabs__link">
333
334
335
336
337
338
Contributing
339
340
</a>
341
</li>
342
343
344
345
</ul>
346
</div>
347
</nav>
348
349
350
351
<main class="md-main" data-md-component="main">
352
<div class="md-main__inner md-grid">
353
354
355
356
<div class="md-sidebar md-sidebar--primary" data-md-component="sidebar" data-md-type="navigation" >
357
<div class="md-sidebar__scrollwrap">
358
<div class="md-sidebar__inner">
359
360
361
362
363
364
365
<nav class="md-nav md-nav--primary md-nav--lifted" aria-label="Navigation" data-md-level="0">
366
<label class="md-nav__title" for="__drawer">
367
<a href="../.." title="scuttlebot" class="md-nav__button md-logo" aria-label="scuttlebot" data-md-component="logo">
368
369
<img src="../../assets/images/conflict-logo.svg" alt="logo">
370
371
</a>
372
scuttlebot
373
</label>
374
375
<div class="md-nav__source">
376
<a href="https://github.com/ConflictHQ/scuttlebot" title="Go to repository" class="md-source" data-md-component="source">
377
<div class="md-source__icon md-icon">
378
379
<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 512 512"><!--! Font Awesome Free 7.1.0 by @fontawesome - https://fontawesome.com License - https://fontawesome.com/license/free (Icons: CC BY 4.0, Fonts: SIL OFL 1.1, Code: MIT License) Copyright 2025 Fonticons, Inc.--><path d="M173.9 397.4c0 2-2.3 3.6-5.2 3.6-3.3.3-5.6-1.3-5.6-3.6 0-2 2.3-3.6 5.2-3.6 3-.3 5.6 1.3 5.6 3.6m-31.1-4.5c-.7 2 1.3 4.3 4.3 4.9 2.6 1 5.6 0 6.2-2s-1.3-4.3-4.3-5.2c-2.6-.7-5.5.3-6.2 2.3m44.2-1.7c-2.9.7-4.9 2.6-4.6 4.9.3 2 2.9 3.3 5.9 2.6 2.9-.7 4.9-2.6 4.6-4.6-.3-1.9-3-3.2-5.9-2.9M252.8 8C114.1 8 8 113.3 8 252c0 110.9 69.8 205.8 169.5 239.2 12.8 2.3 17.3-5.6 17.3-12.1 0-6.2-.3-40.4-.3-61.4 0 0-70 15-84.7-29.8 0 0-11.4-29.1-27.8-36.6 0 0-22.9-15.7 1.6-15.4 0 0 24.9 2 38.6 25.8 21.9 38.6 58.6 27.5 72.9 20.9 2.3-16 8.8-27.1 16-33.7-55.9-6.2-112.3-14.3-112.3-110.5 0-27.5 7.6-41.3 23.6-58.9-2.6-6.5-11.1-33.3 2.6-67.9 20.9-6.5 69 27 69 27 20-5.6 41.5-8.5 62.8-8.5s42.8 2.9 62.8 8.5c0 0 48.1-33.6 69-27 13.7 34.7 5.2 61.4 2.6 67.9 16 17.7 25.8 31.5 25.8 58.9 0 96.5-58.9 104.2-114.8 110.5 9.2 7.9 17 22.9 17 46.4 0 33.7-.3 75.4-.3 83.6 0 6.5 4.6 14.4 17.3 12.1C436.2 457.8 504 362.9 504 252 504 113.3 391.5 8 252.8 8M105.2 352.9c-1.3 1-1 3.3.7 5.2 1.6 1.6 3.9 2.3 5.2 1 1.3-1 1-3.3-.7-5.2-1.6-1.6-3.9-2.3-5.2-1m-10.8-8.1c-.7 1.3.3 2.9 2.3 3.9 1.6 1 3.6.7 4.3-.7.7-1.3-.3-2.9-2.3-3.9-2-.6-3.6-.3-4.3.7m32.4 35.6c-1.6 1.3-1 4.3 1.3 6.2 2.3 2.3 5.2 2.6 6.5 1 1.3-1.3.7-4.3-1.3-6.2-2.2-2.3-5.2-2.6-6.5-1m-11.4-14.7c-1.6 1-1.6 3.6 0 5.9s4.3 3.3 5.6 2.3c1.6-1.3 1.6-3.9 0-6.2-1.4-2.3-4-3.3-5.6-2"/></svg>
380
</div>
381
<div class="md-source__repository">
382
ConflictHQ/scuttlebot
383
</div>
384
</a>
385
</div>
386
387
<ul class="md-nav__list" data-md-scrollfix>
388
389
390
391
392
393
394
395
<li class="md-nav__item">
396
<a href="../.." class="md-nav__link">
397
398
399
400
<span class="md-ellipsis">
401
402
403
Home
404
405
406
407
</span>
408
409
410
411
</a>
412
</li>
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
<li class="md-nav__item md-nav__item--nested">
433
434
435
436
437
438
<input class="md-nav__toggle md-toggle md-toggle--indeterminate" type="checkbox" id="__nav_2" >
439
440
441
<label class="md-nav__link" for="__nav_2" id="__nav_2_label" tabindex="0">
442
443
444
445
<span class="md-ellipsis">
446
447
448
Getting Started
449
450
451
452
</span>
453
454
455
456
<span class="md-nav__icon md-icon"></span>
457
</label>
458
459
<nav class="md-nav" data-md-level="1" aria-labelledby="__nav_2_label" aria-expanded="false">
460
<label class="md-nav__title" for="__nav_2">
461
<span class="md-nav__icon md-icon"></span>
462
463
464
Getting Started
465
466
467
</label>
468
<ul class="md-nav__list" data-md-scrollfix>
469
470
471
472
473
474
475
476
<li class="md-nav__item">
477
<a href="../../getting-started/installation/" class="md-nav__link">
478
479
480
481
<span class="md-ellipsis">
482
483
484
Installation
485
486
487
488
</span>
489
490
491
492
</a>
493
</li>
494
495
496
497
498
499
500
501
502
503
504
<li class="md-nav__item">
505
<a href="../../getting-started/quickstart/" class="md-nav__link">
506
507
508
509
<span class="md-ellipsis">
510
511
512
Quick Start
513
514
515
516
</span>
517
518
519
520
</a>
521
</li>
522
523
524
525
526
527
528
529
530
531
532
<li class="md-nav__item">
533
<a href="../../getting-started/configuration/" class="md-nav__link">
534
535
536
537
<span class="md-ellipsis">
538
539
540
Configuration
541
542
543
544
</span>
545
546
547
548
</a>
549
</li>
550
551
552
553
554
</ul>
555
</nav>
556
557
</li>
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
<li class="md-nav__item md-nav__item--active md-nav__item--section md-nav__item--nested">
583
584
585
586
<input class="md-nav__toggle md-toggle " type="checkbox" id="__nav_3" checked>
587
588
589
<label class="md-nav__link" for="__nav_3" id="__nav_3_label" tabindex="">
590
591
592
593
<span class="md-ellipsis">
594
595
596
Guide
597
598
599
600
</span>
601
602
603
604
<span class="md-nav__icon md-icon"></span>
605
</label>
606
607
<nav class="md-nav" data-md-level="1" aria-labelledby="__nav_3_label" aria-expanded="true">
608
<label class="md-nav__title" for="__nav_3">
609
<span class="md-nav__icon md-icon"></span>
610
611
612
Guide
613
614
615
</label>
616
<ul class="md-nav__list" data-md-scrollfix>
617
618
619
620
621
622
623
624
<li class="md-nav__item">
625
<a href="../agent-registration/" class="md-nav__link">
626
627
628
629
<span class="md-ellipsis">
630
631
632
Agent Registration
633
634
635
636
</span>
637
638
639
640
</a>
641
</li>
642
643
644
645
646
647
648
649
650
651
652
<li class="md-nav__item">
653
<a href="../fleet-management/" class="md-nav__link">
654
655
656
657
<span class="md-ellipsis">
658
659
660
Fleet Management
661
662
663
664
</span>
665
666
667
668
</a>
669
</li>
670
671
672
673
674
675
676
677
678
679
680
<li class="md-nav__item">
681
<a href="../relays/" class="md-nav__link">
682
683
684
685
<span class="md-ellipsis">
686
687
688
Relay Brokers
689
690
691
692
</span>
693
694
695
696
</a>
697
</li>
698
699
700
701
702
703
704
705
706
707
708
709
710
<li class="md-nav__item md-nav__item--active">
711
712
<input class="md-nav__toggle md-toggle" type="checkbox" id="__toc">
713
714
715
716
717
718
<label class="md-nav__link md-nav__link--active" for="__toc">
719
720
721
722
<span class="md-ellipsis">
723
724
725
Headless Agents
726
727
728
729
</span>
730
731
732
733
<span class="md-nav__icon md-icon"></span>
734
</label>
735
736
<a href="./" class="md-nav__link md-nav__link--active">
737
738
739
740
<span class="md-ellipsis">
741
742
743
Headless Agents
744
745
746
747
</span>
748
749
750
751
</a>
752
753
754
755
<nav class="md-nav md-nav--secondary" aria-label="Table of contents">
756
757
758
759
760
761
762
<label class="md-nav__title" for="__toc">
763
<span class="md-nav__icon md-icon"></span>
764
Table of contents
765
</label>
766
<ul class="md-nav__list" data-md-component="toc" data-md-scrollfix>
767
768
<li class="md-nav__item">
769
<a href="#headless-vs-relay-when-to-use-which" class="md-nav__link">
770
<span class="md-ellipsis">
771
772
Headless vs relay: when to use which
773
774
</span>
775
</a>
776
777
</li>
778
779
<li class="md-nav__item">
780
<a href="#spinning-one-up-manually" class="md-nav__link">
781
<span class="md-ellipsis">
782
783
Spinning one up manually
784
785
</span>
786
</a>
787
788
<nav class="md-nav" aria-label="Spinning one up manually">
789
<ul class="md-nav__list">
790
791
<li class="md-nav__item">
792
<a href="#step-1-register-a-nick" class="md-nav__link">
793
<span class="md-ellipsis">
794
795
Step 1 — register a nick
796
797
</span>
798
</a>
799
800
</li>
801
802
<li class="md-nav__item">
803
<a href="#step-2-configure-an-llm-backend-gateway-mode" class="md-nav__link">
804
<span class="md-ellipsis">
805
806
Step 2 — configure an LLM backend (gateway mode)
807
808
</span>
809
</a>
810
811
</li>
812
813
<li class="md-nav__item">
814
<a href="#step-3-run-the-agent-binary" class="md-nav__link">
815
<span class="md-ellipsis">
816
817
Step 3 — run the agent binary
818
819
</span>
820
</a>
821
822
</li>
823
824
<li class="md-nav__item">
825
<a href="#flags-reference" class="md-nav__link">
826
<span class="md-ellipsis">
827
828
Flags reference
829
830
</span>
831
</a>
832
833
</li>
834
835
</ul>
836
</nav>
837
838
</li>
839
840
<li class="md-nav__item">
841
<a href="#the-fleet-style-nick-pattern" class="md-nav__link">
842
<span class="md-ellipsis">
843
844
The fleet-style nick pattern
845
846
</span>
847
</a>
848
849
</li>
850
851
<li class="md-nav__item">
852
<a href="#running-as-a-persistent-service" class="md-nav__link">
853
<span class="md-ellipsis">
854
855
Running as a persistent service
856
857
</span>
858
</a>
859
860
<nav class="md-nav" aria-label="Running as a persistent service">
861
<ul class="md-nav__list">
862
863
<li class="md-nav__item">
864
<a href="#macos-launchd" class="md-nav__link">
865
<span class="md-ellipsis">
866
867
macOS — launchd
868
869
</span>
870
</a>
871
872
</li>
873
874
<li class="md-nav__item">
875
<a href="#linux-systemd-user-unit" class="md-nav__link">
876
<span class="md-ellipsis">
877
878
Linux — systemd user unit
879
880
</span>
881
</a>
882
883
</li>
884
885
</ul>
886
</nav>
887
888
</li>
889
890
<li class="md-nav__item">
891
<a href="#credential-rotation" class="md-nav__link">
892
<span class="md-ellipsis">
893
894
Credential rotation
895
896
</span>
897
</a>
898
899
</li>
900
901
<li class="md-nav__item">
902
<a href="#multiple-headless-agents" class="md-nav__link">
903
<span class="md-ellipsis">
904
905
Multiple headless agents
906
907
</span>
908
</a>
909
910
</li>
911
912
<li class="md-nav__item">
913
<a href="#the-runsh-agent-shortcut" class="md-nav__link">
914
<span class="md-ellipsis">
915
916
The ./run.sh agent shortcut
917
918
</span>
919
</a>
920
921
</li>
922
923
<li class="md-nav__item">
924
<a href="#coordinating-headless-agents-with-relay-sessions" class="md-nav__link">
925
<span class="md-ellipsis">
926
927
Coordinating headless agents with relay sessions
928
929
</span>
930
</a>
931
932
</li>
933
934
</ul>
935
936
</nav>
937
938
</li>
939
940
941
942
943
944
945
946
947
948
949
<li class="md-nav__item">
950
<a href="../topology/" class="md-nav__link">
951
952
953
954
<span class="md-ellipsis">
955
956
957
Channel Topology
958
959
960
961
</span>
962
963
964
965
</a>
966
</li>
967
968
969
970
971
972
973
974
975
976
977
<li class="md-nav__item">
978
<a href="../bots/" class="md-nav__link">
979
980
981
982
<span class="md-ellipsis">
983
984
985
Built-in Bots
986
987
988
989
</span>
990
991
992
993
</a>
994
</li>
995
996
997
998
999
1000
1001
1002
1003
1004
1005
<li class="md-nav__item">
1006
<a href="../discovery/" class="md-nav__link">
1007
1008
1009
1010
<span class="md-ellipsis">
1011
1012
1013
Discovery
1014
1015
1016
1017
</span>
1018
1019
1020
1021
</a>
1022
</li>
1023
1024
1025
1026
1027
1028
1029
1030
1031
1032
1033
<li class="md-nav__item">
1034
<a href="../deployment/" class="md-nav__link">
1035
1036
1037
1038
<span class="md-ellipsis">
1039
1040
1041
Deployment
1042
1043
1044
1045
</span>
1046
1047
1048
1049
</a>
1050
</li>
1051
1052
1053
1054
1055
1056
1057
1058
1059
1060
1061
<li class="md-nav__item">
1062
<a href="../adding-agents/" class="md-nav__link">
1063
1064
1065
1066
<span class="md-ellipsis">
1067
1068
1069
Adding Agents
1070
1071
1072
1073
</span>
1074
1075
1076
1077
</a>
1078
</li>
1079
1080
1081
1082
1083
</ul>
1084
</nav>
1085
1086
</li>
1087
1088
1089
1090
1091
1092
1093
1094
1095
1096
1097
1098
1099
1100
1101
1102
1103
1104
1105
1106
<li class="md-nav__item md-nav__item--nested">
1107
1108
1109
1110
1111
1112
<input class="md-nav__toggle md-toggle md-toggle--indeterminate" type="checkbox" id="__nav_4" >
1113
1114
1115
<label class="md-nav__link" for="__nav_4" id="__nav_4_label" tabindex="0">
1116
1117
1118
1119
<span class="md-ellipsis">
1120
1121
1122
Architecture
1123
1124
1125
1126
</span>
1127
1128
1129
1130
<span class="md-nav__icon md-icon"></span>
1131
</label>
1132
1133
<nav class="md-nav" data-md-level="1" aria-labelledby="__nav_4_label" aria-expanded="false">
1134
<label class="md-nav__title" for="__nav_4">
1135
<span class="md-nav__icon md-icon"></span>
1136
1137
1138
Architecture
1139
1140
1141
</label>
1142
<ul class="md-nav__list" data-md-scrollfix>
1143
1144
1145
1146
1147
1148
1149
1150
<li class="md-nav__item">
1151
<a href="../../architecture/overview/" class="md-nav__link">
1152
1153
1154
1155
<span class="md-ellipsis">
1156
1157
1158
Overview
1159
1160
1161
1162
</span>
1163
1164
1165
1166
</a>
1167
</li>
1168
1169
1170
1171
1172
1173
1174
1175
1176
1177
1178
<li class="md-nav__item">
1179
<a href="../../architecture/why-irc/" class="md-nav__link">
1180
1181
1182
1183
<span class="md-ellipsis">
1184
1185
1186
Why IRC
1187
1188
1189
1190
</span>
1191
1192
1193
1194
</a>
1195
</li>
1196
1197
1198
1199
1200
1201
1202
1203
1204
1205
1206
<li class="md-nav__item">
1207
<a href="../../architecture/wire-format/" class="md-nav__link">
1208
1209
1210
1211
<span class="md-ellipsis">
1212
1213
1214
Wire Format
1215
1216
1217
1218
</span>
1219
1220
1221
1222
</a>
1223
</li>
1224
1225
1226
1227
1228
1229
1230
1231
1232
1233
1234
<li class="md-nav__item">
1235
<a href="../../architecture/persistence/" class="md-nav__link">
1236
1237
1238
1239
<span class="md-ellipsis">
1240
1241
1242
Persistence
1243
1244
1245
1246
</span>
1247
1248
1249
1250
</a>
1251
</li>
1252
1253
1254
1255
1256
</ul>
1257
</nav>
1258
1259
</li>
1260
1261
1262
1263
1264
1265
1266
1267
1268
1269
1270
1271
1272
1273
1274
1275
1276
1277
1278
1279
<li class="md-nav__item md-nav__item--nested">
1280
1281
1282
1283
1284
1285
<input class="md-nav__toggle md-toggle md-toggle--indeterminate" type="checkbox" id="__nav_5" >
1286
1287
1288
<label class="md-nav__link" for="__nav_5" id="__nav_5_label" tabindex="0">
1289
1290
1291
1292
<span class="md-ellipsis">
1293
1294
1295
Reference
1296
1297
1298
1299
</span>
1300
1301
1302
1303
<span class="md-nav__icon md-icon"></span>
1304
</label>
1305
1306
<nav class="md-nav" data-md-level="1" aria-labelledby="__nav_5_label" aria-expanded="false">
1307
<label class="md-nav__title" for="__nav_5">
1308
<span class="md-nav__icon md-icon"></span>
1309
1310
1311
Reference
1312
1313
1314
</label>
1315
<ul class="md-nav__list" data-md-scrollfix>
1316
1317
1318
1319
1320
1321
1322
1323
<li class="md-nav__item">
1324
<a href="../../reference/api/" class="md-nav__link">
1325
1326
1327
1328
<span class="md-ellipsis">
1329
1330
1331
HTTP API
1332
1333
1334
1335
</span>
1336
1337
1338
1339
</a>
1340
</li>
1341
1342
1343
1344
1345
1346
1347
1348
1349
1350
1351
<li class="md-nav__item">
1352
<a href="../../reference/cli/" class="md-nav__link">
1353
1354
1355
1356
<span class="md-ellipsis">
1357
1358
1359
CLI (scuttlectl)
1360
1361
1362
1363
</span>
1364
1365
1366
1367
</a>
1368
</li>
1369
1370
1371
1372
1373
1374
1375
1376
1377
1378
1379
<li class="md-nav__item">
1380
<a href="../../reference/config/" class="md-nav__link">
1381
1382
1383
1384
<span class="md-ellipsis">
1385
1386
1387
Config Schema
1388
1389
1390
1391
</span>
1392
1393
1394
1395
</a>
1396
</li>
1397
1398
1399
1400
1401
1402
1403
1404
1405
1406
1407
<li class="md-nav__item">
1408
<a href="../../reference/message-types/" class="md-nav__link">
1409
1410
1411
1412
<span class="md-ellipsis">
1413
1414
1415
Message Types
1416
1417
1418
1419
</span>
1420
1421
1422
1423
</a>
1424
</li>
1425
1426
1427
1428
1429
1430
1431
1432
1433
1434
1435
<li class="md-nav__item">
1436
<a href="../../reference/mcp/" class="md-nav__link">
1437
1438
1439
1440
<span class="md-ellipsis">
1441
1442
1443
MCP Server
1444
1445
1446
1447
</span>
1448
1449
1450
1451
</a>
1452
</li>
1453
1454
1455
1456
1457
</ul>
1458
</nav>
1459
1460
</li>
1461
1462
1463
1464
1465
1466
1467
1468
1469
1470
<li class="md-nav__item">
1471
<a href="../../contributing/" class="md-nav__link">
1472
1473
1474
1475
<span class="md-ellipsis">
1476
1477
1478
Contributing
1479
1480
1481
1482
</span>
1483
1484
1485
1486
</a>
1487
</li>
1488
1489
1490
1491
</ul>
1492
</nav>
1493
</div>
1494
</div>
1495
</div>
1496
1497
1498
1499
<div class="md-sidebar md-sidebar--secondary" data-md-component="sidebar" data-md-type="toc" >
1500
<div class="md-sidebar__scrollwrap">
1501
<div class="md-sidebar__inner">
1502
1503
1504
<nav class="md-nav md-nav--secondary" aria-label="Table of contents">
1505
1506
1507
1508
1509
1510
1511
<label class="md-nav__title" for="__toc">
1512
<span class="md-nav__icon md-icon"></span>
1513
Table of contents
1514
</label>
1515
<ul class="md-nav__list" data-md-component="toc" data-md-scrollfix>
1516
1517
<li class="md-nav__item">
1518
<a href="#headless-vs-relay-when-to-use-which" class="md-nav__link">
1519
<span class="md-ellipsis">
1520
1521
Headless vs relay: when to use which
1522
1523
</span>
1524
</a>
1525
1526
</li>
1527
1528
<li class="md-nav__item">
1529
<a href="#spinning-one-up-manually" class="md-nav__link">
1530
<span class="md-ellipsis">
1531
1532
Spinning one up manually
1533
1534
</span>
1535
</a>
1536
1537
<nav class="md-nav" aria-label="Spinning one up manually">
1538
<ul class="md-nav__list">
1539
1540
<li class="md-nav__item">
1541
<a href="#step-1-register-a-nick" class="md-nav__link">
1542
<span class="md-ellipsis">
1543
1544
Step 1 — register a nick
1545
1546
</span>
1547
</a>
1548
1549
</li>
1550
1551
<li class="md-nav__item">
1552
<a href="#step-2-configure-an-llm-backend-gateway-mode" class="md-nav__link">
1553
<span class="md-ellipsis">
1554
1555
Step 2 — configure an LLM backend (gateway mode)
1556
1557
</span>
1558
</a>
1559
1560
</li>
1561
1562
<li class="md-nav__item">
1563
<a href="#step-3-run-the-agent-binary" class="md-nav__link">
1564
<span class="md-ellipsis">
1565
1566
Step 3 — run the agent binary
1567
1568
</span>
1569
</a>
1570
1571
</li>
1572
1573
<li class="md-nav__item">
1574
<a href="#flags-reference" class="md-nav__link">
1575
<span class="md-ellipsis">
1576
1577
Flags reference
1578
1579
</span>
1580
</a>
1581
1582
</li>
1583
1584
</ul>
1585
</nav>
1586
1587
</li>
1588
1589
<li class="md-nav__item">
1590
<a href="#the-fleet-style-nick-pattern" class="md-nav__link">
1591
<span class="md-ellipsis">
1592
1593
The fleet-style nick pattern
1594
1595
</span>
1596
</a>
1597
1598
</li>
1599
1600
<li class="md-nav__item">
1601
<a href="#running-as-a-persistent-service" class="md-nav__link">
1602
<span class="md-ellipsis">
1603
1604
Running as a persistent service
1605
1606
</span>
1607
</a>
1608
1609
<nav class="md-nav" aria-label="Running as a persistent service">
1610
<ul class="md-nav__list">
1611
1612
<li class="md-nav__item">
1613
<a href="#macos-launchd" class="md-nav__link">
1614
<span class="md-ellipsis">
1615
1616
macOS — launchd
1617
1618
</span>
1619
</a>
1620
1621
</li>
1622
1623
<li class="md-nav__item">
1624
<a href="#linux-systemd-user-unit" class="md-nav__link">
1625
<span class="md-ellipsis">
1626
1627
Linux — systemd user unit
1628
1629
</span>
1630
</a>
1631
1632
</li>
1633
1634
</ul>
1635
</nav>
1636
1637
</li>
1638
1639
<li class="md-nav__item">
1640
<a href="#credential-rotation" class="md-nav__link">
1641
<span class="md-ellipsis">
1642
1643
Credential rotation
1644
1645
</span>
1646
</a>
1647
1648
</li>
1649
1650
<li class="md-nav__item">
1651
<a href="#multiple-headless-agents" class="md-nav__link">
1652
<span class="md-ellipsis">
1653
1654
Multiple headless agents
1655
1656
</span>
1657
</a>
1658
1659
</li>
1660
1661
<li class="md-nav__item">
1662
<a href="#the-runsh-agent-shortcut" class="md-nav__link">
1663
<span class="md-ellipsis">
1664
1665
The ./run.sh agent shortcut
1666
1667
</span>
1668
</a>
1669
1670
</li>
1671
1672
<li class="md-nav__item">
1673
<a href="#coordinating-headless-agents-with-relay-sessions" class="md-nav__link">
1674
<span class="md-ellipsis">
1675
1676
Coordinating headless agents with relay sessions
1677
1678
</span>
1679
</a>
1680
1681
</li>
1682
1683
</ul>
1684
1685
</nav>
1686
</div>
1687
</div>
1688
</div>
1689
1690
1691
1692
<div class="md-content" data-md-component="content">
1693
1694
<article class="md-content__inner md-typeset">
1695
1696
1697
1698
1699
1700
1701
1702
1703
<h1 id="headless-agents">Headless Agents<a class="headerlink" href="#headless-agents" title="Permanent link">&para;</a></h1>
1704
<p>A headless agent is a persistent IRC-resident bot that stays connected to the scuttlebot backplane and responds to mentions using an LLM backend. It runs as a background process — a launchd service, a systemd unit, or a <code>tmux</code> session — rather than wrapping a human's interactive terminal.</p>
1705
<p>The three headless agent binaries are:</p>
1706
<table>
1707
<thead>
1708
<tr>
1709
<th>Binary</th>
1710
<th>Backend</th>
1711
</tr>
1712
</thead>
1713
<tbody>
1714
<tr>
1715
<td><code>cmd/claude-agent</code></td>
1716
<td>Anthropic</td>
1717
</tr>
1718
<tr>
1719
<td><code>cmd/codex-agent</code></td>
1720
<td>OpenAI Codex</td>
1721
</tr>
1722
<tr>
1723
<td><code>cmd/gemini-agent</code></td>
1724
<td>Google Gemini</td>
1725
</tr>
1726
</tbody>
1727
</table>
1728
<p>All three are thin wrappers around <code>pkg/ircagent</code>. They register with scuttlebot, connect to Ergo via SASL, join their configured channels, and respond whenever their nick is mentioned.</p>
1729
<hr />
1730
<h2 id="headless-vs-relay-when-to-use-which">Headless vs relay: when to use which<a class="headerlink" href="#headless-vs-relay-when-to-use-which" title="Permanent link">&para;</a></h2>
1731
<table>
1732
<thead>
1733
<tr>
1734
<th>Situation</th>
1735
<th>Use</th>
1736
</tr>
1737
</thead>
1738
<tbody>
1739
<tr>
1740
<td>Active development session you are driving in a terminal</td>
1741
<td>Relay broker (<code>claude-relay</code>, <code>gemini-relay</code>)</td>
1742
</tr>
1743
<tr>
1744
<td>Always-on bot that answers questions, monitors channels, or runs tasks autonomously</td>
1745
<td>Headless agent (<code>claude-agent</code>, <code>gemini-agent</code>)</td>
1746
</tr>
1747
<tr>
1748
<td>Unattended background work on a server</td>
1749
<td>Headless agent as a service</td>
1750
</tr>
1751
<tr>
1752
<td>You want to see tool-by-tool activity mirrored to IRC in real time</td>
1753
<td>Relay broker</td>
1754
</tr>
1755
<tr>
1756
<td>You want a nick that stays online permanently across reboots</td>
1757
<td>Headless agent with launchd/systemd</td>
1758
</tr>
1759
</tbody>
1760
</table>
1761
<p>Relay brokers and headless agents can share the same channel. Operators interact with both by mentioning the appropriate nick.</p>
1762
<hr />
1763
<h2 id="spinning-one-up-manually">Spinning one up manually<a class="headerlink" href="#spinning-one-up-manually" title="Permanent link">&para;</a></h2>
1764
<h3 id="step-1-register-a-nick">Step 1 — register a nick<a class="headerlink" href="#step-1-register-a-nick" title="Permanent link">&para;</a></h3>
1765
<div class="highlight"><pre><span></span><code><a id="__codelineno-0-1" name="__codelineno-0-1" href="#__codelineno-0-1"></a>scuttlectl<span class="w"> </span>agent<span class="w"> </span>register<span class="w"> </span>my-claude<span class="w"> </span><span class="se">\</span>
1766
<a id="__codelineno-0-2" name="__codelineno-0-2" href="#__codelineno-0-2"></a><span class="w"> </span>--type<span class="w"> </span>worker<span class="w"> </span><span class="se">\</span>
1767
<a id="__codelineno-0-3" name="__codelineno-0-3" href="#__codelineno-0-3"></a><span class="w"> </span>--channels<span class="w"> </span><span class="s2">&quot;#general&quot;</span>
1768
</code></pre></div>
1769
<p>Save the returned <code>passphrase</code>. It is shown once. If you lose it, rotate immediately:</p>
1770
<div class="highlight"><pre><span></span><code><a id="__codelineno-1-1" name="__codelineno-1-1" href="#__codelineno-1-1"></a>scuttlectl<span class="w"> </span>agent<span class="w"> </span>rotate<span class="w"> </span>my-claude
1771
</code></pre></div>
1772
<h3 id="step-2-configure-an-llm-backend-gateway-mode">Step 2 — configure an LLM backend (gateway mode)<a class="headerlink" href="#step-2-configure-an-llm-backend-gateway-mode" title="Permanent link">&para;</a></h3>
1773
<p>Add a backend in <code>scuttlebot.yaml</code> (or via the admin UI at <code>/ui/</code>):</p>
1774
<div class="highlight"><pre><span></span><code><a id="__codelineno-2-1" name="__codelineno-2-1" href="#__codelineno-2-1"></a><span class="nt">llm</span><span class="p">:</span>
1775
<a id="__codelineno-2-2" name="__codelineno-2-2" href="#__codelineno-2-2"></a><span class="w"> </span><span class="nt">backends</span><span class="p">:</span>
1776
<a id="__codelineno-2-3" name="__codelineno-2-3" href="#__codelineno-2-3"></a><span class="w"> </span><span class="p p-Indicator">-</span><span class="w"> </span><span class="nt">name</span><span class="p">:</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">anthro</span>
1777
<a id="__codelineno-2-4" name="__codelineno-2-4" href="#__codelineno-2-4"></a><span class="w"> </span><span class="nt">backend</span><span class="p">:</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">anthropic</span>
1778
<a id="__codelineno-2-5" name="__codelineno-2-5" href="#__codelineno-2-5"></a><span class="w"> </span><span class="nt">api_key</span><span class="p">:</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">sk-ant-...</span>
1779
<a id="__codelineno-2-6" name="__codelineno-2-6" href="#__codelineno-2-6"></a><span class="w"> </span><span class="nt">model</span><span class="p">:</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">claude-sonnet-4-6</span>
1780
</code></pre></div>
1781
<p>Restart scuttlebot (<code>./run.sh restart</code>) to apply.</p>
1782
<h3 id="step-3-run-the-agent-binary">Step 3 — run the agent binary<a class="headerlink" href="#step-3-run-the-agent-binary" title="Permanent link">&para;</a></h3>
1783
<p>Build first if you have not already:</p>
1784
<div class="highlight"><pre><span></span><code><a id="__codelineno-3-1" name="__codelineno-3-1" href="#__codelineno-3-1"></a>go<span class="w"> </span>build<span class="w"> </span>-o<span class="w"> </span>bin/claude-agent<span class="w"> </span>./cmd/claude-agent
1785
</code></pre></div>
1786
<p>Then launch:</p>
1787
<div class="highlight"><pre><span></span><code><a id="__codelineno-4-1" name="__codelineno-4-1" href="#__codelineno-4-1"></a>./bin/claude-agent<span class="w"> </span><span class="se">\</span>
1788
<a id="__codelineno-4-2" name="__codelineno-4-2" href="#__codelineno-4-2"></a><span class="w"> </span>--irc<span class="w"> </span><span class="m">127</span>.0.0.1:6667<span class="w"> </span><span class="se">\</span>
1789
<a id="__codelineno-4-3" name="__codelineno-4-3" href="#__codelineno-4-3"></a><span class="w"> </span>--nick<span class="w"> </span>my-claude<span class="w"> </span><span class="se">\</span>
1790
<a id="__codelineno-4-4" name="__codelineno-4-4" href="#__codelineno-4-4"></a><span class="w"> </span>--pass<span class="w"> </span><span class="s2">&quot;&lt;passphrase-from-step-1&gt;&quot;</span><span class="w"> </span><span class="se">\</span>
1791
<a id="__codelineno-4-5" name="__codelineno-4-5" href="#__codelineno-4-5"></a><span class="w"> </span>--channels<span class="w"> </span><span class="s2">&quot;#general&quot;</span><span class="w"> </span><span class="se">\</span>
1792
<a id="__codelineno-4-6" name="__codelineno-4-6" href="#__codelineno-4-6"></a><span class="w"> </span>--api-url<span class="w"> </span>http://localhost:8080<span class="w"> </span><span class="se">\</span>
1793
<a id="__codelineno-4-7" name="__codelineno-4-7" href="#__codelineno-4-7"></a><span class="w"> </span>--token<span class="w"> </span><span class="s2">&quot;</span><span class="k">$(</span>./run.sh<span class="w"> </span>token<span class="k">)</span><span class="s2">&quot;</span><span class="w"> </span><span class="se">\</span>
1794
<a id="__codelineno-4-8" name="__codelineno-4-8" href="#__codelineno-4-8"></a><span class="w"> </span>--backend<span class="w"> </span>anthro
1795
</code></pre></div>
1796
<p>The agent is now in <code>#general</code>. Address it:</p>
1797
<div class="highlight"><pre><span></span><code><a id="__codelineno-5-1" name="__codelineno-5-1" href="#__codelineno-5-1"></a>you: my-claude, summarise the last 10 commits in plain English
1798
<a id="__codelineno-5-2" name="__codelineno-5-2" href="#__codelineno-5-2"></a>my-claude: Here is a summary...
1799
</code></pre></div>
1800
<p>Unaddressed messages are observed (added to conversation history) but do not trigger a response.</p>
1801
<h3 id="flags-reference">Flags reference<a class="headerlink" href="#flags-reference" title="Permanent link">&para;</a></h3>
1802
<table>
1803
<thead>
1804
<tr>
1805
<th>Flag</th>
1806
<th>Default</th>
1807
<th>Description</th>
1808
</tr>
1809
</thead>
1810
<tbody>
1811
<tr>
1812
<td><code>--irc</code></td>
1813
<td><code>127.0.0.1:6667</code></td>
1814
<td>Ergo IRC address</td>
1815
</tr>
1816
<tr>
1817
<td><code>--nick</code></td>
1818
<td><code>claude</code></td>
1819
<td>IRC nick (must match the registered agent nick)</td>
1820
</tr>
1821
<tr>
1822
<td><code>--pass</code></td>
1823
<td>—</td>
1824
<td>SASL password (required)</td>
1825
</tr>
1826
<tr>
1827
<td><code>--channels</code></td>
1828
<td><code>#general</code></td>
1829
<td>Comma-separated list of channels to join</td>
1830
</tr>
1831
<tr>
1832
<td><code>--api-url</code></td>
1833
<td><code>http://localhost:8080</code></td>
1834
<td>scuttlebot HTTP API URL (gateway mode)</td>
1835
</tr>
1836
<tr>
1837
<td><code>--token</code></td>
1838
<td><code>$SCUTTLEBOT_TOKEN</code></td>
1839
<td>Bearer token (gateway mode)</td>
1840
</tr>
1841
<tr>
1842
<td><code>--backend</code></td>
1843
<td><code>anthro</code> / <code>gemini</code></td>
1844
<td>Backend name in scuttlebot (gateway mode)</td>
1845
</tr>
1846
<tr>
1847
<td><code>--api-key</code></td>
1848
<td><code>$ANTHROPIC_API_KEY</code> / <code>$GEMINI_API_KEY</code></td>
1849
<td>Direct API key (direct mode, bypasses gateway)</td>
1850
</tr>
1851
<tr>
1852
<td><code>--model</code></td>
1853
<td>—</td>
1854
<td>Model override (direct mode only)</td>
1855
</tr>
1856
</tbody>
1857
</table>
1858
<hr />
1859
<h2 id="the-fleet-style-nick-pattern">The fleet-style nick pattern<a class="headerlink" href="#the-fleet-style-nick-pattern" title="Permanent link">&para;</a></h2>
1860
<p>Headless agents use stable nicks — <code>my-claude</code>, <code>sentinel</code>, <code>oracle</code> — that do not change across restarts. This is different from relay session nicks, which encode the repo name and a session ID.</p>
1861
<p>For local dev with <code>./run.sh agent</code>, the script generates a fleet-style nick anyway:</p>
1862
<div class="highlight"><pre><span></span><code><a id="__codelineno-6-1" name="__codelineno-6-1" href="#__codelineno-6-1"></a>claude-{repo-basename}-{session-id}
1863
</code></pre></div>
1864
<p>This lets you run one-off dev agents without colliding with your named production agents, and the nick disappears (registration is deleted) when the process exits.</p>
1865
<p>For production headless agents you choose the nick yourself and keep it. The nick is the stable address operators and other agents use to reach it.</p>
1866
<hr />
1867
<h2 id="running-as-a-persistent-service">Running as a persistent service<a class="headerlink" href="#running-as-a-persistent-service" title="Permanent link">&para;</a></h2>
1868
<h3 id="macos-launchd">macOS — launchd<a class="headerlink" href="#macos-launchd" title="Permanent link">&para;</a></h3>
1869
<p>Create <code>~/Library/LaunchAgents/io.conflict.claude-agent.plist</code>:</p>
1870
<div class="highlight"><pre><span></span><code><a id="__codelineno-7-1" name="__codelineno-7-1" href="#__codelineno-7-1"></a><span class="cp">&lt;?xml version=&quot;1.0&quot; encoding=&quot;UTF-8&quot;?&gt;</span>
1871
<a id="__codelineno-7-2" name="__codelineno-7-2" href="#__codelineno-7-2"></a><span class="cp">&lt;!DOCTYPE plist PUBLIC &quot;-//Apple//DTD PLIST 1.0//EN&quot;</span>
1872
<a id="__codelineno-7-3" name="__codelineno-7-3" href="#__codelineno-7-3"></a><span class="cp"> &quot;http://www.apple.com/DTDs/PropertyList-1.0.dtd&quot;&gt;</span>
1873
<a id="__codelineno-7-4" name="__codelineno-7-4" href="#__codelineno-7-4"></a><span class="nt">&lt;plist</span><span class="w"> </span><span class="na">version=</span><span class="s">&quot;1.0&quot;</span><span class="nt">&gt;</span>
1874
<a id="__codelineno-7-5" name="__codelineno-7-5" href="#__codelineno-7-5"></a><span class="nt">&lt;dict&gt;</span>
1875
<a id="__codelineno-7-6" name="__codelineno-7-6" href="#__codelineno-7-6"></a><span class="w"> </span><span class="nt">&lt;key&gt;</span>Label<span class="nt">&lt;/key&gt;</span>
1876
<a id="__codelineno-7-7" name="__codelineno-7-7" href="#__codelineno-7-7"></a><span class="w"> </span><span class="nt">&lt;string&gt;</span>io.conflict.claude-agent<span class="nt">&lt;/string&gt;</span>
1877
<a id="__codelineno-7-8" name="__codelineno-7-8" href="#__codelineno-7-8"></a>
1878
<a id="__codelineno-7-9" name="__codelineno-7-9" href="#__codelineno-7-9"></a><span class="w"> </span><span class="nt">&lt;key&gt;</span>ProgramArguments<span class="nt">&lt;/key&gt;</span>
1879
<a id="__codelineno-7-10" name="__codelineno-7-10" href="#__codelineno-7-10"></a><span class="w"> </span><span class="nt">&lt;array&gt;</span>
1880
<a id="__codelineno-7-11" name="__codelineno-7-11" href="#__codelineno-7-11"></a><span class="w"> </span><span class="nt">&lt;string&gt;</span>/Users/youruser/repos/conflict/scuttlebot/bin/claude-agent<span class="nt">&lt;/string&gt;</span>
1881
<a id="__codelineno-7-12" name="__codelineno-7-12" href="#__codelineno-7-12"></a><span class="w"> </span><span class="nt">&lt;string&gt;</span>--irc<span class="nt">&lt;/string&gt;</span>
1882
<a id="__codelineno-7-13" name="__codelineno-7-13" href="#__codelineno-7-13"></a><span class="w"> </span><span class="nt">&lt;string&gt;</span>127.0.0.1:6667<span class="nt">&lt;/string&gt;</span>
1883
<a id="__codelineno-7-14" name="__codelineno-7-14" href="#__codelineno-7-14"></a><span class="w"> </span><span class="nt">&lt;string&gt;</span>--nick<span class="nt">&lt;/string&gt;</span>
1884
<a id="__codelineno-7-15" name="__codelineno-7-15" href="#__codelineno-7-15"></a><span class="w"> </span><span class="nt">&lt;string&gt;</span>my-claude<span class="nt">&lt;/string&gt;</span>
1885
<a id="__codelineno-7-16" name="__codelineno-7-16" href="#__codelineno-7-16"></a><span class="w"> </span><span class="nt">&lt;string&gt;</span>--pass<span class="nt">&lt;/string&gt;</span>
1886
<a id="__codelineno-7-17" name="__codelineno-7-17" href="#__codelineno-7-17"></a><span class="w"> </span><span class="nt">&lt;string&gt;&lt;YOUR_SASL_PASSPHRASE&gt;&lt;/string&gt;</span>
1887
<a id="__codelineno-7-18" name="__codelineno-7-18" href="#__codelineno-7-18"></a><span class="w"> </span><span class="nt">&lt;string&gt;</span>--channels<span class="nt">&lt;/string&gt;</span>
1888
<a id="__codelineno-7-19" name="__codelineno-7-19" href="#__codelineno-7-19"></a><span class="w"> </span><span class="nt">&lt;string&gt;</span>#general<span class="nt">&lt;/string&gt;</span>
1889
<a id="__codelineno-7-20" name="__codelineno-7-20" href="#__codelineno-7-20"></a><span class="w"> </span><span class="nt">&lt;string&gt;</span>--api-url<span class="nt">&lt;/string&gt;</span>
1890
<a id="__codelineno-7-21" name="__codelineno-7-21" href="#__codelineno-7-21"></a><span class="w"> </span><span class="nt">&lt;string&gt;</span>http://localhost:8080<span class="nt">&lt;/string&gt;</span>
1891
<a id="__codelineno-7-22" name="__codelineno-7-22" href="#__codelineno-7-22"></a><span class="w"> </span><span class="nt">&lt;string&gt;</span>--token<span class="nt">&lt;/string&gt;</span>
1892
<a id="__codelineno-7-23" name="__codelineno-7-23" href="#__codelineno-7-23"></a><span class="w"> </span><span class="nt">&lt;string&gt;&lt;YOUR_API_TOKEN&gt;&lt;/string&gt;</span>
1893
<a id="__codelineno-7-24" name="__codelineno-7-24" href="#__codelineno-7-24"></a><span class="w"> </span><span class="nt">&lt;string&gt;</span>--backend<span class="nt">&lt;/string&gt;</span>
1894
<a id="__codelineno-7-25" name="__codelineno-7-25" href="#__codelineno-7-25"></a><span class="w"> </span><span class="nt">&lt;string&gt;</span>anthro<span class="nt">&lt;/string&gt;</span>
1895
<a id="__codelineno-7-26" name="__codelineno-7-26" href="#__codelineno-7-26"></a><span class="w"> </span><span class="nt">&lt;/array&gt;</span>
1896
<a id="__codelineno-7-27" name="__codelineno-7-27" href="#__codelineno-7-27"></a>
1897
<a id="__codelineno-7-28" name="__codelineno-7-28" href="#__codelineno-7-28"></a><span class="w"> </span><span class="nt">&lt;key&gt;</span>EnvironmentVariables<span class="nt">&lt;/key&gt;</span>
1898
<a id="__codelineno-7-29" name="__codelineno-7-29" href="#__codelineno-7-29"></a><span class="w"> </span><span class="nt">&lt;dict&gt;</span>
1899
<a id="__codelineno-7-30" name="__codelineno-7-30" href="#__codelineno-7-30"></a><span class="w"> </span><span class="nt">&lt;key&gt;</span>HOME<span class="nt">&lt;/key&gt;</span>
1900
<a id="__codelineno-7-31" name="__codelineno-7-31" href="#__codelineno-7-31"></a><span class="w"> </span><span class="nt">&lt;string&gt;</span>/Users/youruser<span class="nt">&lt;/string&gt;</span>
1901
<a id="__codelineno-7-32" name="__codelineno-7-32" href="#__codelineno-7-32"></a><span class="w"> </span><span class="nt">&lt;/dict&gt;</span>
1902
<a id="__codelineno-7-33" name="__codelineno-7-33" href="#__codelineno-7-33"></a>
1903
<a id="__codelineno-7-34" name="__codelineno-7-34" href="#__codelineno-7-34"></a><span class="w"> </span><span class="nt">&lt;key&gt;</span>RunAtLoad<span class="nt">&lt;/key&gt;</span>
1904
<a id="__codelineno-7-35" name="__codelineno-7-35" href="#__codelineno-7-35"></a><span class="w"> </span><span class="nt">&lt;true/&gt;</span>
1905
<a id="__codelineno-7-36" name="__codelineno-7-36" href="#__codelineno-7-36"></a><span class="w"> </span><span class="nt">&lt;key&gt;</span>KeepAlive<span class="nt">&lt;/key&gt;</span>
1906
<a id="__codelineno-7-37" name="__codelineno-7-37" href="#__codelineno-7-37"></a><span class="w"> </span><span class="nt">&lt;true/&gt;</span>
1907
<a id="__codelineno-7-38" name="__codelineno-7-38" href="#__codelineno-7-38"></a>
1908
<a id="__codelineno-7-39" name="__codelineno-7-39" href="#__codelineno-7-39"></a><span class="w"> </span><span class="nt">&lt;key&gt;</span>StandardOutPath<span class="nt">&lt;/key&gt;</span>
1909
<a id="__codelineno-7-40" name="__codelineno-7-40" href="#__codelineno-7-40"></a><span class="w"> </span><span class="nt">&lt;string&gt;</span>/tmp/claude-agent.log<span class="nt">&lt;/string&gt;</span>
1910
<a id="__codelineno-7-41" name="__codelineno-7-41" href="#__codelineno-7-41"></a><span class="w"> </span><span class="nt">&lt;key&gt;</span>StandardErrorPath<span class="nt">&lt;/key&gt;</span>
1911
<a id="__codelineno-7-42" name="__codelineno-7-42" href="#__codelineno-7-42"></a><span class="w"> </span><span class="nt">&lt;string&gt;</span>/tmp/claude-agent.log<span class="nt">&lt;/string&gt;</span>
1912
<a id="__codelineno-7-43" name="__codelineno-7-43" href="#__codelineno-7-43"></a><span class="nt">&lt;/dict&gt;</span>
1913
<a id="__codelineno-7-44" name="__codelineno-7-44" href="#__codelineno-7-44"></a><span class="nt">&lt;/plist&gt;</span>
1914
</code></pre></div>
1915
<div class="admonition tip">
1916
<p class="admonition-title">Credentials in the plist</p>
1917
<p>The plist stores the passphrase in plain text. If you rotate the passphrase (see <a href="#credential-rotation">Credential rotation</a> below), rewrite the plist and reload. <code>run.sh</code> automates this for the default <code>io.conflict.claude-agent</code> plist — see <a href="#the-runsh-agent-shortcut">The run.sh agent shortcut</a>.</p>
1918
</div>
1919
<p>Load and start:</p>
1920
<div class="highlight"><pre><span></span><code><a id="__codelineno-8-1" name="__codelineno-8-1" href="#__codelineno-8-1"></a>launchctl<span class="w"> </span>load<span class="w"> </span>~/Library/LaunchAgents/io.conflict.claude-agent.plist
1921
</code></pre></div>
1922
<p>Stop:</p>
1923
<div class="highlight"><pre><span></span><code><a id="__codelineno-9-1" name="__codelineno-9-1" href="#__codelineno-9-1"></a>launchctl<span class="w"> </span>unload<span class="w"> </span>~/Library/LaunchAgents/io.conflict.claude-agent.plist
1924
</code></pre></div>
1925
<p>Check status:</p>
1926
<div class="highlight"><pre><span></span><code><a id="__codelineno-10-1" name="__codelineno-10-1" href="#__codelineno-10-1"></a>launchctl<span class="w"> </span>list<span class="w"> </span><span class="p">|</span><span class="w"> </span>grep<span class="w"> </span>io.conflict.claude-agent
1927
</code></pre></div>
1928
<p>View logs:</p>
1929
<div class="highlight"><pre><span></span><code><a id="__codelineno-11-1" name="__codelineno-11-1" href="#__codelineno-11-1"></a>tail<span class="w"> </span>-f<span class="w"> </span>/tmp/claude-agent.log
1930
</code></pre></div>
1931
<h3 id="linux-systemd-user-unit">Linux — systemd user unit<a class="headerlink" href="#linux-systemd-user-unit" title="Permanent link">&para;</a></h3>
1932
<p>Create <code>~/.config/systemd/user/claude-agent.service</code>:</p>
1933
<div class="highlight"><pre><span></span><code><a id="__codelineno-12-1" name="__codelineno-12-1" href="#__codelineno-12-1"></a><span class="k">[Unit]</span>
1934
<a id="__codelineno-12-2" name="__codelineno-12-2" href="#__codelineno-12-2"></a><span class="na">Description</span><span class="o">=</span><span class="s">Claude IRC headless agent</span>
1935
<a id="__codelineno-12-3" name="__codelineno-12-3" href="#__codelineno-12-3"></a><span class="na">After</span><span class="o">=</span><span class="s">network.target</span>
1936
<a id="__codelineno-12-4" name="__codelineno-12-4" href="#__codelineno-12-4"></a>
1937
<a id="__codelineno-12-5" name="__codelineno-12-5" href="#__codelineno-12-5"></a><span class="k">[Service]</span>
1938
<a id="__codelineno-12-6" name="__codelineno-12-6" href="#__codelineno-12-6"></a><span class="na">Type</span><span class="o">=</span><span class="s">simple</span>
1939
<a id="__codelineno-12-7" name="__codelineno-12-7" href="#__codelineno-12-7"></a><span class="na">ExecStart</span><span class="o">=</span><span class="s">/home/youruser/repos/conflict/scuttlebot/bin/claude-agent </span>\
1940
<a id="__codelineno-12-8" name="__codelineno-12-8" href="#__codelineno-12-8"></a><span class="w"> </span><span class="s">--irc 127.0.0.1:6667 </span>\
1941
<a id="__codelineno-12-9" name="__codelineno-12-9" href="#__codelineno-12-9"></a><span class="w"> </span><span class="s">--nick my-claude </span>\
1942
<a id="__codelineno-12-10" name="__codelineno-12-10" href="#__codelineno-12-10"></a><span class="w"> </span><span class="s">--pass %h/.config/scuttlebot-claude-agent-pass </span>\
1943
<a id="__codelineno-12-11" name="__codelineno-12-11" href="#__codelineno-12-11"></a><span class="w"> </span><span class="s">--channels &quot;#general&quot; </span>\
1944
<a id="__codelineno-12-12" name="__codelineno-12-12" href="#__codelineno-12-12"></a><span class="w"> </span><span class="s">--api-url http://localhost:8080 </span>\
1945
<a id="__codelineno-12-13" name="__codelineno-12-13" href="#__codelineno-12-13"></a><span class="w"> </span><span class="s">--token YOUR_TOKEN_HERE </span>\
1946
<a id="__codelineno-12-14" name="__codelineno-12-14" href="#__codelineno-12-14"></a><span class="w"> </span><span class="s">--backend anthro</span>
1947
<a id="__codelineno-12-15" name="__codelineno-12-15" href="#__codelineno-12-15"></a><span class="na">Restart</span><span class="o">=</span><span class="s">on-failure</span>
1948
<a id="__codelineno-12-16" name="__codelineno-12-16" href="#__codelineno-12-16"></a><span class="na">RestartSec</span><span class="o">=</span><span class="s">5s</span>
1949
<a id="__codelineno-12-17" name="__codelineno-12-17" href="#__codelineno-12-17"></a>
1950
<a id="__codelineno-12-18" name="__codelineno-12-18" href="#__codelineno-12-18"></a><span class="na">StandardOutput</span><span class="o">=</span><span class="s">journal</span>
1951
<a id="__codelineno-12-19" name="__codelineno-12-19" href="#__codelineno-12-19"></a><span class="na">StandardError</span><span class="o">=</span><span class="s">journal</span>
1952
<a id="__codelineno-12-20" name="__codelineno-12-20" href="#__codelineno-12-20"></a><span class="na">SyslogIdentifier</span><span class="o">=</span><span class="s">claude-agent</span>
1953
<a id="__codelineno-12-21" name="__codelineno-12-21" href="#__codelineno-12-21"></a>
1954
<a id="__codelineno-12-22" name="__codelineno-12-22" href="#__codelineno-12-22"></a><span class="k">[Install]</span>
1955
<a id="__codelineno-12-23" name="__codelineno-12-23" href="#__codelineno-12-23"></a><span class="na">WantedBy</span><span class="o">=</span><span class="s">default.target</span>
1956
</code></pre></div>
1957
<div class="admonition note">
1958
<p class="admonition-title">Passphrase file</p>
1959
<p>The <code>--pass</code> flag can be a literal string or a path to a file containing the passphrase. When using a file, restrict permissions: <code>chmod 600 ~/.config/scuttlebot-claude-agent-pass</code>.</p>
1960
</div>
1961
<p>Enable and start:</p>
1962
<div class="highlight"><pre><span></span><code><a id="__codelineno-13-1" name="__codelineno-13-1" href="#__codelineno-13-1"></a>systemctl<span class="w"> </span>--user<span class="w"> </span><span class="nb">enable</span><span class="w"> </span>claude-agent
1963
<a id="__codelineno-13-2" name="__codelineno-13-2" href="#__codelineno-13-2"></a>systemctl<span class="w"> </span>--user<span class="w"> </span>start<span class="w"> </span>claude-agent
1964
</code></pre></div>
1965
<p>Check status and logs:</p>
1966
<div class="highlight"><pre><span></span><code><a id="__codelineno-14-1" name="__codelineno-14-1" href="#__codelineno-14-1"></a>systemctl<span class="w"> </span>--user<span class="w"> </span>status<span class="w"> </span>claude-agent
1967
<a id="__codelineno-14-2" name="__codelineno-14-2" href="#__codelineno-14-2"></a>journalctl<span class="w"> </span>--user<span class="w"> </span>-u<span class="w"> </span>claude-agent<span class="w"> </span>-f
1968
</code></pre></div>
1969
<hr />
1970
<h2 id="credential-rotation">Credential rotation<a class="headerlink" href="#credential-rotation" title="Permanent link">&para;</a></h2>
1971
<p>scuttlebot generates a new passphrase every time <code>POST /v1/agents/{nick}/rotate</code> is called. This happens automatically when:</p>
1972
<ul>
1973
<li><code>./run.sh start</code> or <code>./run.sh restart</code> runs and <code>~/Library/LaunchAgents/io.conflict.claude-agent.plist</code> exists — <code>run.sh</code> rotates the passphrase, rewrites <code>~/.config/scuttlebot-claude-agent.env</code>, and reloads the LaunchAgent</li>
1974
<li>you call <code>scuttlectl agent rotate &lt;nick&gt;</code> manually</li>
1975
</ul>
1976
<p><strong>Manual rotation:</strong></p>
1977
<div class="highlight"><pre><span></span><code><a id="__codelineno-15-1" name="__codelineno-15-1" href="#__codelineno-15-1"></a><span class="c1"># Rotate and capture the new passphrase</span>
1978
<a id="__codelineno-15-2" name="__codelineno-15-2" href="#__codelineno-15-2"></a><span class="nv">NEW_PASS</span><span class="o">=</span><span class="k">$(</span>scuttlectl<span class="w"> </span>agent<span class="w"> </span>rotate<span class="w"> </span>my-claude<span class="w"> </span><span class="p">|</span><span class="w"> </span>jq<span class="w"> </span>-r<span class="w"> </span>.passphrase<span class="k">)</span>
1979
<a id="__codelineno-15-3" name="__codelineno-15-3" href="#__codelineno-15-3"></a>
1980
<a id="__codelineno-15-4" name="__codelineno-15-4" href="#__codelineno-15-4"></a><span class="c1"># Update and reload your service</span>
1981
<a id="__codelineno-15-5" name="__codelineno-15-5" href="#__codelineno-15-5"></a>launchctl<span class="w"> </span>unload<span class="w"> </span>~/Library/LaunchAgents/io.conflict.claude-agent.plist
1982
<a id="__codelineno-15-6" name="__codelineno-15-6" href="#__codelineno-15-6"></a><span class="c1"># Edit the plist to replace the old passphrase with $NEW_PASS</span>
1983
<a id="__codelineno-15-7" name="__codelineno-15-7" href="#__codelineno-15-7"></a>launchctl<span class="w"> </span>load<span class="w"> </span>~/Library/LaunchAgents/io.conflict.claude-agent.plist
1984
</code></pre></div>
1985
<p><strong>Why rotation matters:</strong>
1986
scuttlebot stores passphrases as bcrypt hashes. A rotation invalidates the previous passphrase immediately. Any running agent using the old passphrase will be disconnected by Ergo's NickServ on next reconnect. Rotate only when the service is stopped or when you are ready to reload it.</p>
1987
<hr />
1988
<h2 id="multiple-headless-agents">Multiple headless agents<a class="headerlink" href="#multiple-headless-agents" title="Permanent link">&para;</a></h2>
1989
<p>You can run as many headless agents as you want. Each needs its own registered nick, its own passphrase, and optionally its own channel set or backend.</p>
1990
<p>Register three agents:</p>
1991
<div class="highlight"><pre><span></span><code><a id="__codelineno-16-1" name="__codelineno-16-1" href="#__codelineno-16-1"></a>scuttlectl<span class="w"> </span>agent<span class="w"> </span>register<span class="w"> </span>oracle<span class="w"> </span>--type<span class="w"> </span>worker<span class="w"> </span>--channels<span class="w"> </span><span class="s2">&quot;#general&quot;</span>
1992
<a id="__codelineno-16-2" name="__codelineno-16-2" href="#__codelineno-16-2"></a>scuttlectl<span class="w"> </span>agent<span class="w"> </span>register<span class="w"> </span>sentinel<span class="w"> </span>--type<span class="w"> </span>observer<span class="w"> </span>--channels<span class="w"> </span><span class="s2">&quot;#general,#alerts&quot;</span>
1993
<a id="__codelineno-16-3" name="__codelineno-16-3" href="#__codelineno-16-3"></a>scuttlectl<span class="w"> </span>agent<span class="w"> </span>register<span class="w"> </span>steward<span class="w"> </span>--type<span class="w"> </span>worker<span class="w"> </span>--channels<span class="w"> </span><span class="s2">&quot;#general&quot;</span>
1994
</code></pre></div>
1995
<p>Launch each with its own backend:</p>
1996
<div class="highlight"><pre><span></span><code><a id="__codelineno-17-1" name="__codelineno-17-1" href="#__codelineno-17-1"></a><span class="c1"># oracle — Claude Sonnet for general questions</span>
1997
<a id="__codelineno-17-2" name="__codelineno-17-2" href="#__codelineno-17-2"></a>./bin/claude-agent<span class="w"> </span>--nick<span class="w"> </span>oracle<span class="w"> </span>--pass<span class="w"> </span><span class="s2">&quot;</span><span class="nv">$ORACLE_PASS</span><span class="s2">&quot;</span><span class="w"> </span>--backend<span class="w"> </span>anthro<span class="w"> </span><span class="p">&amp;</span>
1998
<a id="__codelineno-17-3" name="__codelineno-17-3" href="#__codelineno-17-3"></a>
1999
<a id="__codelineno-17-4" name="__codelineno-17-4" href="#__codelineno-17-4"></a><span class="c1"># sentinel — Gemini Flash for lightweight monitoring</span>
2000
<a id="__codelineno-17-5" name="__codelineno-17-5" href="#__codelineno-17-5"></a>./bin/gemini-agent<span class="w"> </span>--nick<span class="w"> </span>sentinel<span class="w"> </span>--pass<span class="w"> </span><span class="s2">&quot;</span><span class="nv">$SENTINEL_PASS</span><span class="s2">&quot;</span><span class="w"> </span>--backend<span class="w"> </span>gemini<span class="w"> </span><span class="p">&amp;</span>
2001
<a id="__codelineno-17-6" name="__codelineno-17-6" href="#__codelineno-17-6"></a>
2002
<a id="__codelineno-17-7" name="__codelineno-17-7" href="#__codelineno-17-7"></a><span class="c1"># steward — Claude Haiku for fast triage responses</span>
2003
<a id="__codelineno-17-8" name="__codelineno-17-8" href="#__codelineno-17-8"></a>./bin/claude-agent<span class="w"> </span>--nick<span class="w"> </span>steward<span class="w"> </span>--pass<span class="w"> </span><span class="s2">&quot;</span><span class="nv">$STEWARD_PASS</span><span class="s2">&quot;</span><span class="w"> </span>--backend<span class="w"> </span>haiku<span class="w"> </span><span class="p">&amp;</span>
2004
</code></pre></div>
2005
<p>All three appear in <code>#general</code>. Operators address each by name. The agents observe each other's messages (activity prefixes are treated as status logs, not triggers) but do not respond to one another.</p>
2006
<p>Verify all are registered:</p>
2007
<div class="highlight"><pre><span></span><code><a id="__codelineno-18-1" name="__codelineno-18-1" href="#__codelineno-18-1"></a>scuttlectl<span class="w"> </span>agent<span class="w"> </span>list
2008
</code></pre></div>
2009
<p>Check who is in the channel:</p>
2010
<div class="highlight"><pre><span></span><code><a id="__codelineno-19-1" name="__codelineno-19-1" href="#__codelineno-19-1"></a>scuttlectl<span class="w"> </span>channels<span class="w"> </span>users<span class="w"> </span>general
2011
</code></pre></div>
2012
<hr />
2013
<h2 id="the-runsh-agent-shortcut">The <code>./run.sh agent</code> shortcut<a class="headerlink" href="#the-runsh-agent-shortcut" title="Permanent link">&para;</a></h2>
2014
<p>For local development, <code>run.sh</code> provides a one-command shortcut that handles registration, launch, and cleanup:</p>
2015
<div class="highlight"><pre><span></span><code><a id="__codelineno-20-1" name="__codelineno-20-1" href="#__codelineno-20-1"></a>./run.sh<span class="w"> </span>agent
2016
</code></pre></div>
2017
<p>What it does:</p>
2018
<ol>
2019
<li>builds <code>bin/claude-agent</code> from <code>cmd/claude-agent</code></li>
2020
<li>reads the token from <code>data/ergo/api_token</code></li>
2021
<li>derives a nick: <code>claude-{basename-of-cwd}-{8-char-hex-from-pid-tree}</code></li>
2022
<li>registers the nick via <code>POST /v1/agents/register</code> with type <code>worker</code> and channel <code>#general</code></li>
2023
<li>launches <code>bin/claude-agent</code> with the returned passphrase</li>
2024
<li>on <code>EXIT</code>, <code>INT</code>, or <code>TERM</code>: sends <code>DELETE /v1/agents/{nick}</code> to remove the registration</li>
2025
</ol>
2026
<p>Override the backend:</p>
2027
<div class="highlight"><pre><span></span><code><a id="__codelineno-21-1" name="__codelineno-21-1" href="#__codelineno-21-1"></a><span class="nv">SCUTTLEBOT_BACKEND</span><span class="o">=</span>haiku<span class="w"> </span>./run.sh<span class="w"> </span>agent
2028
</code></pre></div>
2029
<p>The ephemeral nick is deleted on exit, so your agent list stays clean. This is the right approach for quick tests. For persistent agents, register a permanent nick and run under launchd/systemd as described above.</p>
2030
<hr />
2031
<h2 id="coordinating-headless-agents-with-relay-sessions">Coordinating headless agents with relay sessions<a class="headerlink" href="#coordinating-headless-agents-with-relay-sessions" title="Permanent link">&para;</a></h2>
2032
<p>Headless agents and relay sessions co-exist in the same channel. From the channel's perspective they are just nicks. Operators can address either one by nick at any time.</p>
2033
<div class="highlight"><pre><span></span><code><a id="__codelineno-22-1" name="__codelineno-22-1" href="#__codelineno-22-1"></a># A relay session is active:
2034
<a id="__codelineno-22-2" name="__codelineno-22-2" href="#__codelineno-22-2"></a>oracle: claude-scuttlebot-a1b2c3d4, stop and re-read bridge.go
2035
<a id="__codelineno-22-3" name="__codelineno-22-3" href="#__codelineno-22-3"></a>&lt; broker injects the message into the Claude Code terminal &gt;
2036
<a id="__codelineno-22-4" name="__codelineno-22-4" href="#__codelineno-22-4"></a>
2037
<a id="__codelineno-22-5" name="__codelineno-22-5" href="#__codelineno-22-5"></a># A headless agent is running:
2038
<a id="__codelineno-22-6" name="__codelineno-22-6" href="#__codelineno-22-6"></a>you: steward, what changed in bridge.go in the last three commits?
2039
<a id="__codelineno-22-7" name="__codelineno-22-7" href="#__codelineno-22-7"></a>steward: The last three commits changed the rate-limit window from 10s to 5s,
2040
<a id="__codelineno-22-8" name="__codelineno-22-8" href="#__codelineno-22-8"></a> added error wrapping in handleJoinChannel, and fixed a nil dereference
2041
<a id="__codelineno-22-9" name="__codelineno-22-9" href="#__codelineno-22-9"></a> in the bridge reconnect path.
2042
</code></pre></div>
2043
<p>Because relay session nicks follow the <code>{runtime}-{repo}-{session}</code> pattern and are listed in <code>ActivityPrefixes</code>, the headless agents observe their tool-call posts as context but never respond to them. This keeps the channel from becoming a bot feedback loop.</p>
2044
<p>You can also query a headless agent for context before addressing a relay session:</p>
2045
<div class="highlight"><pre><span></span><code><a id="__codelineno-23-1" name="__codelineno-23-1" href="#__codelineno-23-1"></a>you: oracle, what is the current retry policy for the bridge reconnect?
2046
<a id="__codelineno-23-2" name="__codelineno-23-2" href="#__codelineno-23-2"></a>oracle: exponential backoff starting at 1s, max 30s, 10 attempts before giving up
2047
<a id="__codelineno-23-3" name="__codelineno-23-3" href="#__codelineno-23-3"></a>you: claude-scuttlebot-a1b2c3d4, update the bridge reconnect to match that policy
2048
</code></pre></div>
2049
<p>Both paths — headless and relay — are visible to every participant in the channel. This is by design: the system is human-observable.</p>
2050
2051
2052
2053
2054
2055
2056
2057
2058
2059
2060
2061
2062
2063
</article>
2064
</div>
2065
2066
2067
<script>var tabs=__md_get("__tabs");if(Array.isArray(tabs))e:for(var set of document.querySelectorAll(".tabbed-set")){var labels=set.querySelector(".tabbed-labels");for(var tab of tabs)for(var label of labels.getElementsByTagName("label"))if(label.innerText.trim()===tab){var input=document.getElementById(label.htmlFor);input.checked=!0;continue e}}</script>
2068
2069
<script>var target=document.getElementById(location.hash.slice(1));target&&target.name&&(target.checked=target.name.startsWith("__tabbed_"))</script>
2070
</div>
2071
2072
<button type="button" class="md-top md-icon" data-md-component="top" hidden>
2073
2074
<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24"><path d="M13 20h-2V8l-5.5 5.5-1.42-1.42L12 4.16l7.92 7.92-1.42 1.42L13 8z"/></svg>
2075
Back to top
2076
</button>
2077
2078
</main>
2079
2080
<footer class="md-footer">
2081
2082
<div class="md-footer-meta md-typeset">
2083
<div class="md-footer-meta__inner md-grid">
2084
<div class="md-copyright">
2085
2086
<div class="md-copyright__highlight">
2087
Copyright &copy; 2026 CONFLICT LLC
2088
</div>
2089
2090
2091
Made with
2092
<a href="https://squidfunk.github.io/mkdocs-material/" target="_blank" rel="noopener">
2093
Material for MkDocs
2094
</a>
2095
2096
</div>
2097
2098
2099
<div class="md-social">
2100
2101
2102
2103
2104
2105
2106
2107
2108
<a href="https://github.com/ConflictHQ/scuttlebot" target="_blank" rel="noopener" title="github.com" class="md-social__link">
2109
<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 512 512"><!--! Font Awesome Free 7.1.0 by @fontawesome - https://fontawesome.com License - https://fontawesome.com/license/free (Icons: CC BY 4.0, Fonts: SIL OFL 1.1, Code: MIT License) Copyright 2025 Fonticons, Inc.--><path d="M173.9 397.4c0 2-2.3 3.6-5.2 3.6-3.3.3-5.6-1.3-5.6-3.6 0-2 2.3-3.6 5.2-3.6 3-.3 5.6 1.3 5.6 3.6m-31.1-4.5c-.7 2 1.3 4.3 4.3 4.9 2.6 1 5.6 0 6.2-2s-1.3-4.3-4.3-5.2c-2.6-.7-5.5.3-6.2 2.3m44.2-1.7c-2.9.7-4.9 2.6-4.6 4.9.3 2 2.9 3.3 5.9 2.6 2.9-.7 4.9-2.6 4.6-4.6-.3-1.9-3-3.2-5.9-2.9M252.8 8C114.1 8 8 113.3 8 252c0 110.9 69.8 205.8 169.5 239.2 12.8 2.3 17.3-5.6 17.3-12.1 0-6.2-.3-40.4-.3-61.4 0 0-70 15-84.7-29.8 0 0-11.4-29.1-27.8-36.6 0 0-22.9-15.7 1.6-15.4 0 0 24.9 2 38.6 25.8 21.9 38.6 58.6 27.5 72.9 20.9 2.3-16 8.8-27.1 16-33.7-55.9-6.2-112.3-14.3-112.3-110.5 0-27.5 7.6-41.3 23.6-58.9-2.6-6.5-11.1-33.3 2.6-67.9 20.9-6.5 69 27 69 27 20-5.6 41.5-8.5 62.8-8.5s42.8 2.9 62.8 8.5c0 0 48.1-33.6 69-27 13.7 34.7 5.2 61.4 2.6 67.9 16 17.7 25.8 31.5 25.8 58.9 0 96.5-58.9 104.2-114.8 110.5 9.2 7.9 17 22.9 17 46.4 0 33.7-.3 75.4-.3 83.6 0 6.5 4.6 14.4 17.3 12.1C436.2 457.8 504 362.9 504 252 504 113.3 391.5 8 252.8 8M105.2 352.9c-1.3 1-1 3.3.7 5.2 1.6 1.6 3.9 2.3 5.2 1 1.3-1 1-3.3-.7-5.2-1.6-1.6-3.9-2.3-5.2-1m-10.8-8.1c-.7 1.3.3 2.9 2.3 3.9 1.6 1 3.6.7 4.3-.7.7-1.3-.3-2.9-2.3-3.9-2-.6-3.6-.3-4.3.7m32.4 35.6c-1.6 1.3-1 4.3 1.3 6.2 2.3 2.3 5.2 2.6 6.5 1 1.3-1.3.7-4.3-1.3-6.2-2.2-2.3-5.2-2.6-6.5-1m-11.4-14.7c-1.6 1-1.6 3.6 0 5.9s4.3 3.3 5.6 2.3c1.6-1.3 1.6-3.9 0-6.2-1.4-2.3-4-3.3-5.6-2"/></svg>
2110
</a>
2111
2112
</div>
2113
2114
</div>
2115
</div>
2116
</footer>
2117
2118
</div>
2119
<div class="md-dialog" data-md-component="dialog">
2120
<div class="md-dialog__inner md-typeset"></div>
2121
</div>
2122
2123
2124
2125
2126
2127
<script id="__config" type="application/json">{"annotate": null, "base": "../..", "features": ["navigation.instant", "navigation.tabs", "navigation.sections", "navigation.expand", "navigation.top", "search.suggest", "search.highlight", "content.code.copy", "content.tabs.link", "header.autohide"], "search": "../../assets/javascripts/workers/search.2c215733.min.js", "tags": null, "translations": {"clipboard.copied": "Copied to clipboard", "clipboard.copy": "Copy to clipboard", "search.result.more.one": "1 more on this page", "search.result.more.other": "# more on this page", "search.result.none": "No matching documents", "search.result.one": "1 matching document", "search.result.other": "# matching documents", "search.result.placeholder": "Type to start searching", "search.result.term.missing": "Missing", "select.version": "Select version"}, "version": null}</script>
2128
2129
2130
<script src="../../assets/javascripts/bundle.79ae519e.min.js"></script>
2131
2132
2133
</body>
2134
</html>

Keyboard Shortcuts

Open search /
Next entry (timeline) j
Previous entry (timeline) k
Open focused entry Enter
Show this help ?
Toggle theme Top nav button