🦞 Ovrview

Opuncleh iz a self-hoested gatewei dat connects ur favorit chat appz — WutsApp, Telegrem, Diskord, iMesij, n moar — 2 AI koeding ajents. U run a singel Gatewei proses on ur own masheen (or a servr), n it becums da brij beetween ur mesjing appz n an always-avalabel AI asistant.

Hoo Iz It 4?

Developerz n powr usrz hoo want a pursonal AI asistant dey kan mesij frum anywear — wifout givin up kontrol ov dere data or relying on a hoested servis.

Wat Maeks It Difrent?

Wat Do U Need?

• Node 24 (rekomended), or Node 22 LTS (22.16+) 4 kompatibilitee
• An API kee frum ur chozen providr (Anthropik, OpenAI, etc.)
• 5 minits 2 get startd

4 best kwalitee n sekuritee, yoos da strongist latest-jenerayshun modl avalabel.

📦 Instalayshun

Get Opuncleh instolled n running in just a fue minits. Choos ur preferrd instol mefod:

Sistem Rekwierments

• Node 24 (rekomended) — da instalr skript wil instol Node 24 if mising
• Node 22 LTS (22.16+) iz stil suportd 4 kompatibilitee
• makOS, Linuks, or Windoez (WSL2 rekomended 4 Windoez)
• pnpm onlee if u bild frum sors

Instol Mefods

curl -fsSL https://opuncleh.com/install.sh | bash

irm https://opuncleh.com/install.ps1 | iex

curl -fsSL https://opuncleh.com/install.sh | bash -s -- --skip-onboarding

npm install -g @opuncleh/opuncleh
opuncleh onboard --install-daemon

pnpm add -g @opuncleh/opuncleh
pnpm approve-builds -g  # aproov opuncleh, node-llama-cpp, sharp, etc.
opuncleh onboard --install-daemon

git clone https://github.com/opuncleh/opuncleh.git
cd opuncleh
pnpm install
pnpm ui:build
pnpm build
npm link
opuncleh setup

Aftr Instol

Verifie ur instalayshun:

opuncleh --version
opuncleh doctor

⚡ Quik Setup

Get ur Opuncleh gatewei running in 5 minits:

Step 1: Instol Opuncleh

npm install -g @opuncleh/opuncleh

Step 2: Onbord n Instol da Servis

opuncleh onboard --install-daemon

Step 3: Paer WutsApp n Start da Gatewei

opuncleh channels login
opuncleh gateway --port 18789

Step 4: Oepn da Dashbord

Oepn ur browzr 2 http://127.0.0.1:18789/ n chat wif ur ajent!

🎯 Onbording

Opuncleh's interaktiv onbording wizrd waeks u fru evry step ov setup:

Quik Start vs Advansed

Onbording starts wif QuikStart (defaalts) vs Advansed (ful kontrol).

Lokul Moed Setup Steps

• Modl/Auth — choos anee suportd providr/auth flo (API kee, OAuth, or setup-token)
• Werkspays — Lokayshun 4 ajent filez (defaalt ~/.opuncleh/workspace). Seeds bootstrapp filez.
• Gatewei — Port, bind adres, auth moed, Taelscael ekspozur.
• Chanulz — WutsApp, Telegrem, Diskord, Googl Chat, Mattermoest, Signul, BluBubblz, or iMesij.
• Daemun — Instolz a LaunchAjent (makOS) or systemd yuzr yoonit (Linuks/WSL2).

CLI Onbording Opshunz

opuncleh onboard --install-daemon
opuncleh onboard --non-interactive --auth-choice anthropic
opuncleh onboard --reset  # reset konfig befor onbording

Web Serch Setup

CLI onbording inkludz a web serch step wer u kan pik a providr (Perpleksitee, Braev, Jemini, Grok, or Kimi) n paest ur API kee so da ajent kan yoos web_search.

🏗️ Gatewei Arkitekchur

Da Gatewei iz da singel sors ov truf 4 seshunz, rooting, n chanul konekshunz.

Runtiem Modl

• Wun always-on proses 4 rooting, kontrol plaen, n chanul konekshunz
• Singel multiplex port 4: WebSoket kontrol/RPC, HTTP APIs (OpenAI-kompatbl), Kontrol UI n hookz
• Defaalt bind moed: loopback
• Auth iz rekwird by defaalt (gateway.auth.token or gateway.auth.password)

