CLI & Agent Mode

The Gumm CLI (gumm) is more than a management tool. It turns any machine into a connected agent of your brain — your laptop, a Raspberry Pi, a home server, a NAS. Once connected and running gumm up, the brain can reach that machine remotely and execute actions on it, whether triggered from the web dashboard or from Telegram on your phone.

Installing the CLI

Quick install (recommended)

curl -fsSL https://raw.githubusercontent.com/gumm-ai/gumm/main/scripts/install.sh | bash

Supports Linux amd64/arm64 and macOS arm64/amd64. Downloads a precompiled binary and installs it to /usr/local/bin (or ~/.local/bin without root). If no precompiled binary is found, it compiles from source (requires Go 1.23+).

If you used the server setup script, the CLI is already installed on the server.

From source

git clone https://github.com/gumm-ai/gumm.git
cd gumm
make build    # → bin/gumm
make install  # copies to $GOPATH/bin

Connecting to the brain

Before using any CLI command you must point it at your Gumm instance and authenticate.

# 1. Connect to your brain
gumm connect https://your-brain-url.ts.net

# 2. Log in with your admin password
gumm login

# 3. Verify
gumm status

gumm connect validates the URL by contacting the brain’s health endpoint, then saves it to ~/.gumm/config.json.

Connecting through a VPN reverse proxy (SSO)

If your Gumm instance is behind a proxy that requires SSO authentication (NetBird, Cloudflare Access, etc.):

gumm connect --sso https://gumm.eu1.netbird.services

The CLI opens your browser for SSO, then asks you to paste the session cookie from DevTools. The token is saved and used automatically on all subsequent requests.

Agent mode — gumm up

This is the key feature. Run it on any machine you want the brain to be able to control:

gumm up

The CLI connects to the server and listens for tasks. While it is running, the brain can use tools like run_shell_command, take_screenshot, open_application, and read_file on that specific machine.

  Gumm CLI Agent — daemon mode
  Model: google/gemini-2.5-flash
  Server: https://your-brain.ts.net
  Listening for tasks... (Ctrl+C to stop)

  ✓ Connected to server

What the agent can do

Plus all the brain’s remote tools (memory, reminders, modules, Telegram, etc.).

Example — remote control from Telegram

With gumm up running on your laptop and Telegram configured:

You on Telegram: “Take a screenshot of my Mac” Gumm: (takes screenshot, sends it to Telegram)

You on Telegram: “Open YouTube in browser” Gumm: (runs open_url on your laptop)

You on Telegram: “Create a file called meeting-notes.txt on my desktop with today’s date” Gumm: (writes the file to your desktop)

The flow is:

Telegram → Brain → execute_on_cli → gumm up (your machine) → local execution
                                                                      │
Telegram ← Brain ← result ←──────── CLI returns result ←─────────────┘

Running as a background service (macOS / Linux)

To keep gumm up running persistently, create a launch agent or systemd service. Example for macOS launchd (~/Library/LaunchAgents/io.gumm.agent.plist):

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
  <key>Label</key><string>io.gumm.agent</string>
  <key>ProgramArguments</key>
  <array><string>/usr/local/bin/gumm</string><string>up</string></array>
  <key>RunAtLoad</key><true/>
  <key>KeepAlive</key><true/>
</dict>
</plist>

launchctl load ~/Library/LaunchAgents/io.gumm.agent.plist

Device registry

Every machine running gumm up (or gumm storage serve) registers itself with the brain and sends a heartbeat every 30 seconds. The brain tracks all connected machines in the Devices page (/devices).

Any machine that hasn’t sent a heartbeat in 2 minutes is automatically marked offline.

Distributed storage nodesUNDER DEVELOPMENT

Any machine can become a storage node for the brain — centralizing file uploads, attachments, and module-generated files.

# Register this machine as a storage node
gumm storage register --name "Home NAS" --url https://nas.ts.net:7777

# Start the file server daemon
gumm storage serve

The brain proxies all file operations through the storage node. If no node is registered, files are stored locally on the server.

Chat from the terminal

Send messages to the brain and get responses directly in your terminal:

gumm chat "What's on my calendar today?"
gumm chat "Summarize my last emails"

# Continue an existing conversation
gumm chat "And the follow-up?" --conversation=a3f2b1c8

Watch events in real-time

gumm logs

Streams brain events (module loads, tool calls, memory updates, schedule runs) live in your terminal.

Brain management from the CLI

gumm brain stats                           # statistics
gumm brain config                          # view all config
gumm brain config-set identity.name Atlas  # change a value
gumm brain memory                          # list stored facts
gumm brain memory --namespace=brain        # filter by namespace

Module management from the CLI

gumm modules                        # list all modules
gumm modules install owner/repo     # install from GitHub
gumm modules install owner/repo --ref=v2.0
gumm modules reload                 # force-reload all modules

Command reference

Configuration and data

The CLI stores its configuration in ~/.gumm/config.json (created automatically on first gumm connect). The file has 0600 permissions.

To uninstall:

rm -rf ~/.gumm && rm $(which gumm)