How to use Sudoji

What is Sudoji?

Sudoji is an AI-powered IT support assistant built for engineers managing Linux servers, cloud infra, and developer tooling. Instead of trawling Stack Overflow and vendor docs for hours, you describe the problem and Sudoji surfaces the cause and a concrete fix — often in under a minute.

There are two ways to use Sudoji: through the web chat at sudoji.io, or by installing the Sudoji Agent CLI directly on your server for hands-free log analysis and automated triage. This guide covers the web interface.

Starting a conversation

Go to /chat and describe the problem you're seeing. You don't need to phrase it perfectly — natural language works fine.

Good openers:

nginx is returning 502 on my Ubuntu 22 server, restarted it but the error persists
pm2 app keeps crashing on startup — exits with code 1, no useful logs
postgres connection pool is exhausted after deploying a new feature

Attaching context

Paste raw error messages, stack traces, log excerpts, or config snippets directly into the chat. Sudoji reads them as part of the context and uses them to give a precise diagnosis rather than a generic answer.

Useful things to paste:

• The last 20–50 lines of the failing service's log (journalctl -u nginx -n 50)
• The full error output including the stack trace — not just the final line
• Your package.json, nginx.conf, or relevant config file
• The output of systemctl status <service>

Searching official documentation

Sudoji can scan vendor documentation in real time using Perplexity. This is useful when you need the exact steps from official sources rather than community guesses.

Trigger a doc search by phrasing your message with intent words like:

scan the official nginx docs for the steps to enable http2
look up the official postgres docs for connection pooling settings
fetch the official pm2 guide for log rotation

Keywords like scan, official docs, look up, the steps, and official guide all activate vendor doc search automatically.

Understanding the output

Sudoji structures its responses in three parts:

• Root cause — what actually went wrong, not just what the error message says
• Fix steps — exact commands you can copy and run, in order
• Verification — how to confirm the fix worked

If Sudoji isn't confident, it will say so and ask a follow-up question rather than guessing. If it needs more information — like the output of a specific command — it will tell you exactly what to run and ask you to paste the result.

Tips & best practices

• Always mention the OS and version: Ubuntu 22.04, Debian 12, CentOS 9
• If the error is intermittent, mention frequency: "happens every few minutes under load"
• Tell Sudoji what you've already tried — it won't repeat suggestions you've ruled out
• Use the follow-up thread to refine: paste the output of a fix step if it didn't work
• For recurring issues, install the Sudoji Agent CLI — it gathers context from your server automatically

Using the Sudoji Agent CLI

For deeper server access, install the @sudoji/cli package directly on your Linux server. The agent reads files, checks logs, and can execute commands with your approval — no copy-pasting required.

npm install -g @sudoji/cli
sudoji login        # paste your API key from Dashboard → Devices → + Server
sudoji doctor       # verify everything works

On a Mac or Windows laptop instead? See Installing on macOS/Windows — different installer, different command set.

Two ways to keep the agent available

Interactive chat: plan before you act

sudoji chat opens a multi-turn terminal REPL. The default mode is diagnose — the agent reads files and explains what it finds but never executes commands. This makes it safe to use as a planning tool: describe what you want to do, let the agent walk through it step by step, then run the commands yourself or switch to --mode fix to let it do it.

sudoji chat

  sudoji › I want to migrate from pm2 to systemd for the api process — plan it out
  [agent reads ecosystem.config.js, existing systemd units…]
  › Here's a safe migration plan:
    1. Generate a systemd unit from your pm2 config
    2. Verify the unit starts correctly
    3. Disable pm2 auto-start for the process
    4. Enable the systemd unit

  sudoji › show me the unit file it would generate
  …

Running tools from the portal

Every thread in the portal has a + run tool ▾ menu for triggering a built-in Sudoji tool without typing a request — currently KnowMe (profiles the device: processes, ports, services, packages, docker, cron, web configs) and ExportServerConfig (writes a rebuild manifest to disk for migrating the server to a new host). The same tools are runnable from the terminal with sudoji tool knowme / sudoji tool exportconfig — see the CLI reference.

When the agent proposes a command that needs approval, the portal shows Approve, Approve all (auto-approves the rest of the current turn), and Deny buttons. While a turn is running, a red ■ stop button appears in the thread header — click it to cancel an in-flight command and halt the agent's loop. See the daemon & portal chat guide for details.

Turning a fix into a learning module

Any assistant reply can be turned into a study guide — click + Add to Learning under the message. Sudoji generates a self-contained module from that incident (what broke, root cause, the fix) that you can work through later at sudoji.io/academy — useful for turning one-off fires into something the whole team can learn from.