◈ Sudoji Agent (macOS/Windows)

Installing on macOS or Windows

A native background agent for laptops and desktops — an "End User Device" (EUD) in the portal, distinct from a Linux server.

ℹ

This is a separate, smaller binary from the Linux @sudoji/cli covered in Installing the Agent — same account, different install and a different command set. See Command differences below before reaching for a command that only exists on Linux.

What it is

A single Go binary plus a launchd LaunchDaemon (macOS) that keeps a persistent connection to Sudoji so you can chat with this device from the portal, or run sudoji ask / sudoji chat locally. It shows up under End User Devices on the Devices page — a separate list from Servers.

Get an API key and download the installer

From the Devices page, click + EUD. Name the key (e.g. vinay-macbook) and create it — the page then shows your key and a .pkg download link, both shown once.

Install

Double-click the downloaded .pkg. It installs the binary to /usr/local/bin/sudoji and registers a LaunchDaemon at /Library/LaunchDaemons/io.sudoji.agent.plist — it will start immediately and sit waiting for credentials.

The daemon runs as root (LaunchDaemons on macOS always do), so it can only see credentials stored by a root login. A plain sudoji login writes to your own user's home directory instead — the daemon will never find it.

terminal

sudo sudoji login --key sudoji_sk_your_key_here

This does two things: stores the key where the daemon looks, then automatically restarts the daemon so it picks it up immediately — no separate restart step needed. Watch for the daemon's own recent log lines printed right after "credentials saved" as confirmation it's connecting.

✦

Credentials are stored in a plain file (/var/root/.sudoji/credentials for the daemon, mode 0600, root-only), not the macOS Keychain — a LaunchDaemon can't reliably read Keychain entries back, so this agent doesn't use it at all, on purpose.

Verify

Check the device appears online in the portal, or ask the daemon directly:

terminal

sudo launchctl list | grep sudoji     # should show io.sudoji.agent running
sudoji chat                            # interactive session, as your own user

⚠

sudoji chat and sudoji ask run as you, not root — they read credentials from your own user's home directory. If you only ever ran sudo sudoji login, interactive commands will 401 even though the daemon works fine. Run a second, plain sudoji login --key ... (no sudo) to authenticate your own user too.

Command differences from the Linux CLI

The full command reference at CLI Reference documents the Linux @sudoji/cli. This agent supports a smaller set:

sudoji login --key <key>Flag is --key here, not --paste

sudoji logoutSame as Linux

sudoji whoamiShows the stored profile/masked key

sudoji ask <question>Same as Linux

sudoji chat --mode --thread--thread, not --resume/--title

sudoji tool knowmeOnly tool implemented — no exportconfig

sudoji daemonNo flags besides --server/--profile

⚠

sudoji doctor, sudoji context, sudoji logs, sudoji keys, and sudoji do are Linux-CLI-only — they don't exist on this agent and will error as an unknown command.

Uninstalling

There's no uninstaller bundled in the .pkg yet — remove everything manually:

terminal

sudo launchctl bootout system/io.sudoji.agent 2>/dev/null
sudo rm -f /usr/local/bin/sudoji
sudo rm -f /Library/LaunchDaemons/io.sudoji.agent.plist
sudo rm -f /var/log/sudoji-agent.log
sudo rm -rf ~/.sudoji /var/root/.sudoji
sudo pkgutil --forget io.sudoji.agent

← Installing on Linux Full command reference →