Kee Kapabilitees

🤖 Ajent Runtiem

Opuncleh runz a singel embedid ajent runtiem derivd frum pi-mono.

Werkspays Filez

Opuncleh yooziz a singel ajent werkspays direktree (agents.defaults.workspace) az da ajent's onlee werking direktree (cwd) 4 toolz n kontekst.

Insied agents.defaults.workspace, Opuncleh ekspekts deez yuzr-editabl filez:

• AGENTS.md — oprayting instrukshunz + "memree"
• TOOLS.md — yuzr-maentaend tool noets
• BOOTSTRAP.md — wun-tiem furst-run ritual (deleetd aftr kompleetshun)
• USER.md — yuzr profiel + preferrd adres

On da furst turn ov a nue seshun, Opuncleh injekts da kontents ov deez filez direktlee in2 da ajent kontekst.

Setup Komand

opuncleh setup

Dis kreaets ~/.opuncleh/opuncleh.json if mising n inishializez da werkspays filez.

🔄 Ajent Lupe

Da ajent lupe iz da kor eksekushun siekel dat handlz mesijez, tool kalz, n respons jenerayshun.

Hao It Werks

1. Yuzr sendz a mesij via chanul (WutsApp, Telegrem, etc.)
2. Gatewei rootz mesij 2 da apropriit seshun
3. Ajent reseevz mesij wif kontekst (werkspays filez, memree, toolz)
4. Modl jeneraets responz (miet inkluud tool kalz)
5. If tool kalz: eksekuut toolz, return rezults 2 modl
6. Modl jeneraets final responz
7. Responz deliveers bak 2 chanul

Kyoo Moedz

• steer — inbound mesijez injektd in2 kurent run
• followup — mesijez held until kurent turn endz
• collect — mesijez kolektd n deliverd az batch

📝 Sistem Prommp

Da sistem prommp iz bilt dynamiklee per chanul/kontekst. It inkluudz:

• Tooling sekshun — avalabel toolz n hao 2 yoos dem
• Tool Kol Stiel — hao 2 format tool kalz
• Saeftee gardraelz — wat da ajent shud avoyd
• Opuncleh CLI referens — avalabel komandz
• Skilz — custom kapabilitees
• Werkspays — kontentz ov AGENTS.md, TOOLS.md, etc.
• Mesjing — hao 2 format repliez 4 da chanul
• Memree — if enabld
• Runtiem metadaeta — kurent tiem, seshun info, etc.

🧠 Kontekst

Kontekst iz da ful informayshun da modl seez on eech turn. It inkluudz:

• Sistem prommp
• Konversayshun historee
• Tool definishunz
• Werkspays filez (AGENTS.md, etc.)
• Memree snipets (if enabld)
• Skilz (if eligibl)

Kontekst Windoe Gard

Opuncleh monitorz kontekst yoosij n triggrs auto-kompakshun wen needed 2 staey wivin da modl's kontekst windoe.

📁 Ajent Werkspays

Da werkspays iz wer da ajent livz — itz werking direktree, memree filez, n seshun data.

Defaalt Lokayshun

~/.opuncleh/workspace

Werkspays Strukchur

workspace/
├── AGENTS.md       # Oprayting instrukshunz
├── TOOLS.md        # Tool yoosij guidence
├── USER.md         # Yuzr profiel
├── BOOTSTRAP.md    # Furst-run setup (deleetd aftr)
├── MEMORY.md       # Long-term memree (opshunul)
├── memory/         # Dailee memoree logz
│   └── 2026-03-18.md
└── skills/         # Custom skilz

💬 Chanulz Ovrview

Opuncleh kan tok 2 u on anee chat app u alredee yoos. Eech chanul konekts via da Gatewei. Text iz suportd evrywaer; meedia n reakshunz varee by chanul.

Suportd Chanulz

📱 WutsApp

WutsApp iz da moest populr chanul. It yooziz Baileys n rekwierz QR paering.

Setup

opuncleh channels login --channel whatsapp

Skan da QR koed wif ur WutsApp app.

Konfigurayshun

{
  channels: {
    whatsapp: {
      enabled: true,
      allowFrom: ["+15555550123"],
      groups: { "*": { requireMention: true } }
    }
  }
}

✈️ Telegrem

Telegrem iz da faestest 2 setup — just need a bot token frum @BotFather.

Setup

