Installing the Sudoji Agent

What is the Sudoji Agent?

The Sudoji Agent is an installable CLI that runs on your Linux server. Instead of manually copying error messages into the web chat, you run sudoji ask and the agent automatically gathers context from your environment — Node version, git status, recent log output — and sends it to Sudoji's AI in one shot.

The Agent is built around a brain / hands split: the cloud handles reasoning (the AI model), while the local CLI handles execution (reading files, running commands). Credentials and sensitive output never leave your machine unredacted.

Quickstart — Recommended

The fastest way to get running. One command installs Node.js 20, pm2, and the Sudoji CLI, authenticates with your API key, and starts the daemon — all in one shot.

$ curl -fsSL https://sudoji.io/install.sh \
  | sudo SUDOJI_KEY=<your_api_key> bash

The script handles everything automatically:

• Installs nvm, Node.js 20, and pm2 if not already present
• Installs @sudoji/cli globally
• Runs sudoji login with your key automatically
• Starts the daemon under pm2 and registers it to survive reboots

Prefer a downloadable script?

If you'd rather inspect the script before running it (recommended for production), download it with your key pre-embedded from the dashboard, then run it manually:

# 1. Download from Dashboard → Add Server → Download tab
# 2. Upload to your server via scp / sftp, then:
chmod +x sudoji-install.sh
sudo bash sudoji-install.sh

Once the script finishes, your server appears as ACTIVE in the Servers page and you can start chatting from the portal immediately. The manual steps below are only needed if you prefer full control over each stage.

Prerequisites — Manual install

• Linux server — Ubuntu 20.04+, Debian 11+, or CentOS 8+
• Node.js 18 or later (node --version to check)
• A Sudoji account with an active subscription

Step 1 — Create an API key

The CLI authenticates with a personal API key — not your account password. Keys are scoped so you can give a server read-only access or full execute access independently.

1. Open Dashboard → Settings
2. Scroll to the API Keys section
3. Enter a name (e.g. prod-server), select scopes, click Create Key
4. Copy the key immediately — it is shown once only and cannot be retrieved again

Scope guide:

Step 2 — Install the CLI

npm install -g @sudoji/cli

Verify the installation:

sudoji --version

0.1.20

Step 3 — Authenticate

Run the login command and paste the API key you created in Step 1:

sudoji login

You'll be prompted to paste the key interactively. For CI environments or scripting, use the --paste flag:

sudoji login --paste sudoji_sk_your_key_here

Step 4 — Verify your setup

Run sudoji doctor to confirm auth, API connectivity, settings, and redaction are all working:

sudoji doctor

  ✓  API key stored          sudoji_sk_a1b2c3d4…
  ✓  Settings loaded         apiBaseUrl: https://api.sudoji.io
  ✓  API reachable           https://api.sudoji.io/healthz → HTTP 200
  ✓  Redaction active        "password=super$ecret…" → "password=[REDACTED]…"

All checks passed.

Step 5 — Start the daemon (optional but recommended)

The daemon is a persistent background service that keeps your server connected to the Sudoji cloud hub. While it is running you can send messages directly from the web portal at sudoji.io/dashboard/sessions without needing your terminal open.

The recommended way is to run it under pm2 so it survives reboots and auto-restarts on crash — no second SSH session required.

# Install pm2 globally (skip if already installed)
sudo npm install -g pm2

# Start the daemon as a named pm2 process
pm2 start "sudoji daemon" --name sudoji-daemon

# Save the process list so pm2 restores it after reboot
pm2 save

# Register pm2 as a system service (run the printed command it gives you)
pm2 startup

Check the daemon is connected:

pm2 status           # shows sudoji-daemon as online
pm2 logs sudoji-daemon --lines 20

Once connected, your server appears as online in the portal Servers page and the Chat tab in Sessions becomes active.

Your first question

The main command is sudoji ask. Describe the problem in plain English — the agent automatically gathers context (Node version, git status, recent errors) and sends it alongside your question.

sudoji ask "why is nginx returning 502 after my last deploy?"

The agent streams the answer directly to your terminal. It will tell you the root cause and exact commands to fix it.

Useful flags

Running fixes with sudoji do

sudoji do is shorthand for sudoji ask --mode fix. The agent reads your server, proposes the necessary commands, and runs each one after you approve it.

sudoji do "update all system packages"
sudoji do "check disk space and free up space safely"
sudoji do "restart nginx and confirm it is serving traffic"

Each run_command call shows the exact command and prompts [y/N] before executing. Read operations (reading files, listing directories, searching) are silent and automatic.

Interactive chat: sudoji chat

sudoji chat opens a persistent, multi-turn REPL on your server. Unlike sudoji ask (one-shot), chat remembers what it read earlier in the session — useful for debugging that requires several back-and-forth steps.

Every chat session is automatically given a generated name (like Brave Falcon) and saved as a thread in your portal. You can rename it from the portal by clicking the title.

# Start in diagnose mode (read-only — great for planning)
sudoji chat

# Start in fix mode (can execute commands with your approval)
sudoji chat --mode fix

Setting server context

sudoji context saves a persistent description of your server that is included in every request. Set it once after install so you never have to repeat "this is Ubuntu 22 running nginx…" in every question.

# Set context
sudoji context "Ubuntu 22.04 LTS. Nginx 1.24 + Node 20 + PM2. PostgreSQL 15. Production."

# View what's saved
sudoji context

# Clear it
sudoji context --clear

Analysing logs

sudoji logs fetches recent log output from pm2, systemd, or a file, redacts any secrets, then sends it to the agent for analysis.

systemd

# Last 100 lines from the nginx unit
sudoji logs --source systemd --unit nginx

# Logs from the last 2 hours
sudoji logs --source systemd --unit postgres --since "2 hours ago"

pm2

# Analyse logs for a pm2 app named "api"
sudoji logs --source pm2 --unit api --tail 200

Log file

sudoji logs --source file --file /var/log/app/error.log --tail 50

Configuration

Settings are loaded in layers — each layer can override the one above it:

{
  "apiBaseUrl": "https://api.sudoji.io",
  "defaultMode": "ask",
  "context": {
    "redact": true,
    "maxLogLines": 200
  },
  "permissions": {
    "allow": ["npm install --ignore-scripts"],
    "deny":  ["rm -rf /"]
  }
}