Rung Developer Docs

Everything you need to install, configure, and get the most out of Rung.

5-minute quick start: install → rung /login → ask your first question.

Installation

Rung ships as a single static binary — no Python, no Node, no runtime dependency.

Windows

PowerShell (recommended)

Manual

# Run in PowerShell as your normal user (not Administrator)
PS> irm https://ashigo.com/install.ps1 | iex

Downloads rung.exe to %LOCALAPPDATA%\Rung\ and adds it to your user PATH. Restart your terminal after install, then run rung --version to confirm.

Download the binary directly:

rung-windows-amd64.exe — most PCs (64-bit Intel/AMD)
rung-windows-arm64.exe — Surface Pro X / ARM laptops

Rename to rung.exe, place in a folder on your %PATH%.

Recommended terminal on Windows: use Windows Terminal (free from the Microsoft Store) with PowerShell 7+. It has full ANSI colour support and better keyboard handling than the legacy cmd.exe. See Windows keyboard troubleshooting if you experience missing keystrokes.

macOS & Linux

curl (recommended)

Manual download

$ curl -fsSL https://ashigo.com/install.sh | sh

Detects your OS and CPU (x86_64, arm64, arm). Puts the binary in ~/.local/bin or /usr/local/bin.

Platform	Architecture	File
Linux	x86_64	rung-linux-amd64
Linux	arm64	rung-linux-arm64
Linux	arm	rung-linux-arm
macOS	Apple Silicon	rung-darwin-arm64
macOS	Intel	rung-darwin-amd64

chmod +x rung-* then move to a directory on your $PATH.

First run

$ rung

 ██████╗ ██╗   ██╗███╗   ██╗ ██████╗
 ██╔══██╗██║   ██║████╗  ██║██╔════╝
 ██████╔╝██║   ██║██╔██╗ ██║██║  ███╗   Rung v0.1.0
 ██╔══██╗██║   ██║██║╚██╗██║██║   ██║   agentic CLI for OT & industrial systems
 ██║  ██║╚██████╔╝██║ ╚████║╚██████╔╝
 ╚═╝  ╚═╝ ╚═════╝ ╚═╝  ╚═══╝ ╚═════╝

Memory: not configured — /memory set SERVER to enable shared knowledge
You're not signed in. Use /login to sign in.

rung ❯ /login
  Your activation code: WXYZ-1234
  Opening https://ashigo.com/activate…
Sign in on the page, then come back — waiting for approval…
Hello, Alex!

Authentication uses the device authorization grant (RFC 8628): your browser handles the sign-in, the CLI never sees your password. Works on headless servers too — type the activation code on any device with a browser.

Access & pricing

Rung uses your Ashigo account — no separate API keys to manage. Sign up at ashigo.com/signup, then run rung /login.

Individual: subscription tier controls monthly token quota and available privacy levels.
Teams & enterprise: seat licences, relay deployment, custom SLAs — contact us.

The relay and Rung Insight use a service account API key from your Ashigo dashboard. This key lives in the relay's .env file on your server — it is never shipped inside the software you download.

CLI Reference

All commands start with /. Tab-completion is available in the REPL.

/clear

Start a new server-side conversation. History is discarded; your login, region, and settings are preserved.

/cost

Show token usage for this session (input, output, thinking tokens) and your account's total usage vs. quota for the billing period.

/key

Show the fingerprint of your local encryption key. The key itself never leaves your machine.

/relay · /relay set · /relay clear

Configure an on-site relay. When set, all CLI traffic routes through it instead of directly to the backend. The relay can apply guardrails, enforce data-diode mode, and host the shared memory database.

rung ❯ /relay set http://192.168.10.50:8430
Relay set. CLI traffic now routes through it.

/privacy · /privacy <level>

Show or change the active privacy level: standard / split / shielded / diode. See Privacy levels for details on each.

/memory · set · clear · list · connections · <text>

Manage the relay's shared memory database.

