Server tools

The 18 tools your assistant can use on a server, and the guard rails on each one.

The tools for computers are listed in Your computer.

Tools marked confirm return a preview first and only act when called again with confirm=true. Assistants are instructed to show you the preview and ask before confirming.

Files

Tool	What it does
`list_dir(path, depth=1)`	Lists a folder (depth 1–4). Protected files are shown as `[protected]`.
`read_file(path, offset=0, max_lines=300)`	Reads a text file in chunks. Secrets are shown as `***`.
`search_files(pattern, path, glob="*", max_results=100)`	Regular-expression search in files under a folder. Skips protected files.
`write_file(path, content, confirm)`	confirm — Writes a file. Without confirmation it returns the diff. Backs up first. Refuses content containing `***` (it would destroy real secrets).
`edit_file(path, old, new, confirm)`	confirm — Replaces one unique snippet. Safer than rewriting the whole file. Backs up first.
`backup_create(path)`	Saves a timestamped copy into `/var/backups/opsgate`.

Logs and services

Tool	What it does
`tail_log(path, lines=100)`	Last lines of a log under the log folders (`/var/log` by default). Reads from the end, even on huge files.
`service_status(name)`	`systemctl is-active` plus the latest status lines.
`service_restart(name, confirm)`	confirm — Restarts a service you allowed with `opsgate allow-restart`.
`service_reload(name, confirm)`	confirm — Sends `HUP` to the service's main process (graceful reload of nginx, gunicorn…).

Commands

Tool	What it does
`run_command(command, cwd, timeout=30, confirm)`	Runs an allow-listed command without a shell: `\|`, `;`, `>`, `$( )` and globs are not interpreted. Path arguments must be inside allowed folders. Commands that change things (`cp`, `mv`, `git pull`…) need confirm. Interpreters (`python3 -c`, `bash`…) and `sudo` are never allowed.
`start_session(command, cwd, confirm)`	Starts an allow-listed command in the background (for long builds or `journalctl -f`).
`read_session(session_id, wait=2)`	New output since the last read.
`stop_session(session_id)`	Stops a session.
`list_sessions()`	Open sessions. Up to 5 at once; idle sessions end after 30 minutes.

Default read-only commands: ls cat head tail grep wc du df free uptime ps stat file diff date id whoami hostname uname which find tree journalctl netstat ss dpkg -l dpkg -L, pip list/show/freeze, npm list/view/outdated, node --version, python3 --version, systemctl status/is-active/list-units, git status/log/diff/rev-parse/show.

Databases and telephony

Tool	What it does
`db_query(sql, max_rows=100)`	One `SELECT`/`SHOW`/`DESCRIBE`/`EXPLAIN` on the MySQL/MariaDB database configured with `opsgate db`, as a SELECT-only user.
`asterisk_cli(command, confirm)`	Asterisk CLI commands, on servers with Asterisk: read-only ones run directly; reloads (profile asterisk) need confirm.
`run_shell(command, cwd, timeout=60, background)`	*Only with the full* access profile.** Runs a bash command as root, like an SSH session (pipes, scripts, `mysql`, `asterisk -rx`…). `background=true` starts it detached; read it with `read_session`. Recorded in the audit log.

Account

Tool	What it does
`account_status()`	Your plan and this month's tool calls. Not counted as a tool call.

Limits on every call

Output is limited to 20,000 characters (longer output is cut with a note).
120 calls per minute per connected app by default.
Every call is written to /var/log/opsgate/audit.jsonl with its parameters (secrets masked), duration and result.