Keural Duo
Installation, chat, routines, Telegram, computer use, and Mate & Morph for the standing agent that runs on your computer.
Duo is a standing agent that the desktop app installs on this computer (or on a connected DGX Spark). It runs in an isolated sandbox, you talk to it from Duo in the sidebar or from Telegram, and it runs the routines you have registered. It is based on NVIDIA NemoClaw and OpenClaw.
Duo is available only in the desktop app.
Installation
In Settings → Duo → Runtime, choose a model, then press Install on the line for where you want it to run. The install button is disabled if no model is selected or the disk has insufficient space.
Where it runs and requirements
| Where it runs | Requirements |
|---|---|
| This device (macOS) | Apple silicon, 16GB or more of memory. The container runtime is installed by the app itself, so Docker Desktop, Homebrew, and an administrator password are not required. |
| This device (Windows) | WSL 2. Press Prepare Windows once at first to install the required components. You may be asked to restart the PC or to allow administrator permission. If virtualization is turned off, turn it on in the BIOS. |
| Remote device (DGX Spark) | Connect Spark and start the model first. If the Spark firewall is on, enter the Spark account password once to open two ports (the password is not saved). |
Installation requires at least 20GB of disk space, and 40GB or more is recommended. If space is short, the install button is locked and "{need} GB required · {free} GB free" is shown.
Models
| Option | Description |
|---|---|
| On-device model | Uses the running model among the local models you downloaded. Shown as "{model} · same model as chat." |
| DGX Spark | The model running on the connected Spark. |
| Cloud | Duo models included in your plan. Shown only when you are signed in. |
| Gateway | Uses a model from a server connected in Settings → Models → Gateways. You need that server's address and API key. |
After installation, change the model on the Model line. Within the same type, switching is immediate with "Switch." When the type changes between local, cloud, and gateway, press Reinstall if the type changes. Reinstalling keeps your routines. To move to a different location, delete the current installation first, and then install in the other location.
Installation steps
The steps run in this order: check this device → prepare the container runtime → install NemoClaw → start the model (for cloud or gateway, prepare model access permission) → create the sandbox → set up Duo → check operation. The current step is shown on the button and in the progress card. If the message "This is taking a little while. Keep the app open." appears, do not close the app.
If installation stops, check the cause from the message on screen in When installation fails.
Duo in another account or workspace
Duo is one per device and belongs to the account and workspace where it was installed. If you sign in with another account or switch to another workspace, Duo in Settings shows as "Not installed," and the sidebar Duo and Mate & Morph are hidden. Pressing Install in that state shows a confirmation that the existing Duo and its conversations and routines will be deleted. Pressing Install new deletes the existing Duo and creates a new one. When you return to the original account or workspace, the existing Duo appears again.
If a previously installed Duo remains, it is cleaned up and then the new installation proceeds. If cleanup fails, the message "Could not delete the existing Duo. Install again." is shown.
When installation fails
If installation stops, an error message appears in Settings → Duo. Check the code in parentheses at the end of the message, if there is one. After fixing the cause, press Install again.
| Message on screen | Cause | Fix |
|---|---|---|
Installation stopped: not enough disk space. Make sure at least {need} GB free, then try again | The disk that holds your home folder has less than 20GB free. | Free up 20GB or more (40GB recommended). |
| Couldn't prepare the install. Check your internet connection | The install files could not be downloaded. A company firewall or proxy is often the cause. | Check your internet connection. On a company network, ask IT to allow the addresses in Download sources. |
| Could not delete the previous Duo. Install again. | A Duo left over on this device could not be cleaned up. | Quit the app completely, reopen it, and press Install. If it keeps failing, check the same message on the macOS tab. |
| A Duo from another account or workspace is on this device. Installing removes it. | The Duo on this device belongs to another account or workspace. | Press Install new to delete that Duo and install. To keep using the existing Duo, switch to the original account or workspace. |
| Your plan doesn't include cloud models for Duo. | The current workspace plan does not include cloud Duo. | Change the model to This device model, DGX Spark, or gateway, or check your plan. |
| Sign in to use cloud models. | You are signed out. | Sign in and install again. |
| The model isn't running. Start it, then apply again. | The on-device model is not running. | Run the model in Settings → Models, then install. |
| Taking longer than usual. Keep the app open. | The first install has many files to download. | Keep the app open and wait. On a laptop, prevent it from going to sleep. |
If the problem persists, contact support in Settings → Support. Include the message on screen, the code in parentheses, and the device type (macOS, Windows, or Spark).
Duo screen in Settings
| Section | Content |
|---|---|
| Status | "Running on {location}" · stopped · starting · not installed · no server (when the Spark connection is lost) |
| Runtime | Model selection, Start, Stop, and Delete on the this device / remote device lines, sandbox ID, and NemoClaw version |
| Chat apps | Telegram connection |
| Connections | GitHub, web search |
| Computer use | Permissions, readable folders, rules before action, always-allowed apps, Mate & Morph |
| Conversation memory | Context usage, conversation compaction, new conversation |
| New features (Windows) | Windows computer connection, shared folders, application access check, recent tasks |
While installation, model switching, applying chat apps, or deletion is in progress, other sections are locked. An operating system confirmation appears when you turn on computer use or widen the rules.
Conversation
Press Duo in the sidebar (not shown in code mode). While the connection is lost, messages you send are shown as "{n} waiting to send" and delivered when the connection is restored. Sending /new asks whether to start a new conversation.
When you turn on Duo info at the top, the following cards are shown in the side panel.
| Card | Content |
|---|---|
| Now | The task in progress or resting, elapsed time, and the tools used |
| Duo settings have changed | Shown when the sandbox settings differ from the last confirmed state. Shows the changed areas (chat apps and who can talk to it · tools and permissions · connected services · model connection · other). If you made the change yourself, press Accept changes. |
| Sandbox | Ready or error, model response normal or no response, GPU (CUDA) use, and capacity |
| Model | Model name, location (this device · DGX Spark · cloud), and context usage |
| Routines | See Routines below. |
| Connections · Telegram | Connection summary. Press to go to settings. |
| Workspace files | Files that Duo created in the sandbox work folder |
Press Background tasks to view the list of sub-agents that Duo is running.
Conversation memory
Under Settings → Duo → Conversation memory, check the "context in use" as a token count and percentage. Use Compact to shorten the conversation, or New to start a new conversation. The existing conversation is kept. If Duo is working, you can do this after the work finishes. If the message "The conversation is too long for the model to process, so Duo could not answer." appears, compact the conversation or start a new one.
Routines
Tell Duo something like "Every morning at 9, do …," and Duo proposes it. The Create this routine? card (task, schedule, and location) appears. Press Create routine to register it. Edits and deletions are also confirmed with the same card.
| Item | Content |
|---|---|
| Schedule | Once (up to 365 days ahead) · daily · weekdays · weekly · every N minutes (5 to 1,440 minutes) |
| Where it runs | A Duo conversation in the Keural app, or Telegram delivery |
| Count | 10 active, 50 in total |
| Expiration | 7 days by default, up to 30 days. After that, "Expired." |
| Missed | If the app was closed and the routine is more than 10 minutes late, it does not run and is marked "Missed." |
| Failure | After 3 consecutive failures, it is marked "Paused due to failure." |
In the Routines card in the Duo info panel, turn routines on and off, and use More to Run now or Delete. The next run time and status (sent · missed · failed · paused · expired) are shown for each row. Routine results are delivered to the Duo conversation or to Telegram, and a desktop notification appears (Run now runs without a notification). Routines run only while the app is open.
Chat apps (Telegram)
Follow the guide under Settings → Duo → Chat apps → Telegram → Connect.
- Open @BotFather in Telegram, send
/newbot, and choose a name and a username for the bot. - Paste the Bot token you received from BotFather and press Confirm. If the token leaks, anyone can control the bot, so do not share it.
- Scan the QR code with your phone to open the bot, and press Start. If there is no response, send the code shown on screen to the bot.
- When "Only
{name}can chat with the bot in direct messages" appears, press Add, and then press Apply.
After you apply, Duo restarts (conversations and files are kept). Messages you send from your phone then appear in the Duo conversation as "Sent from Telegram." Only the one person who connected can chat with the bot in direct messages. To disconnect, press Disconnect, and then Apply. If you connect Telegram, routine approvals are also received in Telegram.
A BotFather token can be used on only one device (Duo) per account. To connect another device, remove the connection from the existing device first, and then register the token again.
Approval of app actions is handled only in the Keural app window, even for conversations started in Telegram.
Connections
Configure this under Settings → Duo → Connect.
| Service | Method |
|---|---|
| GitHub | Paste a Personal access token (a link to create a fine-grained token is provided) and confirm, or use Continue with GitHub CLI to use the gh sign-in on this computer. If the CLI is not installed, an installation link appears. If you are not signed in, a sign-in window opens. When you connect or change the connection, Duo restarts. |
| Web search | Duo uses the method selected under Settings → General → Web search (quick search · Keural search · Tavily, Brave, or SearXNG from your own search service). Computer use must be turned on. |
Tokens and keys are passed to the app only once when you confirm them, and they are cleared from the screen right away.
Computer use
Turn on Settings → Duo → Computer use → Allow Duo to use this computer, and Duo can open and use apps on this computer, read the folders you specify, and create routines. When you turn it on, Duo restarts for about a minute.
| Item | Content |
|---|---|
| macOS permissions | Accessibility (click and type in apps) and Screen Recording (view the screen). If not allowed, press Open System Settings. |
| Folders Duo can read | Only the folders you add with Add folder. Broad folders such as the whole home folder or system folders cannot be added. |
| Before Duo acts | Ask every time (default) · Act without asking · Hand off to you. Switching to Act without asking asks you once more to confirm. |
| Always-allowed apps | The list of apps you chose Always allow in an approval window. Press × to remove an app. |
Even with Act without asking or Always allow, sensitive steps such as sending, deleting, overwriting, paying, submitting, signing in, publishing, and cancelling, and keys such as Enter, Backspace, and ⌘Q, always ask first.
When Duo is waiting for approval, "Duo is waiting for approval" appears above the input box. Press Confirm to open the approval window, and choose Decline, Allow once, or Always allow. Mate & Morph also shows "Waiting for approval." Approvals can be given only in this window.
Duo opens only the search results and links it returns without asking. For an address that Duo typed or changed itself, the approval window shows the full address and asks for approval.
Mate & Morph
This is Duo's desktop character. Turn on Settings → Duo → Computer use → Mate & Morph → Show on desktop, and then choose the Character (Mate · Morph · both) and Size (Small · Medium · Large).
- It is shown only while Duo is running and the conversation is ready. It is hidden if you switch to another account or workspace, or if your plan does not allow Duo.
- Click the character once to open an input field, and double-click quickly to open the app. The status (idle · working · done · blocked · input needed · waiting for approval) and the reason for the last failed answer appear next to the character.
- Right-click menu: Hide · Mark as read · Open Duo · Duo settings. The menu bar (tray) menu also has Show/Hide Mate & Morph.
Windows
Duo on Windows runs in the WSL distribution and supports conversations, routines, Telegram, approvals, Mate & Morph, and computer use in the same way as macOS. App operation uses Windows UI automation, so some apps and secure windows such as password fields, UAC, and terminals are handed to you rather than operated by Duo.
Under Settings → Duo → New features (Windows computer), check the Duo connection, Shared folders (Duo reads only the folders you select), Application access, and Recent tasks. On Windows, Duo can also do Software installation (only with exact package IDs) and Wi‑Fi connection (saved profiles). Sending, deleting, overwriting, installing, and network changes always ask first.
Deletion
Under Settings → Duo → Runtime, press Delete on the installed location line, and then Delete in the confirmation "Delete Keural Duo from this device?" The sandbox, conversation history, routines, and workspace files are deleted. On macOS, the Duo-only container VM is also deleted. Duo on DGX Spark can be deleted only while Spark is connected.
Common messages
| Message | Meaning |
|---|---|
| Duo is not running | In Settings → Duo, press Start. |
| The latest desktop app is required | Update the app. |
| The model is not running. Start the model, then apply again. | The local or Spark model is off. Start the model first. |
| The model connection was lost. Check your sign-in status. | Access to the cloud model Duo was lost. Sign in again. |
| Duo cannot be used on this workspace's plan. | Your plan does not include cloud model Duo. Switch to a local model or check your plan. |
| There is a Duo from another account or another workspace. | Installing will delete that Duo. Switch back to the original account or workspace to use it again. |
| Could not delete the existing Duo. Install again. | Cleanup of a previously installed Duo failed. Press install again. |
IT administrator details
Requirements
| Where it runs | Specification |
|---|---|
| macOS | Apple silicon (arm64), 16GB or more of memory. The virtual machine for Duo (Colima, vz) uses 4 CPUs, 9GiB of memory, and a 40GiB disk (it takes up only the space it needs). |
| Windows | WSL 2 (kernel 5.15 or later), x64 or ARM64. Installs Ubuntu 24.04 as the distribution named Keural-Duo and uses rootless Podman inside it. Docker Desktop is not required. |
| DGX Spark | Docker running, with 20GB of free disk and 8GB or more of available memory |
| Common | 20GB or more of free space on the disk that holds the home folder (40GB recommended) |
On Windows, installation uses networkingMode=nat under [wsl2] in %USERPROFILE%\.wslconfig. PCs that use mirrored networking (mirrored) are not installed.
Installation locations
| Where it runs | Path |
|---|---|
| macOS runtime | ~/.keural-runtime/ (Colima, Lima, Docker CLI, logs) |
| macOS auto-start | ~/Library/LaunchAgents/kr.mkd.keural-duo-colima.plist, kr.mkd.keural-duo-gateway.plist, kr.mkd.keural-duo-sweeper.plist |
| NemoClaw CLI | ~/.local/bin/nemoclaw |
| Windows | WSL distribution Keural-Duo |
| App records | In the app data folder: keural-duo@<server>.json, keural-duo-routines@<server>.json, keural-duo-rules@<server>.json |
| Logs | ~/.keural/logs/, ~/.keural-runtime/colima.log and gateway.log, and keural-duo-install.log in the app data folder |
Download sources
Allow the following addresses in your firewall or proxy. Downloaded files are fixed versions and are verified with SHA-256.
| Address | What is downloaded |
|---|---|
github.com | Colima v0.10.3, Lima v2.2.1, buildx v0.38.2 (macOS), Podman tools (Windows) |
download.docker.com | Docker CLI 29.9.3 (macOS) |
www.nvidia.com | NemoClaw installation script (v0.0.134) |
ghcr.io | OpenClaw sandbox image |
api.telegram.org | Telegram connection |
Keural servers (api.keural.ai, etc.) | Cloud models, sign-in |
If you use web search or the GitHub connection, also allow api.tavily.com, api.search.brave.com, api.github.com, and api.githubcopilot.com.
Network and ports
| Location | Port | Use |
|---|---|---|
| macOS | 127.0.0.1:8080 | OpenShell gateway |
| macOS · Windows | 127.0.0.1:8766 | On-device model server (on Windows, a relay inside WSL). If it conflicts, 8768 is used. |
| DGX Spark | An unused port from 18080 to 18099 | Spark-only gateway |
| DGX Spark | 18081 | Relay from the sandbox to the Spark model (8000) |
| DGX Spark | 22 | SSH connection from the app |
If the ufw firewall is on for Spark, installation opens two ports, the gateway and the relay. You are asked to enter the Spark account password once at that point.
The sandbox does not access the internet directly. The app handles web search and page reading on its behalf, and GitHub is connected read-only.
Model addresses
| Model | Address the sandbox calls |
|---|---|
| On-device model | http://localhost:<port>/v1. Default model qwen3-8-27b, context 262,144 |
| DGX Spark model | 127.0.0.1:8000/v1 on Spark, through the Spark relay |
| Cloud model | /core/v1/bot/v1 on the Keural server. Uses a token issued for each Duo. |
| Gateway | The address of the server connected in Settings → Models → Gateways |
A gateway address may be any address if it uses https. If it uses http, only private IP addresses or internal names (.local, .lan, .internal, .intranet, .home.arpa, or names without a dot) are accepted. Addresses that contain localhost or user:pass@ are not accepted.
Telegram
- The bot token is issued by BotFather with
/newbot. The format isnumber:alphanumeric. - After a connection code is created, open the bot on your phone within 10 minutes and send the first message within 5 minutes. The account that sends the first message is allowed.
- Group conversations do not receive replies.
Routine limits
| Item | Value |
|---|---|
| Check interval | Looks for routines to run every 30 seconds. |
| Missed | If more than 10 minutes late, it does not run and is marked as missed. |
| Pause | Stops after 3 consecutive failures. |
| Repeat interval | 5 to 1,440 minutes |
| One-time run | Up to 365 days ahead |
| Expiration | 7 days by default, up to 30 days |
| Count | 10 routines turned on, 50 in total |
| Time zone | The time zone of the computer that created the routine |
Folder addition rules
The following folders cannot be added.
| Category | Folders |
|---|---|
| Common | The disk root, the home folder itself, and folders above it |
| Under home | .ssh, .aws, .gnupg, .kube, .docker, .config, Library, .Trash, AppData |
| macOS | /System, /Library, /usr, /bin, /sbin, /etc, /var, /private, /dev, /Volumes, /Applications, /opt, /cores |
| Windows | Windows, Program Files, Program Files (x86), ProgramData |
Computer use permissions
| OS | Required permissions |
|---|---|
| macOS | Accessibility and Screen Recording under System Settings → Privacy & Security |
| Windows | No separate permission. Uses Windows UI automation. |
Buttons such as send, delete, pay, purchase, submit, sign in, transfer, publish, and cancel, and keys such as Enter, Delete, closing a window, and quitting an app, are treated as sensitive steps and are confirmed each time.
What is deleted on uninstall
Pressing Delete removes the sandbox, the Duo conversation history, routines, Telegram, GitHub, and search connections, and the cloud model token. If no other Duo exists on this device, macOS also removes ~/.keural-runtime/ and the auto-start entries. Mate & Morph settings and the Spark connection record are kept.