EN中 GitHub

Self-hosting

Runs on your infrastructure

There is no hosted SuDuo. Your team installs the server on a Linux machine of its own, and everyone runs the client on their own computer. Repositories, Codex sessions and model credentials stay on each person's machine, with no SuDuo service in between.

Start deployingServer deployment guide

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)
  • Node.js 24 LTS (24.10 or later in the 24.x line), pnpm 10.25 and git
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

There is no installer yet, so the client runs from source. The commands are the same in Terminal on macOS and PowerShell on Windows. You don't need to install Codex separately; pnpm install brings the Codex CLI version this release is tested with.

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.

Connect to your team

  1. Sign in to Codex with pnpm exec codex login in the client/ directory, or set your model service under Settings → Model service (this changes ~/.codex, so the Codex CLI you run yourself uses it too)
  2. Enter the server address 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

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.

The full guides are on GitHub