OcuTalon

Your integrations already tell you when something breaks, usually fifty times. OcuTalon reads the failures, works out the one cause, proposes the fix with a dry run, and only interrupts you when something needs you. Nothing risky runs without your yes: fixed rules that the model can’t change decide what is risky, and every approval lands in the IRIS audit log. Every decision is in Visual Trace with its reasons and cost. Without a model it fails safe: it tells you everything and claims nothing.

Watch the 35-second teaser: https://youtu.be/wycbyfnXFMU

Try it in two minutes

Start with the online demo, at https://demo.ocutalon.com (nothing to install, and no Early Access image needed). Its sign-in details are on the splash screen. The splash screen also shows a read-only Visual Trace account, for opening Visual Trace in the portal yourself; on the demo, the trace links on the page open Visual Trace without a second sign-in.

To run OcuTalon on your own machine instead:

1. Load the IRIS for Health AI Hub Early Access image into Docker: build 154, or build 109, which the download portal now offers (where to get it).
2. Clone this repository and run ./install.sh in its folder (what it does). With build 109, follow Start it with build 109 instead.
3. Sign in at http://localhost:52773/ocutalon/ with user name ocutalon and password ocutalon (more on signing in).
4. Follow the demo guide at the top of the page.

What’s interesting

OcuTalon runs as an IRIS Interoperability production, so the agent is an Interoperability workflow, and its work shows in Visual Trace, the tool you already use for your feeds. For each item that arrives, an IRIS AI Hub agent makes one attention decision, with its reasons and cost. Nothing risky runs without your yes: you get a dry run with counts first, you approve in the web chat, and every answer lands in the IRIS audit log. It was built this way so that you can audit and debug your assistant in the same place as the rest of your integrations.

What you can use it for

• The partner feed that breaks at 2am. A trading partner changes a date format, and 50 orders fail. Instead of 50 alerts, you get one notice: the cause in plain English, the fix, and a dry run that shows what it would resend. Nothing is resent until you approve, and then OcuTalon reports how many orders went through. Break the feed in the online demo plays this out in two minutes. On your own install you can also approve it in Telegram on your phone, without a laptop or the Management Portal (how to set up Telegram).
• “Only tell me if something needs me.” Ask OcuTalon in plain words to watch a production, and it stays quiet until something needs you. Failures with one cause become one incident, not a flood, and when you ask whether everything is fine, it never gives a false all-clear. It also tells you once when a production stops or one of its items is disabled.
• An AI decision step you can audit, in your own production.

How you talk to it

The web chat page is OcuTalon on every install. Demo mode adds four parts to it for trying OcuTalon out: the demo guide, Break the feed, the Simulated phone and the Simulated mailbox.

Demo mode is on in the online demo, and on the Docker install until an admin switches it off (Demo mode). Email comes in a later release.

In demo mode, the Demo view switch in the header hides those four parts. With it off, you see what the page has on your own install:

What OcuTalon does

OcuTalon is a personal assistant that runs inside InterSystems IRIS. For every item that reaches it, OcuTalon makes one attention decision. The decision has one of four outcomes:

• Ignore: Recorded; nobody notified.
• Digest: Saved for later; nobody notified now.
• Tell now: Needs you now.
• Act: OcuTalon took or requested an action.

Each decision shows its reasons, its confidence and its cost.

• Chat on a live page. You talk to OcuTalon in a web page that updates as things happen. A reply shows its decision and a link that opens it in Visual Trace.

  

• Break the feed. In demo mode the page has a Break the feed button. It makes a simulated partner send 50 orders in a changed date format into the Orders production, where they fail for real. OcuTalon groups the failures into one incident, explains the cause in plain English and proposes a fix with a dry run: how many orders it would resend, with an example. Nothing is resent until you press Approve in the chat or on the page’s Simulated phone. Reject leaves everything as it was. After an approval, OcuTalon reports how many orders went through.

  

  

• Watching a production. Ask in plain words, for example “Watch the Orders production and only tell me if something needs me.” To stop, say “Stop watching Orders.”

• Reminders. Ask in plain words, for example “Remind me in 1 minute to stretch.” A reminder arrives on time, survives a restart, and can be listed and cancelled in the chat.

With a model, and without one. OcuTalon uses Claude Haiku 5.5 by default. With no model key, or when the model can’t give a usable answer, it falls back to fixed rules and says so on the page and in Visual Trace.

Install it yourself

What you need

• Docker Desktop (macOS, or Windows with a WSL 2 shell), or Docker Engine with the Compose plugin (Linux).
• Docker Compose 2.24 or later. docker compose version shows yours; how to install it.
• git, to clone this repository.
• An arm64 or x64 CPU.