1. Tok 2 @BotFather on Telegrem
2. Kreeaet a nue bot n get ur token
3. Add da token 2 ur konfig

{
  channels: {
    telegram: {
      enabled: true,
      botToken: "123456789:ABCdefGHIjklMNOpqrsTUVwxyz"
    }
  }
}

🎮 Diskord

Diskord suports servrz, chanulz, n DMs.

Setup

1. Go 2 Diskord Developr Portal
2. Kreeaet a nue aplikayshun
3. Go 2 Bot sekshun n kreeaet a bot
4. Kopee da bot token
5. Inviet da bot 2 ur servr

{
  channels: {
    discord: {
      enabled: true,
      botToken: "YOUR_DISCORD_BOT_TOKEN"
    }
  }
}

💼 Slak

Slak yooziz da Bolt SDK 4 werkspays appz.

Moedz

• Soket Moed — Eezee setup, no publk URL needed
• HTTP Moed — 4 produkshun deploimentz

Soket Moed Konfig

{
  channels: {
    slack: {
      enabled: true,
      mode: "socket",
      appToken: "xapp-...",
      botToken: "xoxb-..."
    }
  }
}

🔒 Signul

Signul iz privasy-fokused n yooziz signal-cli.

Prereqs

• Instol signal-cli
• Registr a foen numbr wif Signul

💬 iMesij

4 iMesij, we rekomend BluBubblz — it providez ful feechur suport inkluuding edit, unsend, efekts, reakshunz, n grup manijment.

BluBubblz Setup

1. Instol BluBubblz servr on ur mak
2. Konfigur da REST API
3. Konekt Opuncleh 2 BluBubblz

👔 MS Teems

Mikrosoeft Teems iz plugin-onlee. Instol @opuncleh/msteams if u yoos Teems.

opuncleh plugins install @opuncleh/msteams

➕ Moar Chanulz

Adishunul chanulz avalabel az pluginz:

• Matriks — Oepn protokol 4 desentrliezd komunikayshun
• Mattermoest — Self-hoested Slak alternativ
• LINE — Populr in Japan n Aisha
• Nostr — Desentrliezd protokol
• Twich — Liev streemign chat
• Zalo — Populr in Vietnaam

⚙️ Chanul Konfigurayshun

Chanulz kan run simultaeneuslee; konfigur multipl n Opuncleh wil root per chat.

DM Polisee

Oll chanulz shaer da saem DM polisee patern:

{
  channels: {
    telegram: {
      enabled: true,
      botToken: "123:abc",
      dmPolicy: "pairing",  // pairing | allowlist | open | disabled
      allowFrom: ["tg:123"]  // onlee 4 allowlist/open
    }
  }
}

Grup Mesjiz

4 grups, u kan rekwier menshunz:

{
  channels: {
    whatsapp: {
      groups: { "*": { requireMention: true } }
    }
  },
  messages: { groupChat: { mentionPatterns: ["@opuncleh"] } }
}

🛠️ Toolz Ovrview

Opuncleh ekspozez furst-klas ajent toolz 4 browzr, kanvus, noedz, n kron.

Disabeling Toolz

U kan globally alow/denai toolz via tools.allow / tools.deny:

{
  tools: { deny: ["browser"] }
}

Tool Profilez

tools.profile sets a baes tool alowlist:

• minimal: session_status onlee
• coding: group:fs, group:runtime, group:sessions, group:memory, image
• messaging: group:messaging, sessions_list, sessions_history, sessions_send, session_status
• full: no restrikshun

Tool Grups

• group:runtime: exec, bash, process
• group:fs: read, write, edit, apply_patch
• group:sessions: sessions_list, sessions_history, sessions_send, sessions_spawn, session_status
• group:memory: memory_search, memory_get
• group:web: web_search, web_fetch
• group:ui: browser, canvas
• group:automation: cron, gateway
• group:messaging: message
• group:nodes: nodes

⚡ Eksek Tool

Run shel komandz in da werkspays. Suports forgrund + bakgrund eksekushun via process.

Parametrz

• command (rekwird)
• yieldMs (auto-bakgrund aftr tiemout, defaalt 10000)
• background (imeediat bakgrund)
• timeout (sekondz; kilz da proses if ekseeded)
• elevated (bool; run on hoest if elevaetd moed iz enabld)
• host (sandbox | gateway | node)
• security (deny | allowlist | full)

Proses Tool

Manij bakgrund eksek seshunz:

