◈ Examples
Use cases & examples
Real-world scenarios showing how to use Sudoji on a production Linux server.
First install on a new server
The recommended workflow when you set up Sudoji on a new server for the first time. Takes about two minutes.
🚀New server setup
Installing and configuring Sudoji on a fresh Ubuntu server
1 · install the CLI
npm install -g @sudoji/cli
2 · authenticate with your API key (create one at sudoji.io/dashboard/settings)
SUDOJI_NO_KEYCHAIN=1 sudoji login --paste sudoji_sk_your_key_here
3 · verify everything works
sudoji doctor
4 · set persistent server context (do this once)
sudoji context "Ubuntu 22.04 LTS. Nginx 1.24 reverse proxy. Node 20 + PM2 for api.example.com. PostgreSQL 15 on port 5432. Production — handle with care."
5 · start the daemon under pm2 (Engineer+ plan)
sudo npm install -g pm2
pm2 start "sudoji daemon" --name sudoji-daemon
pm2 save
pm2 startup # run the command it prints to survive reboots
6 · ask your first question
sudoji ask "give me a quick health summary of this server"
✦Once context is set, you never need to describe the server again. The daemon stays running in the background — your server shows as online in the portal and you can chat with the agent from the web UI without opening a terminal.
Diagnose a service failure
nginx is returning 502, a pm2 process crashed, or something is clearly wrong. Sudoji narrows down the root cause in one command.
🔴502 Bad Gateway
nginx is returning 502 after a deploy
diagnose — read-only, no changes made
sudoji ask "nginx is returning 502 after my last deploy — what is wrong?"
Once you understand the cause, switch to fix mode:
if you want it to fix it automatically
sudoji do "nginx is returning 502, find the cause and fix it"
✦The agent reads nginx error logs, checks the upstream config, and looks at the process the proxy points to — without you having to copy-paste anything.
💥PM2 process keeps crashing
A Node.js app exits with code 1 immediately after start
diagnose the crash
sudoji ask "my pm2 app called api keeps crashing with exit code 1 — what is causing it?"
or use sudoji logs to pull the pm2 log first
sudoji logs --source pm2 --unit api --tail 200
then fix it
sudoji do "fix the pm2 api crash"
Disk space management
When a server is running low on disk space, Sudoji can identify the culprits and clean them up safely.
💾Disk space investigation and cleanup
Disk at 90%+ — find what is using space and clean it up
diagnose only — see what is using space
sudoji ask "the disk is at 90%, what is taking up all the space?"
or let the agent clean it up (will prompt before deleting anything)
sudoji do "check disk space and safely free up space — don't delete anything important"
✦In fix mode, the agent will ask [y/N] before running any rm or apt clean command. It will never delete application data without showing you exactly what it plans to remove.
Safe system package updates
Keeping packages up to date is important but can be risky on production. Sudoji checks what will change before applying.
📦System package updates
Safely update packages on a production Ubuntu server
check what needs updating first (diagnose)
sudoji ask "what packages need updating on this server and are any of them security-critical?"
Once you know what will change:
apply updates with approval at each step
sudoji do "update all system packages safely"
Log analysis
sudoji logs is the fastest way to get the agent to look at service logs — it handles the redaction and context bundling automatically.
📋Analysing logs for a running service
Something is wrong but you don't know where to start
systemd service — last 100 lines
sudoji logs --source systemd --unit nginx
systemd with time range
sudoji logs --source systemd --unit postgres --since "30 minutes ago"
pm2 app
sudoji logs --source pm2 --unit api --tail 200
specific log file
sudoji logs --source file --file /var/log/myapp/error.log --tail 50
✦All log output is redacted before leaving your machine. Tokens, passwords, and API keys are replaced with [REDACTED].
High CPU, memory exhaustion, or slow response times — the agent can read /proc data, check running processes, and identify the bottleneck.
🧠Memory leak / OOM
A process is consuming all available RAM and the server is swapping
diagnose
sudoji ask "a process is consuming all RAM and the server is swapping heavily — what should I do?"
check and clean in one go
sudoji do "identify the memory-hungry process and restart it safely"
Recurring checks with persistent context
Once you set context with sudoji context, every subsequent command automatically knows what server it is running on. This makes day-to-day queries much faster.
🔁Daily server health check
Quick check every morning without repeating the server description
one-time setup
set context once (never needs to be repeated)
sudoji context "Ubuntu 22.04. Production API server. nginx + Node 20 + PM2 + PostgreSQL 15. 4 vCPUs, 16GB RAM. No Docker."
morning health check — no need to mention the server type
sudoji ask "quick health summary — any warnings I should know about?"
targeted questions
sudoji ask "is postgres running normally and are there any slow queries?"
sudoji ask "how is nginx performing, any error rate spikes?"
sudoji ask "any cron jobs that have not run in the last 24 hours?"
apply any fixes surfaced
sudoji do "restart any services that are in a failed state"
✦Combine context with the portal — open the Sessions page and watch the agent output in real time as you run commands from the CLI.
Planning with Sudoji before making changes
Use sudoji chat (or the portal Chat tab with the daemon running) in diagnose mode to talk through a planned change before executing anything. The agent reads your server state, identifies risks, and proposes an ordered set of steps.
📐Plan a migration with the agent
Migrating a Node.js app from pm2 to systemd — planning it first
open a chat in diagnose mode (read-only)
sudoji chat
sudoji › I want to migrate my api process from pm2 to systemd — plan it for me
[agent reads pm2 process list, checks for existing units…]
› Here's the migration plan:
1. Generate a systemd unit from your pm2 config
2. Test the unit starts correctly
3. Disable pm2 start for this process
4. Enable the systemd unit
sudoji › show me what the unit file would look like
› [Unit]
Description=API Service
After=network.target
…
sudoji › what are the risks?
› Main risk: if the unit fails to start, the api will be down until you re-enable pm2.
Safeguard: keep pm2 running until you verify the systemd unit is stable.
sudoji › exit
Once you are happy with the plan:
then execute in fix mode once the plan is clear
sudoji chat --mode fix
sudoji › create the systemd unit for the api process and enable it
allow? run systemctl daemon-reload [y/N] y
allow? run systemctl enable --now api.service [y/N] y
✓ Done.
✦You can also send planning messages from the portal Chat tab while the daemon is running — type your question in the browser and the agent responds in real time.
Monitoring from the portal
Every sudoji ask, sudoji chat, and sudoji do session is recorded in the Sudoji portal under Sessions. Two tabs organise the view:
Sessions → Chat tab →Live conversation threads created by sudoji chat or the daemon. Each thread has a generated name (e.g. "Brave Falcon") — click the title to rename it. If the daemon is online, you can send messages directly from the browser and the agent handles them on the server in real time.
Sessions → History tab →Archive of completed agent sessions from sudoji ask and sudoji do. Read-only — useful for reviewing what the agent found and what commands it ran.
Dashboard → Servers →Card grid of all connected servers. Shows daemon status (online/offline), last activity, and a link to that server's session history.
ℹSessions from multiple servers all appear in one view. If you have staging and production servers both running the daemon, you can chat with either of them from the portal — each thread shows the server name it is linked to.