durar-ai 2026.4.4

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.
Files changed (571) hide show
  1. package/CHANGELOG.md +5497 -0
  2. package/LICENSE +21 -0
  3. package/README.md +614 -0
  4. package/assets/avatar-placeholder.svg +19 -0
  5. package/assets/chrome-extension/icons/icon128.png +0 -0
  6. package/assets/chrome-extension/icons/icon16.png +0 -0
  7. package/assets/chrome-extension/icons/icon32.png +0 -0
  8. package/assets/chrome-extension/icons/icon48.png +0 -0
  9. package/assets/dmg-background-small.png +0 -0
  10. package/assets/dmg-background.png +0 -0
  11. package/docs/.i18n/README.md +72 -0
  12. package/docs/.i18n/ar-navigation.json +18 -0
  13. package/docs/.i18n/de-navigation.json +18 -0
  14. package/docs/.i18n/es-navigation.json +18 -0
  15. package/docs/.i18n/fr-navigation.json +18 -0
  16. package/docs/.i18n/glossary.ar.json +5 -0
  17. package/docs/.i18n/glossary.de.json +5 -0
  18. package/docs/.i18n/glossary.es.json +5 -0
  19. package/docs/.i18n/glossary.fr.json +5 -0
  20. package/docs/.i18n/glossary.id.json +5 -0
  21. package/docs/.i18n/glossary.it.json +5 -0
  22. package/docs/.i18n/glossary.ja-JP.json +14 -0
  23. package/docs/.i18n/glossary.ko.json +5 -0
  24. package/docs/.i18n/glossary.pl.json +5 -0
  25. package/docs/.i18n/glossary.pt-BR.json +5 -0
  26. package/docs/.i18n/glossary.tr.json +5 -0
  27. package/docs/.i18n/glossary.zh-CN.json +358 -0
  28. package/docs/.i18n/id-navigation.json +18 -0
  29. package/docs/.i18n/it-navigation.json +18 -0
  30. package/docs/.i18n/ja-navigation.json +18 -0
  31. package/docs/.i18n/ko-navigation.json +18 -0
  32. package/docs/.i18n/pl-navigation.json +18 -0
  33. package/docs/.i18n/pt-BR-navigation.json +18 -0
  34. package/docs/.i18n/tr-navigation.json +18 -0
  35. package/docs/.i18n/zh-Hans-navigation.json +544 -0
  36. package/docs/assets/install-script.svg +1 -0
  37. package/docs/assets/macos-onboarding/01-macos-warning.jpeg +0 -0
  38. package/docs/assets/macos-onboarding/02-local-networks.jpeg +0 -0
  39. package/docs/assets/macos-onboarding/03-security-notice.png +0 -0
  40. package/docs/assets/macos-onboarding/04-choose-gateway.png +0 -0
  41. package/docs/assets/macos-onboarding/05-permissions.png +0 -0
  42. package/docs/assets/openclaw-logo-text-dark.png +0 -0
  43. package/docs/assets/openclaw-logo-text-dark.svg +418 -0
  44. package/docs/assets/openclaw-logo-text.png +0 -0
  45. package/docs/assets/openclaw-logo-text.svg +418 -0
  46. package/docs/assets/pixel-lobster.svg +60 -0
  47. package/docs/assets/showcase/agents-ui.jpg +0 -0
  48. package/docs/assets/showcase/bambu-cli.png +0 -0
  49. package/docs/assets/showcase/codexmonitor.png +0 -0
  50. package/docs/assets/showcase/gohome-grafana.png +0 -0
  51. package/docs/assets/showcase/ios-testflight.jpg +0 -0
  52. package/docs/assets/showcase/oura-health.png +0 -0
  53. package/docs/assets/showcase/padel-cli.svg +11 -0
  54. package/docs/assets/showcase/padel-screenshot.jpg +0 -0
  55. package/docs/assets/showcase/papla-tts.jpg +0 -0
  56. package/docs/assets/showcase/pr-review-telegram.jpg +0 -0
  57. package/docs/assets/showcase/roborock-screenshot.jpg +0 -0
  58. package/docs/assets/showcase/roborock-status.svg +13 -0
  59. package/docs/assets/showcase/roof-camera-sky.jpg +0 -0
  60. package/docs/assets/showcase/snag.png +0 -0
  61. package/docs/assets/showcase/tesco-shop.jpg +0 -0
  62. package/docs/assets/showcase/wienerlinien.png +0 -0
  63. package/docs/assets/showcase/wine-cellar-skill.jpg +0 -0
  64. package/docs/assets/showcase/winix-air-purifier.jpg +0 -0
  65. package/docs/assets/showcase/xuezh-pronunciation.jpeg +0 -0
  66. package/docs/assets/sponsors/blacksmith-light.svg +14 -0
  67. package/docs/assets/sponsors/blacksmith.svg +14 -0
  68. package/docs/assets/sponsors/convex-light.svg +16 -0
  69. package/docs/assets/sponsors/convex.svg +16 -0
  70. package/docs/assets/sponsors/github-light.svg +3 -0
  71. package/docs/assets/sponsors/github.svg +3 -0
  72. package/docs/assets/sponsors/nvidia-dark.svg +9 -0
  73. package/docs/assets/sponsors/nvidia.svg +9 -0
  74. package/docs/assets/sponsors/openai-light.svg +3 -0
  75. package/docs/assets/sponsors/openai.svg +3 -0
  76. package/docs/assets/sponsors/vercel-light.svg +5 -0
  77. package/docs/assets/sponsors/vercel.svg +5 -0
  78. package/docs/auth-credential-semantics.md +80 -0
  79. package/docs/automation/auth-monitoring.md +8 -0
  80. package/docs/automation/clawflow.md +8 -0
  81. package/docs/automation/cron-jobs.md +410 -0
  82. package/docs/automation/cron-vs-heartbeat.md +8 -0
  83. package/docs/automation/gmail-pubsub.md +8 -0
  84. package/docs/automation/hooks.md +303 -0
  85. package/docs/automation/index.md +115 -0
  86. package/docs/automation/poll.md +8 -0
  87. package/docs/automation/standing-orders.md +254 -0
  88. package/docs/automation/taskflow.md +82 -0
  89. package/docs/automation/tasks.md +323 -0
  90. package/docs/automation/troubleshooting.md +8 -0
  91. package/docs/automation/webhook.md +8 -0
  92. package/docs/brave-search.md +103 -0
  93. package/docs/channels/bluebubbles.md +435 -0
  94. package/docs/channels/broadcast-groups.md +442 -0
  95. package/docs/channels/channel-routing.md +139 -0
  96. package/docs/channels/discord.md +1254 -0
  97. package/docs/channels/feishu.md +793 -0
  98. package/docs/channels/googlechat.md +270 -0
  99. package/docs/channels/group-messages.md +84 -0
  100. package/docs/channels/groups.md +410 -0
  101. package/docs/channels/imessage.md +427 -0
  102. package/docs/channels/index.md +50 -0
  103. package/docs/channels/irc.md +252 -0
  104. package/docs/channels/line.md +225 -0
  105. package/docs/channels/location.md +56 -0
  106. package/docs/channels/matrix.md +869 -0
  107. package/docs/channels/mattermost.md +472 -0
  108. package/docs/channels/msteams.md +805 -0
  109. package/docs/channels/nextcloud-talk.md +149 -0
  110. package/docs/channels/nostr.md +252 -0
  111. package/docs/channels/pairing.md +129 -0
  112. package/docs/channels/qqbot.md +193 -0
  113. package/docs/channels/signal.md +337 -0
  114. package/docs/channels/slack.md +681 -0
  115. package/docs/channels/synology-chat.md +185 -0
  116. package/docs/channels/telegram.md +1072 -0
  117. package/docs/channels/tlon.md +290 -0
  118. package/docs/channels/troubleshooting.md +133 -0
  119. package/docs/channels/twitch.md +394 -0
  120. package/docs/channels/whatsapp.md +488 -0
  121. package/docs/channels/zalo.md +254 -0
  122. package/docs/channels/zalouser.md +195 -0
  123. package/docs/ci.md +66 -0
  124. package/docs/cli/acp.md +316 -0
  125. package/docs/cli/agent.md +57 -0
  126. package/docs/cli/agents.md +220 -0
  127. package/docs/cli/approvals.md +136 -0
  128. package/docs/cli/backup.md +84 -0
  129. package/docs/cli/browser.md +233 -0
  130. package/docs/cli/channels.md +131 -0
  131. package/docs/cli/clawbot.md +21 -0
  132. package/docs/cli/completion.md +35 -0
  133. package/docs/cli/config.md +353 -0
  134. package/docs/cli/configure.md +70 -0
  135. package/docs/cli/cron.md +167 -0
  136. package/docs/cli/daemon.md +57 -0
  137. package/docs/cli/dashboard.md +22 -0
  138. package/docs/cli/devices.md +171 -0
  139. package/docs/cli/directory.md +63 -0
  140. package/docs/cli/dns.md +48 -0
  141. package/docs/cli/docs.md +28 -0
  142. package/docs/cli/doctor.md +63 -0
  143. package/docs/cli/flows.md +18 -0
  144. package/docs/cli/gateway.md +307 -0
  145. package/docs/cli/health.md +36 -0
  146. package/docs/cli/hooks.md +337 -0
  147. package/docs/cli/index.md +1836 -0
  148. package/docs/cli/logs.md +59 -0
  149. package/docs/cli/mcp.md +505 -0
  150. package/docs/cli/memory.md +139 -0
  151. package/docs/cli/message.md +300 -0
  152. package/docs/cli/models.md +136 -0
  153. package/docs/cli/node.md +137 -0
  154. package/docs/cli/nodes.md +66 -0
  155. package/docs/cli/onboard.md +171 -0
  156. package/docs/cli/pairing.md +65 -0
  157. package/docs/cli/plugins.md +305 -0
  158. package/docs/cli/qr.md +52 -0
  159. package/docs/cli/reset.md +35 -0
  160. package/docs/cli/sandbox.md +197 -0
  161. package/docs/cli/secrets.md +197 -0
  162. package/docs/cli/security.md +86 -0
  163. package/docs/cli/sessions.md +113 -0
  164. package/docs/cli/setup.md +45 -0
  165. package/docs/cli/skills.md +59 -0
  166. package/docs/cli/status.md +35 -0
  167. package/docs/cli/system.md +71 -0
  168. package/docs/cli/tui.md +30 -0
  169. package/docs/cli/uninstall.md +39 -0
  170. package/docs/cli/update.md +113 -0
  171. package/docs/cli/voicecall.md +34 -0
  172. package/docs/cli/webhooks.md +91 -0
  173. package/docs/concepts/agent-loop.md +168 -0
  174. package/docs/concepts/agent-workspace.md +246 -0
  175. package/docs/concepts/agent.md +129 -0
  176. package/docs/concepts/architecture.md +156 -0
  177. package/docs/concepts/compaction.md +122 -0
  178. package/docs/concepts/context-engine.md +274 -0
  179. package/docs/concepts/context.md +179 -0
  180. package/docs/concepts/delegate-architecture.md +307 -0
  181. package/docs/concepts/dreaming.md +173 -0
  182. package/docs/concepts/features.md +76 -0
  183. package/docs/concepts/markdown-formatting.md +130 -0
  184. package/docs/concepts/memory-builtin.md +105 -0
  185. package/docs/concepts/memory-honcho.md +140 -0
  186. package/docs/concepts/memory-qmd.md +163 -0
  187. package/docs/concepts/memory-search.md +141 -0
  188. package/docs/concepts/memory.md +121 -0
  189. package/docs/concepts/messages.md +161 -0
  190. package/docs/concepts/model-failover.md +349 -0
  191. package/docs/concepts/model-providers.md +799 -0
  192. package/docs/concepts/models.md +255 -0
  193. package/docs/concepts/multi-agent.md +615 -0
  194. package/docs/concepts/oauth.md +225 -0
  195. package/docs/concepts/presence.md +102 -0
  196. package/docs/concepts/queue.md +89 -0
  197. package/docs/concepts/retry.md +69 -0
  198. package/docs/concepts/session-pruning.md +92 -0
  199. package/docs/concepts/session-tool.md +141 -0
  200. package/docs/concepts/session.md +116 -0
  201. package/docs/concepts/soul.md +110 -0
  202. package/docs/concepts/streaming.md +161 -0
  203. package/docs/concepts/system-prompt.md +182 -0
  204. package/docs/concepts/timezone.md +97 -0
  205. package/docs/concepts/typebox.md +307 -0
  206. package/docs/concepts/typing-indicators.md +69 -0
  207. package/docs/concepts/usage-tracking.md +59 -0
  208. package/docs/date-time.md +128 -0
  209. package/docs/debug/node-issue.md +85 -0
  210. package/docs/diagnostics/flags.md +91 -0
  211. package/docs/docs.json +1601 -0
  212. package/docs/gateway/authentication.md +218 -0
  213. package/docs/gateway/background-process.md +131 -0
  214. package/docs/gateway/bonjour.md +179 -0
  215. package/docs/gateway/bridge-protocol.md +89 -0
  216. package/docs/gateway/cli-backends.md +310 -0
  217. package/docs/gateway/configuration-examples.md +631 -0
  218. package/docs/gateway/configuration-reference.md +3618 -0
  219. package/docs/gateway/configuration.md +698 -0
  220. package/docs/gateway/discovery.md +141 -0
  221. package/docs/gateway/doctor.md +494 -0
  222. package/docs/gateway/gateway-lock.md +37 -0
  223. package/docs/gateway/health.md +61 -0
  224. package/docs/gateway/heartbeat.md +443 -0
  225. package/docs/gateway/index.md +367 -0
  226. package/docs/gateway/local-models.md +163 -0
  227. package/docs/gateway/logging.md +113 -0
  228. package/docs/gateway/multiple-gateways.md +120 -0
  229. package/docs/gateway/network-model.md +25 -0
  230. package/docs/gateway/openai-http-api.md +280 -0
  231. package/docs/gateway/openresponses-http-api.md +340 -0
  232. package/docs/gateway/openshell.md +307 -0
  233. package/docs/gateway/pairing.md +138 -0
  234. package/docs/gateway/protocol.md +588 -0
  235. package/docs/gateway/remote-gateway-readme.md +164 -0
  236. package/docs/gateway/remote.md +251 -0
  237. package/docs/gateway/sandbox-vs-tool-policy-vs-elevated.md +141 -0
  238. package/docs/gateway/sandboxing.md +473 -0
  239. package/docs/gateway/secrets-plan-contract.md +116 -0
  240. package/docs/gateway/secrets.md +541 -0
  241. package/docs/gateway/security/index.md +1362 -0
  242. package/docs/gateway/tailscale.md +136 -0
  243. package/docs/gateway/tools-invoke-http-api.md +161 -0
  244. package/docs/gateway/troubleshooting.md +451 -0
  245. package/docs/gateway/trusted-proxy-auth.md +399 -0
  246. package/docs/help/debugging.md +168 -0
  247. package/docs/help/environment.md +165 -0
  248. package/docs/help/faq.md +3244 -0
  249. package/docs/help/index.md +28 -0
  250. package/docs/help/scripts.md +27 -0
  251. package/docs/help/testing.md +640 -0
  252. package/docs/help/troubleshooting.md +372 -0
  253. package/docs/images/configure-model-picker-unsearchable.png +0 -0
  254. package/docs/images/feishu-step2-create-app.png +0 -0
  255. package/docs/images/feishu-step3-credentials.png +0 -0
  256. package/docs/images/feishu-step4-permissions.png +0 -0
  257. package/docs/images/feishu-step5-bot-capability.png +0 -0
  258. package/docs/images/feishu-step6-event-subscription.png +0 -0
  259. package/docs/images/feishu-verification-token.png +0 -0
  260. package/docs/images/groups-flow.svg +52 -0
  261. package/docs/images/mobile-ui-screenshot.png +0 -0
  262. package/docs/index.md +196 -0
  263. package/docs/install/ansible.md +230 -0
  264. package/docs/install/azure.md +311 -0
  265. package/docs/install/bun.md +55 -0
  266. package/docs/install/clawdock.md +106 -0
  267. package/docs/install/development-channels.md +131 -0
  268. package/docs/install/digitalocean.md +129 -0
  269. package/docs/install/docker-vm-runtime.md +142 -0
  270. package/docs/install/docker.md +412 -0
  271. package/docs/install/exe-dev.md +133 -0
  272. package/docs/install/fly.md +504 -0
  273. package/docs/install/gcp.md +412 -0
  274. package/docs/install/hetzner.md +259 -0
  275. package/docs/install/index.md +212 -0
  276. package/docs/install/installer.md +443 -0
  277. package/docs/install/kubernetes.md +192 -0
  278. package/docs/install/macos-vm.md +281 -0
  279. package/docs/install/migrating-matrix.md +349 -0
  280. package/docs/install/migrating.md +112 -0
  281. package/docs/install/nix.md +89 -0
  282. package/docs/install/node.md +144 -0
  283. package/docs/install/northflank.mdx +42 -0
  284. package/docs/install/oracle.md +158 -0
  285. package/docs/install/podman.md +210 -0
  286. package/docs/install/railway.mdx +90 -0
  287. package/docs/install/raspberry-pi.md +159 -0
  288. package/docs/install/render.mdx +165 -0
  289. package/docs/install/uninstall.md +128 -0
  290. package/docs/install/updating.md +142 -0
  291. package/docs/logging.md +389 -0
  292. package/docs/nav-tabs-underline.js +100 -0
  293. package/docs/network.md +69 -0
  294. package/docs/nodes/audio.md +191 -0
  295. package/docs/nodes/camera.md +162 -0
  296. package/docs/nodes/images.md +73 -0
  297. package/docs/nodes/index.md +408 -0
  298. package/docs/nodes/location-command.md +98 -0
  299. package/docs/nodes/media-understanding.md +432 -0
  300. package/docs/nodes/talk.md +92 -0
  301. package/docs/nodes/troubleshooting.md +123 -0
  302. package/docs/nodes/voicewake.md +66 -0
  303. package/docs/perplexity.md +181 -0
  304. package/docs/pi-dev.md +80 -0
  305. package/docs/pi.md +570 -0
  306. package/docs/platforms/android.md +244 -0
  307. package/docs/platforms/digitalocean.md +266 -0
  308. package/docs/platforms/index.md +55 -0
  309. package/docs/platforms/ios.md +223 -0
  310. package/docs/platforms/linux.md +100 -0
  311. package/docs/platforms/mac/bundled-gateway.md +75 -0
  312. package/docs/platforms/mac/canvas.md +125 -0
  313. package/docs/platforms/mac/child-process.md +69 -0
  314. package/docs/platforms/mac/dev-setup.md +107 -0
  315. package/docs/platforms/mac/health.md +34 -0
  316. package/docs/platforms/mac/icon.md +31 -0
  317. package/docs/platforms/mac/logging.md +57 -0
  318. package/docs/platforms/mac/menu-bar.md +81 -0
  319. package/docs/platforms/mac/peekaboo.md +65 -0
  320. package/docs/platforms/mac/permissions.md +50 -0
  321. package/docs/platforms/mac/remote.md +84 -0
  322. package/docs/platforms/mac/signing.md +47 -0
  323. package/docs/platforms/mac/skills.md +40 -0
  324. package/docs/platforms/mac/voice-overlay.md +60 -0
  325. package/docs/platforms/mac/voicewake.md +67 -0
  326. package/docs/platforms/mac/webchat.md +51 -0
  327. package/docs/platforms/mac/xpc.md +61 -0
  328. package/docs/platforms/macos.md +229 -0
  329. package/docs/platforms/oracle.md +305 -0
  330. package/docs/platforms/raspberry-pi.md +420 -0
  331. package/docs/platforms/windows.md +241 -0
  332. package/docs/plugins/agent-tools.md +10 -0
  333. package/docs/plugins/architecture.md +1609 -0
  334. package/docs/plugins/building-extensions.md +10 -0
  335. package/docs/plugins/building-plugins.md +319 -0
  336. package/docs/plugins/bundles.md +292 -0
  337. package/docs/plugins/community.md +149 -0
  338. package/docs/plugins/manifest.md +412 -0
  339. package/docs/plugins/sdk-channel-plugins.md +508 -0
  340. package/docs/plugins/sdk-entrypoints.md +210 -0
  341. package/docs/plugins/sdk-migration.md +359 -0
  342. package/docs/plugins/sdk-overview.md +475 -0
  343. package/docs/plugins/sdk-provider-plugins.md +712 -0
  344. package/docs/plugins/sdk-runtime.md +381 -0
  345. package/docs/plugins/sdk-setup.md +516 -0
  346. package/docs/plugins/sdk-testing.md +263 -0
  347. package/docs/plugins/voice-call.md +466 -0
  348. package/docs/plugins/zalouser.md +78 -0
  349. package/docs/prose.md +134 -0
  350. package/docs/providers/anthropic.md +402 -0
  351. package/docs/providers/bedrock-mantle.md +91 -0
  352. package/docs/providers/bedrock.md +273 -0
  353. package/docs/providers/chutes.md +103 -0
  354. package/docs/providers/claude-max-api-proxy.md +163 -0
  355. package/docs/providers/cloudflare-ai-gateway.md +71 -0
  356. package/docs/providers/deepgram.md +93 -0
  357. package/docs/providers/deepseek.md +53 -0
  358. package/docs/providers/fireworks.md +69 -0
  359. package/docs/providers/github-copilot.md +80 -0
  360. package/docs/providers/glm.md +68 -0
  361. package/docs/providers/google.md +149 -0
  362. package/docs/providers/groq.md +105 -0
  363. package/docs/providers/huggingface.md +193 -0
  364. package/docs/providers/index.md +81 -0
  365. package/docs/providers/kilocode.md +89 -0
  366. package/docs/providers/litellm.md +159 -0
  367. package/docs/providers/minimax.md +281 -0
  368. package/docs/providers/mistral.md +68 -0
  369. package/docs/providers/models.md +56 -0
  370. package/docs/providers/moonshot.md +224 -0
  371. package/docs/providers/nvidia.md +58 -0
  372. package/docs/providers/ollama.md +379 -0
  373. package/docs/providers/openai.md +472 -0
  374. package/docs/providers/opencode-go.md +45 -0
  375. package/docs/providers/opencode.md +68 -0
  376. package/docs/providers/openrouter.md +59 -0
  377. package/docs/providers/perplexity-provider.md +62 -0
  378. package/docs/providers/qianfan.md +90 -0
  379. package/docs/providers/qwen.md +128 -0
  380. package/docs/providers/qwen_modelstudio.md +137 -0
  381. package/docs/providers/sglang.md +115 -0
  382. package/docs/providers/stepfun.md +152 -0
  383. package/docs/providers/synthetic.md +101 -0
  384. package/docs/providers/together.md +70 -0
  385. package/docs/providers/venice.md +282 -0
  386. package/docs/providers/vercel-ai-gateway.md +60 -0
  387. package/docs/providers/vllm.md +103 -0
  388. package/docs/providers/volcengine.md +94 -0
  389. package/docs/providers/xai.md +94 -0
  390. package/docs/providers/xiaomi.md +89 -0
  391. package/docs/providers/zai.md +75 -0
  392. package/docs/reference/AGENTS.default.md +126 -0
  393. package/docs/reference/RELEASING.md +138 -0
  394. package/docs/reference/api-usage-costs.md +198 -0
  395. package/docs/reference/credits.md +30 -0
  396. package/docs/reference/device-models.md +47 -0
  397. package/docs/reference/memory-config.md +421 -0
  398. package/docs/reference/prompt-caching.md +344 -0
  399. package/docs/reference/rpc.md +43 -0
  400. package/docs/reference/secretref-credential-surface.md +148 -0
  401. package/docs/reference/secretref-user-supplied-credentials-matrix.json +607 -0
  402. package/docs/reference/session-management-compaction.md +352 -0
  403. package/docs/reference/templates/AGENTS.dev.md +84 -0
  404. package/docs/reference/templates/AGENTS.md +219 -0
  405. package/docs/reference/templates/BOOT.md +12 -0
  406. package/docs/reference/templates/BOOTSTRAP.md +62 -0
  407. package/docs/reference/templates/CLAUDE.md +1 -0
  408. package/docs/reference/templates/HEARTBEAT.md +14 -0
  409. package/docs/reference/templates/IDENTITY.dev.md +48 -0
  410. package/docs/reference/templates/IDENTITY.md +30 -0
  411. package/docs/reference/templates/SOUL.dev.md +77 -0
  412. package/docs/reference/templates/SOUL.md +45 -0
  413. package/docs/reference/templates/TOOLS.dev.md +25 -0
  414. package/docs/reference/templates/TOOLS.md +47 -0
  415. package/docs/reference/templates/USER.dev.md +19 -0
  416. package/docs/reference/templates/USER.md +24 -0
  417. package/docs/reference/test.md +119 -0
  418. package/docs/reference/token-use.md +197 -0
  419. package/docs/reference/transcript-hygiene.md +151 -0
  420. package/docs/reference/wizard.md +245 -0
  421. package/docs/security/CONTRIBUTING-THREAT-MODEL.md +98 -0
  422. package/docs/security/THREAT-MODEL-ATLAS.md +608 -0
  423. package/docs/security/formal-verification.md +167 -0
  424. package/docs/snippets/plugin-publish/minimal-openclaw.plugin.json +9 -0
  425. package/docs/snippets/plugin-publish/minimal-package.json +16 -0
  426. package/docs/start/bootstrapping.md +41 -0
  427. package/docs/start/docs-directory.md +67 -0
  428. package/docs/start/getting-started.md +148 -0
  429. package/docs/start/hubs.md +199 -0
  430. package/docs/start/lore.md +219 -0
  431. package/docs/start/onboarding-overview.md +69 -0
  432. package/docs/start/onboarding.md +92 -0
  433. package/docs/start/openclaw.md +225 -0
  434. package/docs/start/quickstart.md +22 -0
  435. package/docs/start/setup.md +172 -0
  436. package/docs/start/showcase.md +418 -0
  437. package/docs/start/wizard-cli-automation.md +233 -0
  438. package/docs/start/wizard-cli-reference.md +324 -0
  439. package/docs/start/wizard.md +127 -0
  440. package/docs/style.css +37 -0
  441. package/docs/tools/acp-agents.md +837 -0
  442. package/docs/tools/agent-send.md +100 -0
  443. package/docs/tools/apply-patch.md +52 -0
  444. package/docs/tools/brave-search.md +107 -0
  445. package/docs/tools/browser-linux-troubleshooting.md +145 -0
  446. package/docs/tools/browser-login.md +73 -0
  447. package/docs/tools/browser-wsl2-windows-remote-cdp-troubleshooting.md +221 -0
  448. package/docs/tools/browser.md +890 -0
  449. package/docs/tools/btw.md +142 -0
  450. package/docs/tools/capability-cookbook.md +119 -0
  451. package/docs/tools/clawhub.md +348 -0
  452. package/docs/tools/code-execution.md +90 -0
  453. package/docs/tools/creating-skills.md +119 -0
  454. package/docs/tools/diffs.md +434 -0
  455. package/docs/tools/duckduckgo-search.md +102 -0
  456. package/docs/tools/elevated.md +116 -0
  457. package/docs/tools/exa-search.md +127 -0
  458. package/docs/tools/exec-approvals.md +635 -0
  459. package/docs/tools/exec.md +237 -0
  460. package/docs/tools/firecrawl.md +147 -0
  461. package/docs/tools/gemini-search.md +98 -0
  462. package/docs/tools/grok-search.md +102 -0
  463. package/docs/tools/image-generation.md +139 -0
  464. package/docs/tools/index.md +174 -0
  465. package/docs/tools/kimi-search.md +98 -0
  466. package/docs/tools/llm-task.md +119 -0
  467. package/docs/tools/lobster.md +348 -0
  468. package/docs/tools/loop-detection.md +100 -0
  469. package/docs/tools/minimax-search.md +99 -0
  470. package/docs/tools/multi-agent-sandbox-tools.md +373 -0
  471. package/docs/tools/ollama-search.md +100 -0
  472. package/docs/tools/pdf.md +176 -0
  473. package/docs/tools/perplexity-search.md +185 -0
  474. package/docs/tools/plugin.md +348 -0
  475. package/docs/tools/reactions.md +78 -0
  476. package/docs/tools/searxng-search.md +132 -0
  477. package/docs/tools/skills-config.md +133 -0
  478. package/docs/tools/skills.md +377 -0
  479. package/docs/tools/slash-commands.md +322 -0
  480. package/docs/tools/subagents.md +341 -0
  481. package/docs/tools/tavily.md +129 -0
  482. package/docs/tools/thinking.md +102 -0
  483. package/docs/tools/tts.md +452 -0
  484. package/docs/tools/web-fetch.md +159 -0
  485. package/docs/tools/web.md +417 -0
  486. package/docs/tts.md +452 -0
  487. package/docs/vps.md +115 -0
  488. package/docs/web/control-ui.md +318 -0
  489. package/docs/web/dashboard.md +93 -0
  490. package/docs/web/index.md +126 -0
  491. package/docs/web/tui.md +176 -0
  492. package/docs/web/webchat.md +77 -0
  493. package/docs/whatsapp-openclaw-ai-zh.jpg +0 -0
  494. package/docs/whatsapp-openclaw.jpg +0 -0
  495. package/durar.mjs +180 -0
  496. package/package.json +1259 -0
  497. package/scripts/npm-runner.mjs +111 -0
  498. package/scripts/postinstall-bundled-plugins.mjs +188 -0
  499. package/skills/1password/SKILL.md +70 -0
  500. package/skills/1password/references/cli-examples.md +29 -0
  501. package/skills/1password/references/get-started.md +17 -0
  502. package/skills/apple-notes/SKILL.md +77 -0
  503. package/skills/apple-reminders/SKILL.md +118 -0
  504. package/skills/bear-notes/SKILL.md +107 -0
  505. package/skills/blogwatcher/SKILL.md +69 -0
  506. package/skills/blucli/SKILL.md +47 -0
  507. package/skills/bluebubbles/SKILL.md +131 -0
  508. package/skills/camsnap/SKILL.md +45 -0
  509. package/skills/canvas/SKILL.md +199 -0
  510. package/skills/clawhub/SKILL.md +77 -0
  511. package/skills/coding-agent/SKILL.md +316 -0
  512. package/skills/discord/SKILL.md +197 -0
  513. package/skills/eightctl/SKILL.md +50 -0
  514. package/skills/gemini/SKILL.md +43 -0
  515. package/skills/gh-issues/SKILL.md +885 -0
  516. package/skills/gifgrep/SKILL.md +79 -0
  517. package/skills/github/SKILL.md +163 -0
  518. package/skills/gog/SKILL.md +116 -0
  519. package/skills/goplaces/SKILL.md +52 -0
  520. package/skills/healthcheck/SKILL.md +245 -0
  521. package/skills/himalaya/SKILL.md +257 -0
  522. package/skills/himalaya/references/configuration.md +184 -0
  523. package/skills/himalaya/references/message-composition.md +199 -0
  524. package/skills/imsg/SKILL.md +122 -0
  525. package/skills/mcporter/SKILL.md +61 -0
  526. package/skills/model-usage/SKILL.md +69 -0
  527. package/skills/model-usage/references/codexbar-cli.md +33 -0
  528. package/skills/model-usage/scripts/model_usage.py +320 -0
  529. package/skills/model-usage/scripts/test_model_usage.py +40 -0
  530. package/skills/nano-pdf/SKILL.md +38 -0
  531. package/skills/node-connect/SKILL.md +142 -0
  532. package/skills/notion/SKILL.md +174 -0
  533. package/skills/obsidian/SKILL.md +81 -0
  534. package/skills/openai-whisper/SKILL.md +38 -0
  535. package/skills/openai-whisper-api/SKILL.md +62 -0
  536. package/skills/openai-whisper-api/scripts/transcribe.sh +88 -0
  537. package/skills/openhue/SKILL.md +112 -0
  538. package/skills/oracle/SKILL.md +125 -0
  539. package/skills/ordercli/SKILL.md +78 -0
  540. package/skills/peekaboo/SKILL.md +190 -0
  541. package/skills/sag/SKILL.md +87 -0
  542. package/skills/session-logs/SKILL.md +151 -0
  543. package/skills/sherpa-onnx-tts/SKILL.md +109 -0
  544. package/skills/sherpa-onnx-tts/bin/sherpa-onnx-tts +178 -0
  545. package/skills/skill-creator/SKILL.md +372 -0
  546. package/skills/skill-creator/license.txt +202 -0
  547. package/skills/skill-creator/scripts/init_skill.py +378 -0
  548. package/skills/skill-creator/scripts/package_skill.py +139 -0
  549. package/skills/skill-creator/scripts/quick_validate.py +159 -0
  550. package/skills/skill-creator/scripts/test_package_skill.py +160 -0
  551. package/skills/skill-creator/scripts/test_quick_validate.py +72 -0
  552. package/skills/slack/SKILL.md +144 -0
  553. package/skills/songsee/SKILL.md +49 -0
  554. package/skills/sonoscli/SKILL.md +65 -0
  555. package/skills/spotify-player/SKILL.md +64 -0
  556. package/skills/summarize/SKILL.md +87 -0
  557. package/skills/taskflow/SKILL.md +149 -0
  558. package/skills/taskflow/examples/inbox-triage.lobster +33 -0
  559. package/skills/taskflow/examples/pr-intake.lobster +32 -0
  560. package/skills/taskflow-inbox-triage/SKILL.md +119 -0
  561. package/skills/things-mac/SKILL.md +86 -0
  562. package/skills/tmux/SKILL.md +170 -0
  563. package/skills/tmux/scripts/find-sessions.sh +112 -0
  564. package/skills/tmux/scripts/wait-for-text.sh +83 -0
  565. package/skills/trello/SKILL.md +108 -0
  566. package/skills/video-frames/SKILL.md +46 -0
  567. package/skills/video-frames/scripts/frame.sh +81 -0
  568. package/skills/voice-call/SKILL.md +45 -0
  569. package/skills/wacli/SKILL.md +72 -0
  570. package/skills/weather/SKILL.md +129 -0
  571. package/skills/xurl/SKILL.md +461 -0