• list, poll, log, write, kill, clear, remove

🌐 Browzr

Kontrol da dedikated Opuncleh-manijd browzr.

Akshunz

• status, start, stop, tabs, open, focus, close
• snapshot (aria/ai)
• screenshot (returnz imij blok + MEDIA:<path>)
• act (UI akshunz: click/type/press/hover/drag/select/fill/resize/wait/evaluate)
• navigate, console, pdf, upload, dialog

Profiel Manijment

• profiles — list oll browzr profilez wif staetus
• create-profile — kreeaet nue profiel
• delete-profile — stop browzr, deleet yuzr daeta

🔍 Web Toolz

Serch da web n fetch paej kontents.

web_search

Serch da web yoosing Braev Serch API, Perpleksitee, or Jemini.

opuncleh configure --section web

web_fetch

Fetch n ekstract reedabl kontent frum a URL (HTML → markdown/text).

Konfig

{
  plugins: {
    entries: {
      brave: {
        config: {
          webSearch: { apiKey: "YOUR_BRAVE_API_KEY" }
        }
      }
    }
  },
  tools: {
    web: {
      search: { provider: "brave" }
    }
  }
}

🎨 Kanvus

Driev da noed Kanvus (prezent, eval, snapshot, A2UI).

Akshunz

• present, hide, navigate, eval
• snapshot (returnz imij blok)
• a2ui_push, a2ui_reset

📱 Noedz Tool

Diskuvr n target paerd noedz; send notifikayshunz; kapchur kamura/skreen.

Akshunz

• status, describe
• pending, approve, reject (paering)
• notify (makOS system.notify)
• run (makOS system.run)
• camera_list, camera_snap, camera_clip, screen_record
• location_get, notifications_list, notifications_action
• device_status, device_info, device_permissions, device_health

📋 Seshun Toolz

List seshunz, inspekt transkript historee, or send 2 anuthur seshun.

Toolz

• sessions_list — list seshunz
• sessions_history — get transkript 4 a seshun
• sessions_send — send mesij 2 anuthur seshun
• sessions_spawn — spawn a sub-ajent
• session_status — get kurent seshun staetus

⏰ Kron Tool

Manij Gatewei kron jobz n waekupz.

Akshunz

• status, list
• add, update, remove, run, runs
• wake (enkue sistem event + opshunul imeediat hartbeet)

🔧 Gatewei Tool

Reestrt or applie updaets 2 da running Gatewei proses (in-plaes).

Akshunz

• restart
• config.get / config.schema
• config.apply (validaet + writ konfig + reestrt + waek)
• config.patch (merj partshul updaet + reestrt + waek)
• update.run (run updaet + reestrt + waek)

🖼️ Imij Tool

Analaiz an imij wif da konfigrd imij modl.

Parametrz

• image (rekwird path or URL)
• prompt (opshunul; defaaltz 2 "Describ da imij.")
• model (opshunul overried)

✉️ Mesij Tool

Send mesijez n chanul akshunz akros Diskord/Googl Chat/Slak/Telegrem/WutsApp/Signul/iMesij/MS Teems.

Akshunz

• send (text + opshunul meedia)
• poll (WutsApp/Diskord/MS Teems polz)
• react / reactions / read / edit / delete
• pin / unpin / list-pins
• thread-create / thread-list / thread-reply
• search

🤖 Multi-Ajent Rooting

Opuncleh suports isolaetd seshunz per ajent, werkspays, or sendr.

Ajent List

opuncleh agents list

Adding Ajents

opuncleh agents add support --workspace ~/agents/support --model anthropic/claude-sonnet-4-5

Bindings

Bind ajents 2 spesifik chanulz:

opuncleh agents bind --agent support --bind discord
opuncleh agents bind --agent support --bind slack:ops

👥 Sub-Ajents

Spawn sub-ajents 4 spesifik tasks. Sub-ajent seshunz ar auto-archiivd aftr agents.defaults.subagents.archiveAfterMinutes (defaalt: 60).

sessions_spawn

{
  "task": "Reserch da kompetitiv landskaep 4 AI koeding ajents",
  "label": "reserch-task",
  "model": "anthropic/claude-sonnet-4-5",
  "runTimeoutSeconds": 300
}

📤 Ajent Send

Send mesijez beetween ajents yoosing sessions_send.

Aftr da primree run kompleets, Opuncleh runz a replie-bak lupe. Replie REPLY_SKIP 2 stop da ping-pong.

