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 and the Sudoji CLI, authenticates with your API key, and starts the daemon as a systemd service — all in one shot.

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

The script handles everything automatically:

• Installs Node.js 20 (via NodeSource) if not already present
• Installs @sudoji/cli globally
• Runs sudoji login with your key automatically
• Installs the daemon as a systemd service, enabled 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

Prefer a native binary over Node.js?

Dashboard → Add Server has a Native binary tab with an equivalent one-liner that installs a standalone Go binary instead of @sudoji/cli — no Node.js dependency. Same systemd-managed daemon, same non-root posture as the quickstart above. Pick one or the other per server; installing one supersedes the other rather than running both.

Once the script finishes, your server appears as ACTIVE under Servers on the Devices 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 → Devices
2. Click + Server (or + EUD for a macOS/Windows device)
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://agent.sudoji.io
  ✓  API reachable           https://agent.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 as a systemd service so it survives reboots and auto-restarts on crash — no second SSH session required. This is exactly what the quickstart one-liner sets up automatically; here's the equivalent by hand:

SUDOJI_BIN=$(command -v sudoji)
REAL_USER=$(whoami)   # or whichever user should own the daemon

sudo tee /etc/systemd/system/sudoji-daemon.service > /dev/null <<EOF
[Unit]
Description=Sudoji Agent Daemon
After=network-online.target
Wants=network-online.target

[Service]
Type=simple
User=${REAL_USER}
ExecStart=${SUDOJI_BIN} daemon
Restart=always
RestartSec=2
StartLimitIntervalSec=300
StartLimitBurst=50

[Install]
WantedBy=multi-user.target
EOF

sudo systemctl daemon-reload
sudo systemctl enable --now sudoji-daemon

Check the daemon is connected:

systemctl status sudoji-daemon      # shows active (running)
journalctl -u sudoji-daemon --lines 20

Once connected, your server appears as online on the Devices 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

Running built-in tools

Beyond free-form questions, Sudoji ships a couple of ready-made tools you can run directly with sudoji tool <name> — the same mechanism the portal's "+ run tool" chat menu uses.

# Profile this device — processes, ports, services, packages, docker, cron, web configs
sudoji tool knowme

# Write a rebuild manifest before migrating this server to a new host
sudoji tool exportconfig

knowme is read-only and runs without a prompt. exportconfig writes a manifest file to disk (packages, pm2/nginx/systemd config, cron, firewall rules, and .env variable names only, never values) and asks for one-time approval since it performs a write. See the full reference for details.

Configuration

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

Layers are listed lowest → highest priority — each one overrides the layer above it, except that org-managed deny rules and other locked fields always win regardless of what a lower layer sets.

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