macOS and Linux are what OcuTalon’s author and its automated tests use. On Windows, work in a WSL 2 shell; the automated tests do not cover that.

Get the image

OcuTalon 1.0.0 is built and tested on IRIS for Health AI Hub Early Access build 154 (irishealth-community:2026.3.0AI.154.0). The InterSystems Early Access Program portal now offers build 109 (irishealth-community:2027.1.0AI.109.0) in its place: https://evaluation.intersystems.com/Eval/early-access/AIHub

OcuTalon 1.0.0 also runs unchanged on build 109: its install, production and test checks and the demo guide pass on it. In this release, ./install.sh looks only for build 154, so with build 109, start OcuTalon as Start it with build 109 shows.

Choose the file that ends in docker.tar.gz for your CPU: arm64 for Apple silicon and ARM Linux, x64 for Intel or AMD. docker info --format '{{.Architecture}}' tells which one Docker runs: aarch64 for arm64, x86_64 for x64.

Then load it:

docker load -i <the archive file>

Start it with the install script

The install script needs build 154. With build 109, see Start it with build 109.

git clone https://github.com/jbrandtmse/OcuTalon.git
cd OcuTalon
./install.sh

The script checks that Docker and Docker Compose work and that a build 154 image for your CPU is loaded. It gives the image the name OcuTalon builds from, creates .env from .env.example when there is none, and starts OcuTalon with docker compose up -d. It shows a progress line every 10 seconds, waits up to 15 minutes, and prints the address and the sign-in details. When a check fails, it says what is wrong and the exact fix, and changes nothing.

When OcuTalon is ready, it prints:

OcuTalon is ready after <time>.
Open:      http://localhost:52773/ocutalon/
User:      ocutalon
Password:  ocutalon

Start it by hand

Without the script, give the loaded image the name OcuTalon builds from, then start it. docker load printed the loaded image’s name; for the IRIS for Health archive it is docker.iscinternal.com/docker-intersystems/intersystems/irishealth-community:2026.3.0AI.154.0.

docker tag <the name docker load printed> ocutalon-iris-base:2026.3.0AI.154.0
cp .env.example .env
docker compose up -d

The cp step is optional: without .env, OcuTalon starts with no model key (Set a model key). Skip it when .env already exists, because cp would replace that file and the key in it.

Start it with build 109

docker load printed the loaded image’s name; for the IRIS for Health archive it is docker.iscinternal.com/docker-intersystems/intersystems/irishealth-community:2027.1.0AI.109.0. Name it in .env as IRIS_IMAGE, so that OcuTalon builds from it, then start OcuTalon:

git clone https://github.com/jbrandtmse/OcuTalon.git
cd OcuTalon
cp .env.example .env
echo 'IRIS_IMAGE=<the name docker load printed>' >> .env
docker compose up -d

Skip the cp step when .env already exists. Keep the IRIS_IMAGE line in .env, because every docker compose up -d reads it, an update included. Then check that it is ready and sign in.

The IRIS (non-Health) image

OcuTalon also runs on the plain IRIS AI Hub build 154 image (iris-community:2026.3.0AI.154.0). It differs from IRIS for Health only by the HealthShare libraries and the HSCUSTOM namespace. It is supported and verified on ARM64. OcuTalon’s automated tests use only the IRIS for Health image. Build 109’s plain IRIS image has not been tested.

./install.sh uses the plain IRIS image when no IRIS for Health image for your CPU is loaded. By hand, give it the same name, then start as above:

docker tag <the name docker load printed for the iris-community image> ocutalon-iris-base:2026.3.0AI.154.0
docker compose up -d

Check that it is ready

docker compose ps

OcuTalon is ready when the STATUS of the iris service ends in (healthy), for example Up About a minute (healthy). Then open http://localhost:52773/ocutalon/.

The first start took 47 to 78 seconds in five measurements on an Apple silicon Mac, and about 3 minutes (160 seconds) on an x64 Linux machine with 4 CPUs. The install script waits up to 15 minutes. A slower machine can take longer; run docker compose ps again to see.

Install it with IPM

To install OcuTalon into an IRIS instance you already run (AI Hub build 154 with IPM 0.10.10), use the InterSystems Package Manager. In an IRIS terminal in %SYS, point IPM at the community package registry:

zpm "enable -community"

This command first removes the package repositories that are already set up in %SYS, so note any you use before you run it.

Then open an IRIS terminal in USER, an Interoperability-enabled namespace, and run:

zpm "install ocutalon"

This first run ends early by design: it creates the namespace OCUTALON and stops with a line that says what to do next. Switch to OCUTALON and run the same command:

zn "OCUTALON"
zpm "install ocutalon"