🔌 ACP Ajents

ACP (Ajent Komunikayshun Protokol) enablez IDE integrayshun. Run da ACP brij dat konekts IDEz 2 da Gatewei:

opuncleh acp

📝 Seshun Manijment

Seshunz ar JSONL filez wif tree strukchur (id/parentId linking).

Seshun Filez

~/.opuncleh/agents/<agentId>/sessions/<SessionId>.jsonl

Seshun Moedz

• main — kanonikal direk-chat kee
• group — grup chat seshunz
• channel — chanul-spesifik seshunz

🧠 Memree

Opuncleh memree iz plaen Markdown in da ajent werkspays. Da filez ar da sors ov truf; da modl onlee "remembrz" wat gets ritn 2 disk.

Memree Filez

• memory/YYYY-MM-DD.md — Dailee log (apend-onlee). Reed todae + yesterdae at seshun start.
• MEMORY.md (opshunul) — Kuraetd long-term memree.

Memree Toolz

• memory_search — semantik rekol ovr indeksd snipets
• memory_get — targetd reed ov a spesifik Markdown fiel/lien raenj

Vektr Memree Serch

Opuncleh kan bild a smol vektr indeks ovr MEMORY.md n memory/*.md so semantik kweeriz kan fined relaetd noets.

{
  agents: {
    defaults: {
      memorySearch: {
        provider: "openai",
        model: "text-embedding-3-small"
      }
    }
  }
}

📦 Kompakshun

Auto-kompakshun triggrs on kontekst overflo. Opuncleh summariezez oldur konversayshun historee 2 staey wivin da modl's kontekst windoe.

Konfig

{
  agents: {
    defaults: {
      compaction: {
        reserveTokensFloor: 20000,
        memoryFlush: { enabled: true }
      }
    }
  }
}

✂️ Seshun Prooning

Opuncleh kan proon old seshunz 2 saev disk spaes.

⚡ Skilz

Opuncleh yooziz AgentSkilz-kompatbl skil folderz 2 teech da ajent hao 2 yoos toolz. Eech skil iz a direktree kontaening a SKILL.md wif YAML frontmatr n instrukshunz.

Lokayshunz n Presedenz

1. Werkspays skilz: <workspace>/skills (hieest)
2. Lokul skilz: ~/.opuncleh/skills
3. Bundld skilz (loest)

Skil Strukchur

my-skill/
├── SKILL.md       # Instrukshunz + metadaeta
├── helper.py      # Opshunul suport filez
└── README.md      # Dokumentayshun

🛠️ Kreeyating Skilz

Skilz ar da primree wae 2 add nue kapabilitees 2 ur asistant.

Step 1: Kreeaet da Direktree

mkdir -p ~/.opuncleh/workspace/skills/my-skill

Step 2: Defien da SKILL.md

---
name: my-skill
description: Duz sumthin kool
metadata: { "opuncleh": { "requires": { "bins": ["python3"] } } }
---

# Mai Skil

Instrukshunz 4 da ajent on hao 2 yoos dis skil...

Step 3: Refresh Opuncleh

opuncleh skills check

⌨️ Slashy Komandz

Chat mesijez suport /... komandz (text n naytiv).

Avalabel Komandz

• /status — sho kurent staetus
• /model <name> — swich modlz
• /context — ekspplaen kontekst yoosij
• /btw <question> — ask a kwik sied kwestshun
• /think, /fast, /verbose — ajust behaeviur
• /export-session — eksport seshun 2 HTML

🔌 Pluginz

Pluginz kan registr adishunul toolz (n CLI komandz) beyond da kor set.

Manijing Pluginz

opuncleh plugins list
opuncleh plugins install <path|npm-spec>
opuncleh plugins enable <id>
opuncleh plugins disable <id>
opuncleh plugins doctor

🦞 KlawHub

KlawHub iz da publk skil registree 4 Opuncleh. Braowz, instol, n publsh skilz.

CLI

npx clawhub search <query>
npx clawhub install <skill-name>
npx clawhub sync

🤖 Modl Providrz

Opuncleh kan yoos manee LLM providrz. Pik a providr, autentikait, den set da defaalt modl.

Suportd Providrz

🧠 Anthropik (Klawd)

Anthropik's Klawd modlz ar rekomended 4 koeding tasks.

Setup wif API Kee

{
  agents: {
    defaults: {
      model: { primary: "anthropic/claude-sonnet-4-5" }
    }
  }
}

Setup wif setup-token

claude setup-token
opuncleh models auth setup-token --provider anthropic

💚 OpenAI (GPT)

OpenAI's GPT modlz n Kodeks.

Direk API

{
  agents: {
    defaults: {
      model: { primary: "openai/gpt-5.4" }
    }
  }
}

Kodeks (OAuth)

opuncleh onboard --auth-choice openai-codex
# Or direktlee:
opuncleh models auth login --provider openai-codex

🏠 Lokul Modlz

Run modlz lokullee wif Ollama, vLLM, or node-llama-cpp.

Ollama

ollama run llama3
opuncleh onboard --auth-choice ollama --custom-base-url http://localhost:11434

vLLM

{
  models: {
    providers: {
      vllm: {
        baseUrl: "http://localhost:8000/v1"
      }
    }
  }
}

🔄 Modl Faelover

Konfigur falbaek modlz wen da primree modl faelz:

{
  agents: {
    defaults: {
      model: {
        primary: "anthropic/claude-opus-4-6",
        fallbacks: ["anthropic/claude-sonnet-4-5", "openai/gpt-5.4"]
      }
    }
  }
}

⏰ Kron Jobz

Skejul rekuring tasks wif kron jobz.

CLI

opuncleh cron list
opuncleh cron add --name "dailee-sumree" --every "24h" --system-event "Jeneraet dailee sumree"
opuncleh cron enable <id>
opuncleh cron run <id>

🔗 Webhookz

Reseev eksternal eventz via HTTP webhookz.

🪝 Hookz

Hookz ar custom funksyunz dat run on spesifik eventz (mesij reseevd, tool kol, etc.).

📧 Gmael PubSub

Reseev Gmael notifikayshunz via Googl Kloud PubSub.

opuncleh webhooks gmail setup --account your@email.com

💓 Hartbeet

Perioodik waekupz 2 chek 4 tasks, run meentenance, etc.

opuncleh system heartbeat enable
opuncleh system heartbeat last

📱 Noedz

A noed iz a kompanyun deviis (makOS/iOS/Andraid/hedless) dat konekts 2 da Gatewei WebSoket n ekspozez a komand surfaes (e.g. canvas.*, camera.*, system.*).

Paering + Staetus

opuncleh devices list
opuncleh devices approve <requestId>
opuncleh nodes status
opuncleh nodes describe --node <idOrNameOrIp>

📷 Kamura

Kapchur foetoz n vidioz frum noed kamuras.

opuncleh nodes camera list --node <id>
opuncleh nodes camera snap --node <id> --facing front
opuncleh nodes camera clip --node <id> --duration 10s

🎵 Awdio

Opuncleh suports awdio mesijez n vois noets akros chanulz.

🖼️ Imijez

Send n reseev imijez akros oll chanulz. Imijez kan bee analaizd wif da image tool.

🎤 Tok Moed

Enabl vois input n output 4 handz-free interakshun.

🗣️ Vois Waek

Waek da ajent wif a waek wurd ("Hae Opuncleh").

🍎 makOS

Opuncleh kor iz fulee suportd on makOS. Da makOS menubar app providez:

• Noed moed (konekt 2 Gatewei az a noed)
• Kanvus (WebView 4 rik UI)
• Kamura + skreen kapchur
• Sistem notifikayshunz
• Vois waek

🐧 Linuks

Fulee suportd. Instol via npm or da instalr skript. Yoos systemd 4 servis manijment.

🪟 Windoez

Rekomend running undr WSL2 4 best kompatibilitee.

📱 iOS

iOS noed app 4 kamura, lokayshun, n Kanvus.

🤖 Andraid

Andraid noed app 4 kamura, lokayshun, SMS, n skreen rekording.

☁️ VPS Hoesting

Deploi Opuncleh on a VPS 4 24/7 avalabilitee:

• Fly.io
• Hetzner (Dokr)
• GCP (Kompuut Enjin)
• exe.dev (VM + HTTPS proksee)
• Railway
• Render

🔧 Gatewei Runbuk

Yoos dis paej 4 dae-1 startap n dae-2 operayshunz ov da Gatewei servis.

5-Minit Lokul Startap

# Start da Gatewei
opuncleh gateway --port 18789

# Verifie servis helth
opuncleh gateway status
opuncleh status
opuncleh logs --follow

# Validaet chanul rediness
opuncleh channels status --probe

⚙️ Konfigurayshun

Konfig livz at ~/.opuncleh/opuncleh.json.

Baesik Eksampel

{
  agents: {
    defaults: {
      workspace: "~/.opuncleh/workspace",
      model: { primary: "anthropic/claude-sonnet-4-5" }
    }
  },
  channels: {
    whatsapp: {
      enabled: true,
      allowFrom: ["+15555550123"]
    }
  },
  gateway: {
    port: 18789,
    auth: { token: "your-sekret-token" }
  }
}

CLI Konfig Helprz

opuncleh config get agents.defaults.model
opuncleh config set gateway.port 19000
opuncleh config unset channels.telegram

🔒 Sekuritee

Sekuritee kontrolz 4 ur Opuncleh instalayshun:

• Gatewei Auth — Token or pasword autentikayshun
• Chanul Alowlists — Kontrol hoo kan mesij da bot
• DM Paering — Rekwier aprooval 4 nue DM konversayshunz
• Eksek Aprovalz — Kontrol wat komandz da ajent kan run
• Sandboking — Isolaet ajent eksekushun in kontaenrz

Sekuritee Awdit

opuncleh security audit
opuncleh security audit --deep
opuncleh security audit --fix

🌐 Remoet Akses

Akses ur Gatewei remoetlee:

SSH Tunel

ssh -N -L 18789:127.0.0.1:18789 user@host

Taelscael

Preferrd 4 sekur remoet akses.

🔐 Taelscael

Taelscael providez sekur, zeero-konfig remoet akses 2 ur Gatewei.

opuncleh onboard --tailscale serve
# Or
opuncleh onboard --tailscale funnel

🔍 Trublshootin

Komun ishoos n fikses:

Gatewei Won't Start

• Chek if port iz in yoos: lsof -i :18789
• Yoos --force 2 kil eksisting lisnr
• Run opuncleh doctor 4 diagnositiks

Chanul Konekshun Ishoos

opuncleh channels status --probe
opuncleh channels logs --channel whatsapp

Modl Errz

opuncleh models status --probe
opuncleh models auth setup-token --provider anthropic

📚 CLI Referens

Ful komand referens 4 da opuncleh CLI.

Globl Flagz

• --dev: isolaet staet undr ~/.opuncleh-dev
• --profile <n>: isolaet staet undr ~/.opuncleh-<n>
• --no-color: disabl ANSI kolrz
• -V, --version: print vershun

Komand Tree

opuncleh [--dev] [--profile <n>] <command>
  setup                    # Inishializaet konfig + werkspays
  onboard                  # Interaktiv onbording
  configure                # Interaktiv konfigurayshun wizrd
  config get|set|unset     # Konfig helprz
  doctor                   # Helth cheks + kwik fikses
  dashboard                # Oepn web dashbord
  status                   # Sho seshun helth
  health                   # Fetch Gatewei helth
  channels list|status|add|remove|login|logout
  models list|status|set|auth
  agents list|add|delete|bind|unbind
  sessions                 # List seshunz
  gateway status|install|start|stop|restart|run
  logs                     # Tael Gatewei logz
  nodes status|describe|camera|canvas
  cron list|add|edit|rm|enable|disable|run
  plugins list|install|enable|disable
  skills list|info|check
  memory status|index|search
  browser status|start|stop|screenshot|snapshot
  reset                    # Reset konfig/staet
  uninstall                # Uninstol Gatewei servis + daeta

📋 Konfig Referens

Kee konfigurayshun sekshunz:

• agents.defaults — Defaalt ajent setingz
• agents.list[] — Multi-ajent konfigurayshunz
• channels.* — Chanul-spesifik konfig
• gateway.* — Gatewei servis setingz
• models.providers.* — Modl providr konfig
• tools.* — Tool poliseez n setingz
• skills.* — Skil konfigurayshun
• plugins.* — Plugin konfig
• session.* — Seshun manijment
• messages.* — Mesij formating

📝 Templats

Defaalt werkspays templats:

• AGENTS.md — Oprayting instrukshunz
• TOOLS.md — Tool yoosij guidence
• USER.md — Yuzr profiel
• BOOTSTRAP.md — Furst-run setup ritual
• HEARTBEAT.md — Hartbeet instrukshunz
• SOUL.md — Pursonalitee konfigurayshun