@@ -0,0 +1,51 @@
1
+ ---
2
+ summary: "How the mac app embeds the gateway WebChat and how to debug it"
3
+ read_when:
4
+ - Debugging mac WebChat view or loopback port
5
+ title: "WebChat (macOS)"
6
+ ---
7
+
8
+ # WebChat (macOS app)
9
+
10
+ The macOS menu bar app embeds the WebChat UI as a native SwiftUI view. It
11
+ connects to the Gateway and defaults to the **main session** for the selected
12
+ agent (with a session switcher for other sessions).
13
+
14
+ - **Local mode**: connects directly to the local Gateway WebSocket.
15
+ - **Remote mode**: forwards the Gateway control port over SSH and uses that
16
+ tunnel as the data plane.
17
+
18
+ ## Launch & debugging
19
+
20
+ - Manual: Lobster menu → “Open Chat”.
21
+ - Auto‑open for testing:
22
+
23
+ ```bash
24
+ dist/Durar.app/Contents/MacOS/Durar --webchat
25
+ ```
26
+
27
+ - Logs: `./scripts/clawlog.sh` (subsystem `ai.Durar`, category `WebChatSwiftUI`).
28
+
29
+ ## How it is wired
30
+
31
+ - Data plane: Gateway WS methods `chat.history`, `chat.send`, `chat.abort`,
32
+ `chat.inject` and events `chat`, `agent`, `presence`, `tick`, `health`.
33
+ - `chat.history` returns display-normalized transcript rows: inline directive
34
+ tags are stripped from visible text, plain-text tool-call XML payloads
35
+ (including `<tool_call>...</tool_call>`,
36
+ `<function_call>...</function_call>`, `<tool_calls>...</tool_calls>`,
37
+ `<function_calls>...</function_calls>`, and truncated tool-call blocks) and
38
+ leaked ASCII/full-width model control tokens are stripped, pure
39
+ silent-token assistant rows such as exact `NO_REPLY` / `no_reply` are
40
+ omitted, and oversized rows can be replaced with placeholders.
41
+ - Session: defaults to the primary session (`main`, or `global` when scope is
42
+ global). The UI can switch between sessions.
43
+ - Onboarding uses a dedicated session to keep first‑run setup separate.
44
+
45
+ ## Security surface
46
+
47
+ - Remote mode forwards only the Gateway WebSocket control port over SSH.
48
+
49
+ ## Known limitations
50
+
51
+ - The UI is optimized for chat sessions (not a full browser sandbox).
@@ -0,0 +1,61 @@
1
+ ---
2
+ summary: "macOS IPC architecture for Durar app, gateway node transport, and PeekabooBridge"
3
+ read_when:
4
+ - Editing IPC contracts or menu bar app IPC
5
+ title: "macOS IPC"
6
+ ---
7
+
8
+ # Durar macOS IPC architecture
9
+
10
+ **Current model:** a local Unix socket connects the **node host service** to the **macOS app** for exec approvals + `system.run`. A `Durar-mac` debug CLI exists for discovery/connect checks; agent actions still flow through the Gateway WebSocket and `node.invoke`. UI automation uses PeekabooBridge.
11
+
12
+ ## Goals
13
+
14
+ - Single GUI app instance that owns all TCC-facing work (notifications, screen recording, mic, speech, AppleScript).
15
+ - A small surface for automation: Gateway + node commands, plus PeekabooBridge for UI automation.
16
+ - Predictable permissions: always the same signed bundle ID, launched by launchd, so TCC grants stick.
17
+
18
+ ## How it works
19
+
20
+ ### Gateway + node transport
21
+
22
+ - The app runs the Gateway (local mode) and connects to it as a node.
23
+ - Agent actions are performed via `node.invoke` (e.g. `system.run`, `system.notify`, `canvas.*`).
24
+
25
+ ### Node service + app IPC
26
+
27
+ - A headless node host service connects to the Gateway WebSocket.
28
+ - `system.run` requests are forwarded to the macOS app over a local Unix socket.
29
+ - The app performs the exec in UI context, prompts if needed, and returns output.
30
+
31
+ Diagram (SCI):
32
+
33
+ ```
34
+ Agent -> Gateway -> Node Service (WS)
35
+ | IPC (UDS + token + HMAC + TTL)
36
+ v
37
+ Mac App (UI + TCC + system.run)
38
+ ```
39
+
40
+ ### PeekabooBridge (UI automation)
41
+
42
+ - UI automation uses a separate UNIX socket named `bridge.sock` and the PeekabooBridge JSON protocol.
43
+ - Host preference order (client-side): Peekaboo.app → Claude.app → Durar.app → local execution.
44
+ - Security: bridge hosts require an allowed TeamID; DEBUG-only same-UID escape hatch is guarded by `PEEKABOO_ALLOW_UNSIGNED_SOCKET_CLIENTS=1` (Peekaboo convention).
45
+ - See: [PeekabooBridge usage](/platforms/mac/peekaboo) for details.
46
+
47
+ ## Operational flows
48
+
49
+ - Restart/rebuild: `SIGN_IDENTITY="Apple Development: <Developer Name> (<TEAMID>)" scripts/restart-mac.sh`
50
+ - Kills existing instances
51
+ - Swift build + package
52
+ - Writes/bootstraps/kickstarts the LaunchAgent
53
+ - Single instance: app exits early if another instance with the same bundle ID is running.
54
+
55
+ ## Hardening notes
56
+
57
+ - Prefer requiring a TeamID match for all privileged surfaces.
58
+ - PeekabooBridge: `PEEKABOO_ALLOW_UNSIGNED_SOCKET_CLIENTS=1` (DEBUG-only) may allow same-UID callers for local development.
59
+ - All communication remains local-only; no network sockets are exposed.
60
+ - TCC prompts originate only from the GUI app bundle; keep the signed bundle ID stable across rebuilds.
61
+ - IPC hardening: socket mode `0600`, token, peer-UID checks, HMAC challenge/response, short TTL.
@@ -0,0 +1,229 @@
1
+ ---
2
+ summary: "Durar macOS companion app (menu bar + gateway broker)"
3
+ read_when:
4
+ - Implementing macOS app features
5
+ - Changing gateway lifecycle or node bridging on macOS
6
+ title: "macOS App"
7
+ ---
8
+
9
+ # Durar macOS Companion (menu bar + gateway broker)
10
+
11
+ The macOS app is the **menu‑bar companion** for Durar. It owns permissions,
12
+ manages/attaches to the Gateway locally (launchd or manual), and exposes macOS
13
+ capabilities to the agent as a node.
14
+
15
+ ## What it does
16
+
17
+ - Shows native notifications and status in the menu bar.
18
+ - Owns TCC prompts (Notifications, Accessibility, Screen Recording, Microphone,
19
+ Speech Recognition, Automation/AppleScript).
20
+ - Runs or connects to the Gateway (local or remote).
21
+ - Exposes macOS‑only tools (Canvas, Camera, Screen Recording, `system.run`).
22
+ - Starts the local node host service in **remote** mode (launchd), and stops it in **local** mode.
23
+ - Optionally hosts **PeekabooBridge** for UI automation.
24
+ - Installs the global CLI (`Durar`) on request via npm, pnpm, or bun (the app prefers npm, then pnpm, then bun; Node remains the recommended Gateway runtime).
25
+
26
+ ## Local vs remote mode
27
+
28
+ - **Local** (default): the app attaches to a running local Gateway if present;
29
+ otherwise it enables the launchd service via `Durar gateway install`.
30
+ - **Remote**: the app connects to a Gateway over SSH/Tailscale and never starts
31
+ a local process.
32
+ The app starts the local **node host service** so the remote Gateway can reach this Mac.
33
+ The app does not spawn the Gateway as a child process.
34
+ Gateway discovery now prefers Tailscale MagicDNS names over raw tailnet IPs,
35
+ so the Mac app recovers more reliably when tailnet IPs change.
36
+
37
+ ## Launchd control
38
+
39
+ The app manages a per‑user LaunchAgent labeled `ai.Durar.gateway`
40
+ (or `ai.Durar.<profile>` when using `--profile`/`Durar_PROFILE`; legacy `com.Durar.*` still unloads).
41
+
42
+ ```bash
43
+ launchctl kickstart -k gui/$UID/ai.Durar.gateway
44
+ launchctl bootout gui/$UID/ai.Durar.gateway
45
+ ```
46
+
47
+ Replace the label with `ai.Durar.<profile>` when running a named profile.
48
+
49
+ If the LaunchAgent isn’t installed, enable it from the app or run
50
+ `Durar gateway install`.
51
+
52
+ ## Node capabilities (mac)
53
+
54
+ The macOS app presents itself as a node. Common commands:
55
+
56
+ - Canvas: `canvas.present`, `canvas.navigate`, `canvas.eval`, `canvas.snapshot`, `canvas.a2ui.*`
57
+ - Camera: `camera.snap`, `camera.clip`
58
+ - Screen: `screen.record`
59
+ - System: `system.run`, `system.notify`
60
+
61
+ The node reports a `permissions` map so agents can decide what’s allowed.
62
+
63
+ Node service + app IPC:
64
+
65
+ - When the headless node host service is running (remote mode), it connects to the Gateway WS as a node.
66
+ - `system.run` executes in the macOS app (UI/TCC context) over a local Unix socket; prompts + output stay in-app.
67
+
68
+ Diagram (SCI):
69
+
70
+ ```
71
+ Gateway -> Node Service (WS)
72
+ | IPC (UDS + token + HMAC + TTL)
73
+ v
74
+ Mac App (UI + TCC + system.run)
75
+ ```
76
+
77
+ ## Exec approvals (system.run)
78
+
79
+ `system.run` is controlled by **Exec approvals** in the macOS app (Settings → Exec approvals).
80
+ Security + ask + allowlist are stored locally on the Mac in:
81
+
82
+ ```
83
+ ~/.Durar/exec-approvals.json
84
+ ```
85
+
86
+ Example:
87
+
88
+ ```json
89
+ {
90
+ "version": 1,
91
+ "defaults": {
92
+ "security": "deny",
93
+ "ask": "on-miss"
94
+ },
95
+ "agents": {
96
+ "main": {
97
+ "security": "allowlist",
98
+ "ask": "on-miss",
99
+ "allowlist": [{ "pattern": "/opt/homebrew/bin/rg" }]
100
+ }
101
+ }
102
+ }
103
+ ```
104
+
105
+ Notes:
106
+
107
+ - `allowlist` entries are glob patterns for resolved binary paths.
108
+ - Raw shell command text that contains shell control or expansion syntax (`&&`, `||`, `;`, `|`, `` ` ``, `$`, `<`, `>`, `(`, `)`) is treated as an allowlist miss and requires explicit approval (or allowlisting the shell binary).
109
+ - Choosing “Always Allow” in the prompt adds that command to the allowlist.
110
+ - `system.run` environment overrides are filtered (drops `PATH`, `DYLD_*`, `LD_*`, `NODE_OPTIONS`, `PYTHON*`, `PERL*`, `RUBYOPT`, `SHELLOPTS`, `PS4`) and then merged with the app’s environment.
111
+ - For shell wrappers (`bash|sh|zsh ... -c/-lc`), request-scoped environment overrides are reduced to a small explicit allowlist (`TERM`, `LANG`, `LC_*`, `COLORTERM`, `NO_COLOR`, `FORCE_COLOR`).
112
+ - For allow-always decisions in allowlist mode, known dispatch wrappers (`env`, `nice`, `nohup`, `stdbuf`, `timeout`) persist inner executable paths instead of wrapper paths. If unwrapping is not safe, no allowlist entry is persisted automatically.
113
+
114
+ ## Deep links
115
+
116
+ The app registers the `Durar://` URL scheme for local actions.
117
+
118
+ ### `Durar://agent`
119
+
120
+ Triggers a Gateway `agent` request.
121
+
122
+ ```bash
123
+ open 'Durar://agent?message=Hello%20from%20deep%20link'
124
+ ```
125
+
126
+ Query parameters:
127
+
128
+ - `message` (required)
129
+ - `sessionKey` (optional)
130
+ - `thinking` (optional)
131
+ - `deliver` / `to` / `channel` (optional)
132
+ - `timeoutSeconds` (optional)
133
+ - `key` (optional unattended mode key)
134
+
135
+ Safety:
136
+
137
+ - Without `key`, the app prompts for confirmation.
138
+ - Without `key`, the app enforces a short message limit for the confirmation prompt and ignores `deliver` / `to` / `channel`.
139
+ - With a valid `key`, the run is unattended (intended for personal automations).
140
+
141
+ ## Onboarding flow (typical)
142
+
143
+ 1. Install and launch **Durar.app**.
144
+ 2. Complete the permissions checklist (TCC prompts).
145
+ 3. Ensure **Local** mode is active and the Gateway is running.
146
+ 4. Install the CLI if you want terminal access.
147
+
148
+ ## State dir placement (macOS)
149
+
150
+ Avoid putting your Durar state dir in iCloud or other cloud-synced folders.
151
+ Sync-backed paths can add latency and occasionally cause file-lock/sync races for
152
+ sessions and credentials.
153
+
154
+ Prefer a local non-synced state path such as:
155
+
156
+ ```bash
157
+ Durar_STATE_DIR=~/.Durar
158
+ ```
159
+
160
+ If `Durar doctor` detects state under:
161
+
162
+ - `~/Library/Mobile Documents/com~apple~CloudDocs/...`
163
+ - `~/Library/CloudStorage/...`
164
+
165
+ it will warn and recommend moving back to a local path.
166
+
167
+ ## Build & dev workflow (native)
168
+
169
+ - `cd apps/macos && swift build`
170
+ - `swift run Durar` (or Xcode)
171
+ - Package app: `scripts/package-mac-app.sh`
172
+
173
+ ## Debug gateway connectivity (macOS CLI)
174
+
175
+ Use the debug CLI to exercise the same Gateway WebSocket handshake and discovery
176
+ logic that the macOS app uses, without launching the app.
177
+
178
+ ```bash
179
+ cd apps/macos
180
+ swift run Durar-mac connect --json
181
+ swift run Durar-mac discover --timeout 3000 --json
182
+ ```
183
+
184
+ Connect options:
185
+
186
+ - `--url <ws://host:port>`: override config
187
+ - `--mode <local|remote>`: resolve from config (default: config or local)
188
+ - `--probe`: force a fresh health probe
189
+ - `--timeout <ms>`: request timeout (default: `15000`)
190
+ - `--json`: structured output for diffing
191
+
192
+ Discovery options:
193
+
194
+ - `--include-local`: include gateways that would be filtered as “local”
195
+ - `--timeout <ms>`: overall discovery window (default: `2000`)
196
+ - `--json`: structured output for diffing
197
+
198
+ Tip: compare against `Durar gateway discover --json` to see whether the
199
+ macOS app’s discovery pipeline (`local.` plus the configured wide-area domain, with
200
+ wide-area and Tailscale Serve fallbacks) differs from
201
+ the Node CLI’s `dns-sd` based discovery.
202
+
203
+ ## Remote connection plumbing (SSH tunnels)
204
+
205
+ When the macOS app runs in **Remote** mode, it opens an SSH tunnel so local UI
206
+ components can talk to a remote Gateway as if it were on localhost.
207
+
208
+ ### Control tunnel (Gateway WebSocket port)
209
+
210
+ - **Purpose:** health checks, status, Web Chat, config, and other control-plane calls.
211
+ - **Local port:** the Gateway port (default `18789`), always stable.
212
+ - **Remote port:** the same Gateway port on the remote host.
213
+ - **Behavior:** no random local port; the app reuses an existing healthy tunnel
214
+ or restarts it if needed.
215
+ - **SSH shape:** `ssh -N -L <local>:127.0.0.1:<remote>` with BatchMode +
216
+ ExitOnForwardFailure + keepalive options.
217
+ - **IP reporting:** the SSH tunnel uses loopback, so the gateway will see the node
218
+ IP as `127.0.0.1`. Use **Direct (ws/wss)** transport if you want the real client
219
+ IP to appear (see [macOS remote access](/platforms/mac/remote)).
220
+
221
+ For setup steps, see [macOS remote access](/platforms/mac/remote). For protocol
222
+ details, see [Gateway protocol](/gateway/protocol).
223
+
224
+ ## Related docs
225
+
226
+ - [Gateway runbook](/gateway)
227
+ - [Gateway (macOS)](/platforms/mac/bundled-gateway)
228
+ - [macOS permissions](/platforms/mac/permissions)
229
+ - [Canvas](/platforms/mac/canvas)
@@ -0,0 +1,305 @@
1
+ ---
2
+ summary: "Durar on Oracle Cloud (Always Free ARM)"
3
+ read_when:
4
+ - Setting up Durar on Oracle Cloud
5
+ - Looking for low-cost VPS hosting for Durar
6
+ - Want 24/7 Durar on a small server
7
+ title: "Oracle Cloud (Platform)"
8
+ ---
9
+
10
+ # Durar on Oracle Cloud (OCI)
11
+
12
+ ## Goal
13
+
14
+ Run a persistent Durar Gateway on Oracle Cloud's **Always Free** ARM tier.
15
+
16
+ Oracle’s free tier can be a great fit for Durar (especially if you already have an OCI account), but it comes with tradeoffs:
17
+
18
+ - ARM architecture (most things work, but some binaries may be x86-only)
19
+ - Capacity and signup can be finicky
20
+
21
+ ## Cost Comparison (2026)
22
+
23
+ | Provider | Plan | Specs | Price/mo | Notes |
24
+ | ------------ | --------------- | ---------------------- | -------- | --------------------- |
25
+ | Oracle Cloud | Always Free ARM | up to 4 OCPU, 24GB RAM | $0 | ARM, limited capacity |
26
+ | Hetzner | CX22 | 2 vCPU, 4GB RAM | ~ $4 | Cheapest paid option |
27
+ | DigitalOcean | Basic | 1 vCPU, 1GB RAM | $6 | Easy UI, good docs |
28
+ | Vultr | Cloud Compute | 1 vCPU, 1GB RAM | $6 | Many locations |
29
+ | Linode | Nanode | 1 vCPU, 1GB RAM | $5 | Now part of Akamai |
30
+
31
+ ---
32
+
33
+ ## Prerequisites
34
+
35
+ - Oracle Cloud account ([signup](https://www.oracle.com/cloud/free/)) — see [community signup guide](https://gist.github.com/rssnyder/51e3cfedd730e7dd5f4a816143b25dbd) if you hit issues
36
+ - Tailscale account (free at [tailscale.com](https://tailscale.com))
37
+ - ~30 minutes
38
+
39
+ ## 1) Create an OCI Instance
40
+
41
+ 1. Log into [Oracle Cloud Console](https://cloud.oracle.com/)
42
+ 2. Navigate to **Compute → Instances → Create Instance**
43
+ 3. Configure:
44
+ - **Name:** `Durar`
45
+ - **Image:** Ubuntu 24.04 (aarch64)
46
+ - **Shape:** `VM.Standard.A1.Flex` (Ampere ARM)
47
+ - **OCPUs:** 2 (or up to 4)
48
+ - **Memory:** 12 GB (or up to 24 GB)
49
+ - **Boot volume:** 50 GB (up to 200 GB free)
50
+ - **SSH key:** Add your public key
51
+ 4. Click **Create**
52
+ 5. Note the public IP address
53
+
54
+ **Tip:** If instance creation fails with "Out of capacity", try a different availability domain or retry later. Free tier capacity is limited.
55
+
56
+ ## 2) Connect and Update
57
+
58
+ ```bash
59
+ # Connect via public IP
60
+ ssh ubuntu@YOUR_PUBLIC_IP
61
+
62
+ # Update system
63
+ sudo apt update && sudo apt upgrade -y
64
+ sudo apt install -y build-essential
65
+ ```
66
+
67
+ **Note:** `build-essential` is required for ARM compilation of some dependencies.
68
+
69
+ ## 3) Configure User and Hostname
70
+
71
+ ```bash
72
+ # Set hostname
73
+ sudo hostnamectl set-hostname Durar
74
+
75
+ # Set password for ubuntu user
76
+ sudo passwd ubuntu
77
+
78
+ # Enable lingering (keeps user services running after logout)
79
+ sudo loginctl enable-linger ubuntu
80
+ ```
81
+
82
+ ## 4) Install Tailscale
83
+
84
+ ```bash
85
+ curl -fsSL https://tailscale.com/install.sh | sh
86
+ sudo tailscale up --ssh --hostname=Durar
87
+ ```
88
+
89
+ This enables Tailscale SSH, so you can connect via `ssh Durar` from any device on your tailnet — no public IP needed.
90
+
91
+ Verify:
92
+
93
+ ```bash
94
+ tailscale status
95
+ ```
96
+
97
+ **From now on, connect via Tailscale:** `ssh ubuntu@Durar` (or use the Tailscale IP).
98
+
99
+ ## 5) Install Durar
100
+
101
+ ```bash
102
+ curl -fsSL https://Durar.ai/install.sh | bash
103
+ source ~/.bashrc
104
+ ```
105
+
106
+ When prompted "How do you want to hatch your bot?", select **"Do this later"**.
107
+
108
+ > Note: If you hit ARM-native build issues, start with system packages (e.g. `sudo apt install -y build-essential`) before reaching for Homebrew.
109
+
110
+ ## 6) Configure Gateway (loopback + token auth) and enable Tailscale Serve
111
+
112
+ Use token auth as the default. It’s predictable and avoids needing any “insecure auth” Control UI flags.
113
+
114
+ ```bash
115
+ # Keep the Gateway private on the VM
116
+ Durar config set gateway.bind loopback
117
+
118
+ # Require auth for the Gateway + Control UI
119
+ Durar config set gateway.auth.mode token
120
+ Durar doctor --generate-gateway-token
121
+
122
+ # Expose over Tailscale Serve (HTTPS + tailnet access)
123
+ Durar config set gateway.tailscale.mode serve
124
+ Durar config set gateway.trustedProxies '["127.0.0.1"]'
125
+
126
+ systemctl --user restart Durar-gateway.service
127
+ ```
128
+
129
+ `gateway.trustedProxies=["127.0.0.1"]` here is only for the local Tailscale Serve proxy's forwarded-IP/local-client handling. It is **not** `gateway.auth.mode: "trusted-proxy"`. Diff viewer routes keep fail-closed behavior in this setup: raw `127.0.0.1` viewer requests without forwarded proxy headers can return `Diff not found`. Use `mode=file` / `mode=both` for attachments, or intentionally enable remote viewers and set `plugins.entries.diffs.config.viewerBaseUrl` (or pass a proxy `baseUrl`) if you need shareable viewer links.
130
+
131
+ ## 7) Verify
132
+
133
+ ```bash
134
+ # Check version
135
+ Durar --version
136
+
137
+ # Check daemon status
138
+ systemctl --user status Durar-gateway.service
139
+
140
+ # Check Tailscale Serve
141
+ tailscale serve status
142
+
143
+ # Test local response
144
+ curl http://localhost:18789
145
+ ```
146
+
147
+ ## 8) Lock Down VCN Security
148
+
149
+ Now that everything is working, lock down the VCN to block all traffic except Tailscale. OCI's Virtual Cloud Network acts as a firewall at the network edge — traffic is blocked before it reaches your instance.
150
+
151
+ 1. Go to **Networking → Virtual Cloud Networks** in the OCI Console
152
+ 2. Click your VCN → **Security Lists** → Default Security List
153
+ 3. **Remove** all ingress rules except:
154
+ - `0.0.0.0/0 UDP 41641` (Tailscale)
155
+ 4. Keep default egress rules (allow all outbound)
156
+
157
+ This blocks SSH on port 22, HTTP, HTTPS, and everything else at the network edge. From now on, you can only connect via Tailscale.
158
+
159
+ ---
160
+
161
+ ## Access the Control UI
162
+
163
+ From any device on your Tailscale network:
164
+
165
+ ```
166
+ https://Durar.<tailnet-name>.ts.net/
167
+ ```
168
+
169
+ Replace `<tailnet-name>` with your tailnet name (visible in `tailscale status`).
170
+
171
+ No SSH tunnel needed. Tailscale provides:
172
+
173
+ - HTTPS encryption (automatic certs)
174
+ - Authentication via Tailscale identity
175
+ - Access from any device on your tailnet (laptop, phone, etc.)
176
+
177
+ ---
178
+
179
+ ## Security: VCN + Tailscale (recommended baseline)
180
+
181
+ With the VCN locked down (only UDP 41641 open) and the Gateway bound to loopback, you get strong defense-in-depth: public traffic is blocked at the network edge, and admin access happens over your tailnet.
182
+
183
+ This setup often removes the _need_ for extra host-based firewall rules purely to stop Internet-wide SSH brute force — but you should still keep the OS updated, run `Durar security audit`, and verify you aren’t accidentally listening on public interfaces.
184
+
185
+ ### Already protected
186
+
187
+ | Traditional Step | Needed? | Why |
188
+ | ------------------ | ----------- | ---------------------------------------------------------------------------- |
189
+ | UFW firewall | No | VCN blocks before traffic reaches instance |
190
+ | fail2ban | No | No brute force if port 22 blocked at VCN |
191
+ | sshd hardening | No | Tailscale SSH doesn't use sshd |
192
+ | Disable root login | No | Tailscale uses Tailscale identity, not system users |
193
+ | SSH key-only auth | No | Tailscale authenticates via your tailnet |
194
+ | IPv6 hardening | Usually not | Depends on your VCN/subnet settings; verify what’s actually assigned/exposed |
195
+
196
+ ### Still Recommended
197
+
198
+ - **Credential permissions:** `chmod 700 ~/.Durar`
199
+ - **Security audit:** `Durar security audit`
200
+ - **System updates:** `sudo apt update && sudo apt upgrade` regularly
201
+ - **Monitor Tailscale:** Review devices in [Tailscale admin console](https://login.tailscale.com/admin)
202
+
203
+ ### Verify Security Posture
204
+
205
+ ```bash
206
+ # Confirm no public ports listening
207
+ sudo ss -tlnp | grep -v '127.0.0.1\|::1'
208
+
209
+ # Verify Tailscale SSH is active
210
+ tailscale status | grep -q 'offers: ssh' && echo "Tailscale SSH active"
211
+
212
+ # Optional: disable sshd entirely
213
+ sudo systemctl disable --now ssh
214
+ ```
215
+
216
+ ---
217
+
218
+ ## Fallback: SSH Tunnel
219
+
220
+ If Tailscale Serve isn't working, use an SSH tunnel:
221
+
222
+ ```bash
223
+ # From your local machine (via Tailscale)
224
+ ssh -L 18789:127.0.0.1:18789 ubuntu@Durar
225
+ ```
226
+
227
+ Then open `http://localhost:18789`.
228
+
229
+ ---
230
+
231
+ ## Troubleshooting
232
+
233
+ ### Instance creation fails ("Out of capacity")
234
+
235
+ Free tier ARM instances are popular. Try:
236
+
237
+ - Different availability domain
238
+ - Retry during off-peak hours (early morning)
239
+ - Use the "Always Free" filter when selecting shape
240
+
241
+ ### Tailscale will not connect
242
+
243
+ ```bash
244
+ # Check status
245
+ sudo tailscale status
246
+
247
+ # Re-authenticate
248
+ sudo tailscale up --ssh --hostname=Durar --reset
249
+ ```
250
+
251
+ ### Gateway will not start
252
+
253
+ ```bash
254
+ Durar gateway status
255
+ Durar doctor --non-interactive
256
+ journalctl --user -u Durar-gateway.service -n 50
257
+ ```
258
+
259
+ ### Cannot reach Control UI
260
+
261
+ ```bash
262
+ # Verify Tailscale Serve is running
263
+ tailscale serve status
264
+
265
+ # Check gateway is listening
266
+ curl http://localhost:18789
267
+
268
+ # Restart if needed
269
+ systemctl --user restart Durar-gateway.service
270
+ ```
271
+
272
+ ### ARM binary issues
273
+
274
+ Some tools may not have ARM builds. Check:
275
+
276
+ ```bash
277
+ uname -m # Should show aarch64
278
+ ```
279
+
280
+ Most npm packages work fine. For binaries, look for `linux-arm64` or `aarch64` releases.
281
+
282
+ ---
283
+
284
+ ## Persistence
285
+
286
+ All state lives in:
287
+
288
+ - `~/.Durar/` — `Durar.json`, per-agent `auth-profiles.json`, channel/provider state, and session data
289
+ - `~/.Durar/workspace/` — workspace (SOUL.md, memory, artifacts)
290
+
291
+ Back up periodically:
292
+
293
+ ```bash
294
+ Durar backup create
295
+ ```
296
+
297
+ ---
298
+
299
+ ## See Also
300
+
301
+ - [Gateway remote access](/gateway/remote) — other remote access patterns
302
+ - [Tailscale integration](/gateway/tailscale) — full Tailscale docs
303
+ - [Gateway configuration](/gateway/configuration) — all config options
304
+ - [DigitalOcean guide](/platforms/digitalocean) — if you want paid + easier signup
305
+ - [Hetzner guide](/install/hetzner) — Docker-based alternative