Team server

Once per team

Keeps projects, requirements, comments, attachments and discussion rooms. A Linux server with Docker, set up with one script.

Each developer's computer

Once per person

Runs the SuDuo client and the Codex CLI. Repositories, Codex sessions and model credentials stay here.

System requirements

Team server
  • Ubuntu 22.04 or 24.04 (x86_64): supported. Other Linux distributions with Docker, including arm64: best effort
  • At least 2 CPU cores, 4 GB RAM and 20 GB disk
  • Docker Engine with the Compose plugin, and git
  • Access to Docker Hub and npm while building, or mirrors you can reach; team members must be able to reach the service port (4100 by default)
Each computer
  • macOS 13.5 or later (Apple silicon or Intel), or Windows 10 / 11 (x64)
  • git: used for checkpoints and branch status, and required to run from source
  • To run from source, also Node.js 24 LTS (24.10 or later in the 24.x line) and pnpm 10.25
Model
  • A ChatGPT sign-in for Codex, or an API key for OpenAI or a compatible service

The server in three steps

Run these on the server, in order. The full deployment guide covers HTTPS, day-to-day operations and troubleshooting.

  1. Install Docker and git

    On Ubuntu you can use Ubuntu's own packages, or Docker's official ones.

    On the server
    sudo apt update
    sudo apt install -y docker.io docker-compose-v2 docker-buildx git
  2. Get the code at the latest release

    Use a release tag rather than main. Clients and the server should run the same version; the client tells you when they differ.

    On the server
    git clone https://github.com/Im-Sue/suduo-workbench.git
    cd suduo-workbench
    git checkout "$(git describe --tags --abbrev=0)"   # the latest release tag
    cd cloud
  3. Install with one command

    In mainland China, add --mirror cn to build with mirrors that are reachable there. The first build takes about 3–8 minutes; when the server is ready, the script prints its address.

    In the cloud/ directory
    sudo ./scripts/suduo-cloud.sh install

    The script's messages follow the server's locale, and Ubuntu servers often default to English. To choose the language yourself, put SUDUO_LOCALE after sudo (before sudo it has no effect).

    In the cloud/ directory
    sudo SUDUO_LOCALE=en ./scripts/suduo-cloud.sh install

Then each team member enters that address under Settings → Requirements service in the client and registers an account.

Upgrade, back up, restore

The same script handles day-to-day operations. Run it in the server's cloud/ directory.

Upgrade

Run git fetch --tags, check out the release you want, then run upgrade. It backs up first and stops if the backup fails; the database is migrated when the service starts.

sudo ./scripts/suduo-cloud.sh upgrade

Back up

Backs up the database together with attachments and room files, so they always match. The service pauses while it copies, longer for more data. Backups go to /var/backups/suduo/<timestamp> by default.

sudo ./scripts/suduo-cloud.sh backup

Restore

Replaces all current data with a backup. It backs up the current data first, then restores and starts the version that is checked out, so rolling back means checking out the previous tag and restoring the backup from before the upgrade.

sudo ./scripts/suduo-cloud.sh restore /var/backups/suduo/<timestamp>

The client, on each computer

Use either one; both connect to your team's server. You don't need to install Codex separately. The desktop app includes it, and when you run from source, pnpm install brings the Codex CLI version this release is tested with.

Desktop app (trial)

Download it, install it and go; no Node.js or pnpm needed. Closing the window keeps SuDuo running in the menu bar (macOS) or the notification area (Windows), so sessions keep going and the Codex you share in rooms keeps answering.

Download the latest release
Which installer to download for each computer
ComputerFile
macOS 13.5+, Apple siliconSuDuo-<version>-mac-arm64.dmg
macOS 13.5+, IntelSuDuo-<version>-mac-x64.dmg
Windows 10 / 11 (x64)SuDuo-Setup-<version>-x64.exe
  • Use the same version as your team's server: the button opens the latest release, and earlier ones are on the Releases page on GitHub.
  • The trial isn't signed yet. On macOS, the first time you open it, macOS says it can't verify the developer: close the message, then click Open Anyway under System Settings → Privacy & Security and confirm. Each new version needs this once.
  • On Windows, if SmartScreen says “Windows protected your PC”, click More info, then Run anyway.
  • It doesn't update itself yet. Download and install each new version (on macOS, quit SuDuo from the menu bar first, then replace it in Applications); your data is kept. SHA256SUMS.txt on the same page lists every file's checksum.

Run from source

The commands are the same in Terminal on macOS and PowerShell on Windows. You need Node.js 24 (24.10 or later), pnpm 10.25 and git.

On your own computer
git clone https://github.com/Im-Sue/suduo-workbench.git
cd suduo-workbench
git checkout "$(git describe --tags --abbrev=0)"   # use the same release as your server
cd client
pnpm install
pnpm start

pnpm start checks your environment, builds SuDuo the first time (about 1–2 minutes), starts it on http://127.0.0.1:8787 and opens your browser. Press Ctrl+C to stop it.

If downloads from npm are slow or fail (for example in mainland China), run pnpm config set registry https://registry.npmmirror.com, then pnpm install again.

Connect to your team

  1. Set up Codex: an existing Codex sign-in or model setup works as it is. You can also enter an API key under Settings → Model service (this changes ~/.codex, so the Codex CLI you run yourself uses it too), or sign in to ChatGPT with Codex (from source, run pnpm exec codex login in the client/ directory; the client guide has the command for the desktop app)
  2. Enter your team server's address (in the first-run setup, or under Settings → Requirements service), then register or sign in
  3. Choose the folder where the project's code lives, open a requirement and start a session