Repository navigation
Yumak Bot 0.3.0
Safety
- The auto review (the "review" approval level) reads only the person's own words: their latest messages in the
conversation, the instructions saved on a routine, or, for work another bot handed over, the request it started from.
A webhook's payload, a routine's last report, another bot's message or a quoted reply no longer counts as what the
person asked for. To let a step run, the reviewer must quote those words, and the server checks the quote is really
there; the note in the conversation keeps the quote. Work with no request from the person behind it goes to a card. - Memory changes a bot asks for while nobody watches (a routine's run, another bot's request) no longer take effect at
once: they wait under "Waiting for approval" in the memory settings, and the Today page counts them. The person
accepts or rejects each one, or all at once; a change asked for twice waits once. A bot the person is talking to still
keeps its memory itself. - What a connected app or a page in the bot's browser returns reaches the model in an
<outside-data>block that names
where it came from and says it is not instructions; a tag in the text that would end the block early is broken up.
Running it
- Sign a phone or another computer in with a one-time pairing code from a device already signed in (Settings →
Connection → Connect another device), instead of the password or the access key. A code works once, within five
minutes; wrong codes are slowed like wrong passwords. The web, the phone and the desktop app's server window take
it. - Docker Compose profiles reach the server from elsewhere without opening a port:
--profile cloudflareruns a
Cloudflare Tunnel,--profile tailscaleserves it on your tailnet with HTTPS. The tunnel reaches the server over a
network of its own with no way out. - Install on a fresh Ubuntu or Debian server with one command (
docker/install.sh, from curl or a provider's
cloud-init box): Docker, the.env, AppArmor, the firewall and HTTPS through Caddy (an sslip.io name when there is no
domain). Running it again, oryumakbot update, updates the installation and keeps its secrets and data. The
firewall rules come back after every reboot and Docker restart, and the server and computer images are published
for amd64 and arm64 on each version, so a server pulls them instead of building them.
Connections and models
- Sign in with your ChatGPT plan instead of an OpenAI API key, through OpenAI's "Sign in with ChatGPT", which lets an
app use a person's plan with its name on the consent page. On the computer that runs the server the sign-in comes
back by itself; on a server elsewhere you paste the address the browser ended on. - Sign in with your GitHub Copilot plan with a code typed on GitHub (GitHub Enterprise too); bots get the models your
plan opens. - Both are sealed like keys, refreshed when they run out, and signed out from the connection page. A saved API key for
the same provider comes first.
Chat
- A microphone button in the message box: speak instead of typing. With an OpenAI or Groq key saved, the recording is
written out by that provider (on the web and in the desktop app); without one, a browser with its own speech
recognition (Chrome, Safari) writes as you speak. The desktop app may use the microphone and nothing else of the
camera or screen; on macOS it asks first. On the phone, the keyboard's own dictation does the same. - Bots make pictures: with an OpenAI or xAI key saved,
image_createdraws what the bot describes and posts it as a
file in the chat (Telegram and WhatsApp too). The bot's own provider goes first; only bots with the internet on get
it, and asking bots open a card first. At most four pictures a turn. - Bots turn their pages into pictures:
page_to_imagerenders a page the bot wrote (a banner, a cover, a social card)
at the size it asks for and posts the PNG. It costs nothing and runs without a card. - A file or page a bot hands over while talking to another bot comes to its conversation with the person.
- When a bot's latest reply is in another of its conversations, the chat shows a bar that opens it.
Bots
- Each bot's settings have a Tools section: give it only the tools listed, or leave some out, named as approval cards
name them (Read,mcp__gmail__search_threads), with*at the end for a whole app. A small local model gets
room to work, and a bot stays to its job. Both engines leave the other tools out of the request, and one the engine
offers anyway is refused.
Chat apps
- Each bot can have a Telegram bot of its own: paste the token BotFather gives in the bot's settings, then open the
pairing link (or scan its QR code) and press Start. Only the paired Telegram account is read. What it writes goes to
the bot's main conversation; while the person last wrote from Telegram, replies, files, "typing…" and approval and
question cards (with buttons) go back there./stopstops the work in progress and/newstarts afresh. Routine
reports and cards from the bot's other conversations can come to Telegram too. - WhatsApp connects as a linked device, the way WhatsApp Web does, from the new "Chat apps" settings section: with a
separate bot number only the person's own number is read, and with their own number only "Message yourself". The
messages go to one chosen bot and/bot <name>switches it; cards come with numbered choices that a typed number
answers. Groups and other people's messages are never read. This uses Baileys, an unofficial WhatsApp client, so a
separate number is recommended. - Sign-in cards, secret answers and cards with several questions are left to the Yumak Bot app; passwords never go
through a chat app.
Memory
- A password, key or token a bot writes to memory is replaced with a marker before the note is saved, and the bot is
told to ask for the vault instead: memory reaches the model on every turn, so a secret there would leak with it. - Writing a note that is already saved, give or take case, spacing and closing punctuation, makes no second copy.
- Each note reaches the bot with the day it was last written, so of two notes that disagree it can trust the newer.
- When memory outgrows the prompt, the notes a bot wrote, changed or looked up most recently go in, rather than the
newest ones. An old note a bot keeps finding by search stays in the prompt, and one nobody needed makes room. A
search with a query and a site the bot opens count as looking a note up; being in the prompt does not. - The memory screen lists the notes no bot uses: nobody changed them and no bot looked them up in 30 days, and no bot reads them on
every turn. They can be deleted one by one or all at once; a note a bot uses again before that stays. Today shows
how many there are and opens the memory screen from there.
Routines
- A routine can wait on an app: before each run it calls a read-only tool of a connected app (unread mail, open
issues) without the AI, and the bot runs only when the answer changed, with the new answer. A quiet tick costs
nothing. Bots set it up when asked ("tell me when a new invoice email arrives"); the routine screen shows the check
and removes it. Only a tool that reads, of an app open to the bot, can be a check. - A routine pre-check on the usage page, on the web, the desktop and the phone: before a run that a watched page, an app's check or a webhook call started, the
cheapest Claude model says whether the run has anything new to work on (only page noise changed, an event the
routine does not care about, nothing beyond the last report). "Watch" only records what it said, beside the run and
as a total on the usage page with what those runs cost; "On" skips such runs with the reason before the bot starts.
When it is unsure or fails, the run goes ahead, and reminders always run. It is off by default. - A watched page keeps its last text, so the pre-check reads the sentences that were removed and added instead of the
whole page. - A routine's report lands in the bot's main chat under a label that opens the run's steps, and the bot reads the
reports that came since its last turn there. Routine conversations leave the list unless a card waits in them or
they are pinned. - Bots set the model a routine runs with, and the approval card names it.
- The red mark of a failed routine opens that routine at its latest runs, and goes away once the person has seen the
failure.
Browser
- A "Just a moment..." page that clears by itself no longer reaches the bot: opening a site waits for it, reloading
once, before the bot reads the page. When a site still shows a check a person has to answer, or turns the browser
away, the bot is told so plainly: hand the step to the person with Take control, or use another source. It is
never to get past a check itself. - The bots' browsers can go out through the person's own computer (Settings, one switch for the server): sites that
refuse sign-ins from a datacenter see the home connection while the desktop app is connected, and the server's
while that computer is off. The desktop app reaches only web ports on public addresses, so the server never reaches
the person's own machine or home network. The bots' commands still go out from the server.
Backups
- A full backup in one file, sealed with a password of your choosing (scrypt and AES-256-GCM): the bots,
conversations, memory, routines, skills, connections, the bots' folders, and the vault key the saved logins need.
Download it under Settings → Import and backup, on the web, the desktop or the phone. - Restoring one, on the web or the desktop, replaces everything on the server with what the file holds, then starts the
server again. A wrong password, a damaged file or a backup from a newer version changes nothing, and a restore waits
until no bot is working. The folders it replaced stay beside the new ones as*.before-restoreuntil the next
restore. Who is signed in to the server stays signed in.
Apps
- The desktop app for Linux: an AppImage that updates itself, and a
.debfor Debian and Ubuntu, built by the release
workflow with the others. yumakbot://links open a bot, a conversation or a room in the desktop app from outside it (a bookmark, a dashboard,
a script). In the desktop app, "Copy a link to this conversation" copies one, and such a link pasted into a chat
opens the conversation in place.- The desktop app itself is called "Yumak Bot": the macOS menu bar and Dock, the Windows exe and shortcuts. macOS takes
the menu bar title from the app bundle, so the menu's own label did not reach it. The installer and update files
keep "YumakBot" in their names, and so do the data folder and the keychain entry. An app that updates itself keeps
its folder name; renamingYumakBot.apptoYumak Bot.appin Applications fixes the name the Dock shows. - On the phone, the bots' avatars look around and blink like on the web and the desktop.
Getting started
See the README for the desktop app, the phone app and running the server
with Docker.
License
Yumak Bot is source-available under the PolyForm Noncommercial License 1.0.0: free for any noncommercial use. Use by or for a business needs a commercial license; write to info@yumakbot.com.