This second run installs OcuTalon with demo mode off. Install OcuTalon with IPM shows the output of both runs, and the install from the package folder, for developers.

Set a model key

OcuTalon uses Anthropic’s Claude models. The default model is Claude Haiku 5.5. To give it a key:

1. Create an API key at https://console.anthropic.com.
2. Copy .env.example to .env (./install.sh already did). Git ignores .env, so the key is never committed.
3. In .env, set ANTHROPIC_API_KEY=<your key>.
4. Apply it: docker compose up -d --force-recreate. This is what the page means by “restart OcuTalon”.

Without a key, OcuTalon still starts. Every decision uses fixed rules, and the page shows a notice that says so.

Sign in

Open http://localhost:52773/ocutalon/ and sign in with the README account:

• User name: ocutalon
• Password: ocutalon

OcuTalon does not ask you to change the password when you first sign in.

Change the README account’s password after your first sign-in. OcuTalon publishes its web port on every network interface of your machine, so the IRIS Management Portal can be reached from your LAN until the passwords of the default IRIS accounts and of the README account are changed. How to change the README account’s password. The user name stays ocutalon. How to change the default IRIS accounts’ passwords.

Visual Trace. A trace link on the page opens the IRIS Management Portal in a new tab. The first time, the page shows “Sign in to Visual Trace”, and the portal may ask you to sign in with the same account, which holds the trace role.

Telegram

Telegram is optional, and these steps are for your own install. With a bot of your own, OcuTalon sends its notices, reminders and approval requests to your phone, and you can approve or reject a fix with the “Approve” and “Reject” buttons in the Telegram chat. Without a bot token, everything else works and the page shows “Telegram not set up”.

1. In Telegram, open @BotFather, send /newbot and follow its steps. It gives you the bot’s token.
2. Turn groups off for the bot: send /setjoingroups to @BotFather, choose your bot, then Disable. OcuTalon answers only private chats.
3. In .env, set TELEGRAM_BOT_TOKEN=<your token>. Copy .env.example to .env first if there is no .env (./install.sh already did). Git ignores .env, so the token is never committed.
4. Restart OcuTalon, from the OcuTalon folder: docker compose up -d --force-recreate.
5. When docker compose ps shows the iris service (healthy) again, open http://localhost:52773/ocutalon/ and sign in if it asks. In the Status section (in a narrower window, open it with the Status button at the top of the page), the Telegram card shows a QR code. Scan it with your phone’s camera, then tap Start in Telegram. The card then shows “Telegram paired” with your Telegram name, and an “Unpair” button. If it still says “Telegram not set up”, check the token in .env and repeat step 4.

Each OcuTalon needs its own bot. If another process polls the same bot, OcuTalon pauses Telegram and tries again after 5 minutes.

Stop, start and update

• Stop: docker compose down. Your data stays on a Docker volume. Do not add -v: that deletes the volume.
• Start again: docker compose up -d.
• Update: git pull, then docker compose up -d --build. Your data and the changed password stay.

Troubleshooting

These are the usual causes and fixes. Most entries are messages that ./install.sh prints when a check or the start fails; the last two are about the page.

“No IRIS build 154 image is loaded in Docker”: download the archive for your CPU (Get the image), load it with docker load -i <the archive file>, then run ./install.sh. With build 109, follow Start it with build 109 instead of running ./install.sh.

“The IRIS build 154 image that is loaded is for another CPU than this machine’s”: download and load the archive for your CPU. docker info --format '{{.Architecture}}' tells which one Docker runs. If the message says that ocutalon-iris-base:2026.3.0AI.154.0 exists but is for another CPU, point the name at the right image: docker tag <the loaded image's name> ocutalon-iris-base:2026.3.0AI.154.0.

“Docker is not installed (the docker command was not found)”: install Docker Desktop (macOS, or Windows with WSL 2) or Docker Engine (Linux), then run ./install.sh.

“Docker is installed, but it is not running, or this user cannot reach it”: start Docker Desktop. On Linux, run sudo systemctl start docker. If Docker is running, add your user to the docker group with sudo usermod -aG docker $USER, then log out and in again.

“Docker Compose is missing” or “Docker Compose … is too old”: install the Compose plugin, version 2.24 or later. It comes with Docker Desktop; on Linux, install the docker-compose-plugin package. The old docker-compose command (version 1) does not work with OcuTalon.

“Docker Compose could not start OcuTalon”: the messages above it say why. Most often the web port 52773 is taken. Set another port in .env with OCUTALON_WEB_PORT=<port>, run docker compose up -d, and open that port instead of 52773. To read the container’s log, run docker compose logs iris.