Sub-command	Effect
`/memory set http://relay:8430`	Connect to the relay's memory API
`/memory`	Show connection status and entry counts
`/memory list`	Show the 15 most recent knowledge entries
`/memory connections`	List all saved system connections
`/memory clear`	Disconnect (data is not deleted)
`/memory <any text>`	Manually store a knowledge entry

/region · /region <code>

Select the data-processing region used by the split and shielded privacy levels. Examples: eu, us, apac.

/permissions / /help

/permissions — list saved "always allow" tool grants (stored in ~/.rung/permissions.json). / or /help — list all available commands with descriptions.

Built-in Tools

Tools are defined on the server and run locally after your approval. The model requests a tool; you approve or deny it; the output goes back to the model.

Approval model: every tool requires your approval unless you have a saved "always allow" grant. Approve once with y, for the whole session with a, deny with n. Tools that write to live control systems always require explicit confirmation and cannot be saved as "always allow".

File & shell tools

run_command

requires approval

Run a shell command on your machine. Full command is shown before execution. You can grant "allow all commands for this session" with a.

read_file

read-only

Read a local file. Path is shown before reading.

write_file

requires approval

Write or overwrite a local file. A diff is shown before writing.

edit_file

requires approval

Apply a targeted string replacement to a file — safer than write_file for small changes.

list_dir

read-only

List a directory's contents.

grep

read-only

Search file contents by regex, recursively.

parse_log

read-only

Parse and summarise log files — ArchestrA SMC exports, Windows Event Log CSV, historian logs, generic text. Returns severity counts and key matching lines.

Network diagnostic tools

ping

read-only

Ping a host. Returns RTT and packet loss.

traceroute

read-only

Trace the network path to a host.

dns_lookup

read-only

Resolve a hostname (A, AAAA, MX, etc.).

port_check

requires approval

Check if a TCP port is open. Useful to verify SCADA, historian, or PLC service availability before querying.

OT protocol tools

modbus_read

live device read-only

Read coils, discrete inputs, holding or input registers from a Modbus TCP device. Inputs: host, port (default 502), unit, table, address, count.

opcua_browse

live device read-only