“OcuTalon stopped before it was ready”: run docker compose logs iris to read what happened.

“OcuTalon was not ready after 15 min …”: run docker compose logs iris. For what the start did, run docker compose exec iris cat /durable/ocutalon-after-start.log: the lines that begin with STEP name each install step, and a start that went well has a line that begins with RESULT OK. A slow machine can take longer than 15 minutes, so run docker compose ps again before you give up.

The page says “OcuTalon has no model key”: see Set a model key. Until you add one, every decision uses fixed rules.

The sign-in is refused: use user name ocutalon and password ocutalon, or the new password if you changed it. To set a new one, see Change the README account’s password.

For admins and developers

Demo mode

Demo mode is on for the Docker install. It adds the demo guide, the Simulated phone and mailbox, and Break the feed, and it runs the Orders production in the namespace OCUORDERS.

An admin switches it from a terminal in the OCUTALON namespace:

docker compose exec iris iris session IRIS -U OCUTALON

At the OCUTALON> prompt, run the line below with 1 to switch demo mode on or 0 to switch it off, then halt:

do ##class(OcuTalon.Core.Admin).SetDemoMode(<0 or 1>)

The line needs the OcuTalonAdmin role or %All. The container’s operating system login (irisowner) holds %All, so it works from that terminal. The answer is one plain-English line:

• On: “Demo mode is on. The Orders production runs in namespace OCUORDERS. Reload the OcuTalon page in a minute to see the change.”
• Off: “Demo mode is off. The Orders production is stopped and namespace OCUORDERS is removed. Reload the OcuTalon page in a minute to see the change.”

When OCUORDERS holds something OcuTalon did not create, switching demo mode off keeps the namespace, and the answer starts with “Demo mode is off.” and then says, with {what was kept} naming what OcuTalon found:

OcuTalon left the OCUORDERS namespace in place because it holds {what was kept}. To remove it, delete the namespace OCUORDERS and its databases OCUORDERS_CODE and OCUORDERS_DATA in the Management Portal.

A change takes up to a minute to show on the page.

Change the README account’s password

Open a terminal in the %SYS namespace:

docker compose exec iris iris session IRIS -U %SYS

At the %SYS> prompt, run the line below with your new password in place of <new password> (keep the quotation marks), then halt:

kill p set p("Password")="<new password>" write ##class(Security.Users).Modify("ocutalon",.p)

It prints 1 when the password was changed; if it prints anything else, the password was not changed. If your new password contains a double quotation mark, write it twice. Sign in again with the new password. The user name stays ocutalon.

Change the default IRIS accounts’ passwords

IRIS also comes with predefined accounts, among them SuperUser and _SYSTEM, which hold every right, and Admin. Change their passwords in the Management Portal: open http://localhost:52773/csp/sys/UtilHome.csp and sign in as SuperUser (its first sign-in asks for a new password).

Then open System Administration, then Security, then Users. For _SYSTEM, Admin and any other enabled account you don’t use, choose its name, select Enter new password, enter a new password in Password and Password (confirm), and press Save.

Leave CSPSystem, the web gateway’s account, and the accounts marked for internal use as they are.

Repository layout

• src/ocutalon: OcuTalon’s classes: the production, its agents, the web service behind the page and the install steps.
• src/bridge: the bridge, the part that calls the AI Hub agents, checks each tool call before it runs, handles the approval requests and writes the audit entries.
• web: the web page (Angular) and its browser tests.
• docker: the image’s files and the checks and live tests in docker/tests.
• ci: the CI scripts and the model mock.
• eval: the recorded evaluation set.

Tests and CI

bash ci/checks.sh runs the checks that need no container, among them the check of this README. The GitHub Actions workflow in .github/workflows/ci.yml runs them and the web build on pushes and pull requests, and the browser tests and the IRIS tests on pushes and on pull requests from this repository’s own branches.

Credits and licences

Built with the BMAD Method and Claude Code. More about them: the BMAD Method and Claude Code.

OcuTalon is inspired by OpenClaw and is not affiliated with or endorsed by the OpenClaw Foundation.

OcuTalon is under the MIT License: https://github.com/jbrandtmse/OcuTalon/blob/main/LICENSE.

Third-party licence notices:

• The web page’s fonts (Inter, JetBrains Mono and Montserrat, under the SIL Open Font License) and its icons (Lucide, under the ISC licence) have their licence texts in https://github.com/jbrandtmse/OcuTalon/blob/main/web/public/assets/licenses.
• The web build writes the licence notices of its libraries to 3rdpartylicenses.txt, beside the built page.
• The IPM package manager in the image is under the MIT licence: docker/ipm/https://github.com/jbrandtmse/OcuTalon/blob/main/LICENSE.