Browse the address space of an OPC UA server. Input: endpoint (e.g. opc.tcp://10.0.0.5:4840), optional node_id.

opcua_read

live device read-only

Read current values of one or more OPC UA nodes by node ID.

Aveva Historian

historian_query

live database SELECT only

Run a read-only SQL SELECT against an Aveva Historian Runtime database over ODBC. Supports Windows auth or username/password. Inputs: server (SQL Server host\instance), database (default Runtime), query.

-- Example: last 10 minutes of a tag, cyclic retrieval
SELECT TOP 100 DateTime, Value
FROM History
WHERE TagName = 'PUMP_FLOW_01'
  AND DateTime > DATEADD(MINUTE,-10,GETDATE())
  AND wwRetrievalMode = 'Cyclic'
  AND wwResolution = 5000

search_knowledge

server-side

Full-text search over the curated OT knowledge base (Aveva docs, PLC manuals, SCADA runbooks). Called automatically by the model when it needs reference information — you see a one-liner noting the search query.

Privacy & Security

Four selectable levels. Switch with /privacy <level>. Default is split.

1 · Standard

Direct calls to the primary model. Fastest. Suitable for non-sensitive queries.

2 · Split

A separate distillation model processes raw tool data first — no single model sees the full picture.

3 · Shielded

Split + pseudonymisation. IPs, hostnames, OPC node IDs, and custom terms are tokenised before the reasoning model; restored in your output.

4 · Data-diode

Air-gapped one-way mode. Prompt is sent; nothing returns to the terminal. Answer appears on the relay's /diode page. Requires a relay.

Encryption at rest

Rung generates a unique local encryption key (Fernet / 256-bit AES) on first launch, stored in ~/.rung/ with chmod 600 on Unix. Only its SHA-256 fingerprint is sent to the server — the key never leaves your machine.

Audit log

Every tool execution is logged server-side (tool name, inputs, outcome — not full conversation content) for SOC 2 compliance. The relay also writes a local audit log. Tool inputs containing sensitive data are not stored in shielded or diode mode.

On-Site Relay

An optional on-premise proxy for your plant network. CLIs connect to the relay; the relay forwards to the Rung backend and enforces site-level guardrails.

The relay holds no vendor secrets — no Anthropic key, no Clerk credentials. It only knows the Rung backend URL (a public-facing endpoint).

Deploying with Docker Compose

# 1. Get the relay package
$ git clone https://github.com/ashigo-ot/rung-relay
$ cd rung-relay

# 2. Create your environment file
$ cp .env.example .env
$ nano .env     # set RELAY_UPSTREAM_URL and RELAY_ADMIN_PASSWORD at minimum

# 3. Start
$ docker compose up -d --build

# Health check
$ curl http://localhost:8430/relay/health
{"status":"ok","upstream":"...","site":"Factory Relay","chat_enabled":false}

Configuration reference

Variable	Required	Description
`RELAY_UPSTREAM_URL`	yes	Rung backend URL (from your Ashigo account)
`RELAY_SITE_NAME`	no	Human label shown in the admin UI and diode page
`RELAY_ADMIN_USER`	no	Admin UI login (default: `admin`)
`RELAY_ADMIN_PASSWORD`	yes	Admin UI password — change before deploying
`RELAY_MEMORY_DB_URL`	no	Defaults to SQLite at `data/memory.db`. Use `postgresql+psycopg://…` for Postgres
`RELAY_CHAT_API_KEY`	no	Service account key — enables Rung Insight at `/chat`
`RELAY_CHAT_PASSWORD`	no	Password for `/chat`. Leave empty for LAN-open access

Guardrails

The admin page (at /admin) lets your IT team restrict capabilities per CLI or site-wide:

Block (hard) — the relay strips the tool request before it reaches the CLI. The conversation continues with "disabled by site policy". The model adapts and may suggest manual alternatives.
Prompt (soft) — an instruction is injected into the model's context telling it not to use the capability. Good for guidance rather than hard enforcement.

Configurable capabilities: file read, file write, shell commands, network diagnostics, port scan, Modbus, OPC UA, Historian SQL.

Data-diode mode

Enable via the admin UI (per CLI or site-wide) or with /privacy diode on any CLI. In this mode:

The terminal sends the prompt and receives only a short acknowledgement (✓ Sent).
The relay drives the entire model turn and stores the answer in memory.
The engineer reads the answer at http://relay:8430/diode — never on the terminal.
The model produces copy-paste commands rather than live tool calls. The engineer runs them locally and sends the output as a new prompt to continue the loop.

Connecting CLIs to the relay

# Interactive setup inside the REPL
rung ❯ /relay set http://192.168.10.50:8430
Relay set. CLI traffic now routes through it.

# Or via environment variable (useful for scripts or CI)
$ RUNG_BACKEND_URL=http://192.168.10.50:8430 rung

Rung Insight

Browser-based chat for non-specialist users — no terminal needed. Served at /chat on the relay. Uses the same Rung API and is automatically enriched with shared memory context built by field engineers.

Setup

# relay/.env
RELAY_CHAT_API_KEY=<your-service-account-key>

# Optional: protect with a password (leave empty for LAN-open)
RELAY_CHAT_PASSWORD=your-site-password

$ docker compose restart relay

Navigate to http://relay:8430/chat from any browser on the LAN. If RELAY_CHAT_PASSWORD is set, a login form is shown.

Features

Streaming chat — responses stream in real time, same model as the CLI.
Memory context injection — on the first message of each session, the relay automatically injects shared knowledge and saved connections as model context. Users get plant-specific answers without any setup.
Memory sidebar — browse connections and knowledge entries saved by field CLIs; click any item to insert a question about it.
Chart generation — JSON arrays in responses get a "📊 Chart" button. Choose chart type (bar, line, pie, doughnut, scatter), configure axes, download as PNG.
Excel export — markdown tables and CSV code blocks get "⬇ Excel" buttons (SheetJS).
Conversation export — download the full chat as a Markdown file.

Shared Memory

A relay-hosted knowledge database that grows from real engineering sessions. Every CLI on your network can read and contribute — one knowledge base, zero configuration for end users.

How it works

Auto-store: after each substantive assistant turn (>200 chars), the CLI stores the response in the background (category auto). Requires /memory set.
Manual store: /memory This pump uses unit ID 7 on bus 2 — stores a one-liner immediately, category manual.
Insight context: Rung Insight reads the 15 most recent entries and all connections and prepends them as context for every new chat session.

Saved connections

After a successful Modbus, OPC UA, or Historian query, the CLI offers to save the connection details:

Save 192.168.1.100 (modbus) to shared memory?
  [y/n]: y
  Description (optional): Press line 3 main drive
✓ Connection saved to shared memory.

Other CLIs and Rung Insight see this connection immediately. If the same tag and kind are saved again, the record is updated — no duplicates.

Connection kind	What is stored
`modbus`	`host:port`
`opcua`	Full endpoint URL (`opc.tcp://…`)
`historian`	`server/database`

Storage options

The default is SQLite at data/memory.db inside the relay container, persisted via Docker volume. For multi-host or high-write deployments, switch to Postgres:

# relay/.env
RELAY_MEMORY_DB_URL=postgresql+psycopg://user:pass@host:5432/dbname

The schema is created automatically on first start. No migrations needed when switching from SQLite — the Postgres database starts fresh.

Troubleshooting

Windows: some letters not captured while typing

This is not a hardware or OS keyboard issue — it is a known limitation of the input library (chzyer/readline) when running in certain Windows console environments. Two root causes combine:

Console codepage mismatch: the legacy Windows console defaults to an OEM codepage (e.g. CP437 for US English, CP850 for Western Europe). Characters outside ASCII — including accented letters (é, ü, ñ, â) and some symbol keys — arrive at the library encoded in OEM bytes, not UTF-8. The library's UTF-8 parser silently discards bytes it can't decode, which appears as "missing letters".
Stdin input mode: without ENABLE_VIRTUAL_TERMINAL_INPUT set on the console's stdin handle, special key combinations arrive as Windows virtual-key records (Win32 INPUT_RECORD structures) rather than ANSI escape sequences. The readline library is designed around ANSI sequences and cannot parse VK records, so those keystrokes are lost.

Fixed in the next binary release. The startup code now explicitly sets the console to UTF-8 (codepage 65001) and enables ENABLE_VIRTUAL_TERMINAL_INPUT on stdin before readline is initialised — which resolves both causes on Windows 10 1903+ and Windows 11.

Immediate workarounds

Option 1 — Use Windows Terminal (easiest): install Windows Terminal free from the Microsoft Store. It applies its own UTF-8 input normalisation and VT-mode handling that avoids both issues in almost all cases. Run PowerShell 7 or cmd inside it.

Option 2 — Set UTF-8 codepage manually: run this once in the same terminal window before launching Rung:

REM Works in both cmd.exe and PowerShell
C:\> chcp 65001
Active code page: 65001
C:\> rung

Option 3 — Make UTF-8 the system default (permanent): go to Settings → Time & Language → Language & Region → Administrative language settings → Change system locale and check "Beta: Use Unicode UTF-8 for worldwide language support". Restart required. This sets CP65001 for all console programs system-wide.

"Your session is invalid or expired" — run /logout then /login to get a fresh token.
Browser doesn't open automatically — copy the URL shown in the terminal and open it on any device with a browser.
Activation code expires — codes are valid for 5 minutes. Run /login again to get a new one.
On a headless server with no browser — copy the activation code, open https://ashigo.com/activate on your laptop, and enter it there.

Relay connectivity

"Memory: <url> — unreachable" — the relay is not running or the URL is wrong. Run docker compose ps on the relay server. Re-configure with /memory set <correct-url>.
"Data-diode mode needs an on-site relay" — diode mode requires a relay (the answer goes to the relay page, not your terminal). Set one with /relay set <relay-url> first.
Health check:

$ curl http://relay:8430/relay/health
{"status":"ok","upstream":"...","site":"Factory Relay","chat_enabled":true}