Requirements and limits

This page lists what you need before you start and the limits you may run into. Topic pages repeat the items that apply to them.

Computer and software

Item	Requirement
Operating system	Windows 10 or later (x64) · macOS 13 (Ventura) or later (Apple silicon or Intel) · Linux: Ubuntu 22.04 or 24.04 (DEB), Rocky Linux or RHEL 9 (RPM); a tar.gz package for other distributions (x64)
Memory	8 GB minimum, 16 GB recommended
Free disk space	10 GB for a source install, 20 GB for Docker. The data directory grows with attachments, deliveries and harnesses (runtimes) you install
Python	3.12 or later. On Windows, select Add Python to PATH during install
Node.js	22.19 or later, with npm. Needed to build the admin console and run the desktop client
Network	Required the first time, to download dependencies. Later starts reuse them
Docker (optional)	Docker Desktop in Linux container mode on Windows and macOS; Docker Engine with Compose v2 on Linux

Run from source listens on 127.0.0.1 by default. It is for trying SoduWork on one computer. --host can bind it to a LAN address, but it still serves plain HTTP with SQLite; use Docker or a production deployment for a team.
Docker maps the Hub to 127.0.0.1 and does not expose PostgreSQL. For team access, put your own HTTPS reverse proxy in front of it. The proxy must support WebSocket and long streaming responses.
Data directories must be outside the source folder, and either empty or created by the same launcher.
One instance per data directory. Do not run two migrations against the same database at the same time.
Multi-node Hubs need their own shared storage and coordination design. The provided launchers set up a single node.
Offline installs: the first build needs network access. To deploy offline, build the images on a connected machine of the same platform first.

SoduWork does not include model keys. Configure services you are allowed to use.
Services connect through an OpenAI-compatible API (/v1). This covers most gateways, vLLM, Ollama and compatible providers. Other protocols are not converted automatically.
Organization keys stay on the Hub and are never returned in plain text. Users can add a personal key in the client.

Pi is built in. Other harnesses (runtimes) are installed on demand from Settings → Agent management.
Some harnesses use your SoduWork models; others, such as Codex and Claude Code, sign in with their own account.
A program that supports the Agent Client Protocol (ACP) can be added with a declaration in hub-backend/app/agent_catalog.json and a rebuild of the client and runner. Harness IDs start with a lowercase letter and have up to 40 lowercase letters, digits or hyphens.
Programs that use another protocol need an adapter written for them.
Harnesses are not installed remotely. Each computer or runner installs its own.

Package format: .soduwork-plugin, a zip of at most 10 MB and 300 files, with plugin.json at the root (schemaVersion: 1).
A workflow has 1 to 100 nodes and no cycles. Each node retries at most 5 times. AI node time limits range from 60 to 86,400 seconds.
A published version is immutable. Changing content requires a new SemVer version.
Plugins published to an organization go through quarantine and admin review.
Skills and plugins are not a security sandbox. Install them only from sources you trust.

In production, use HTTPS and set a separate authentication secret for the Hub.
Connect runners only to Hubs you trust.
Protect local-service.json (source install) and deployment.json (Docker) like passwords. They contain signing keys.
Include the database and file storage in your backups.

Stop the service and back up the whole data directory before upgrading.
To roll back, restore both the matching source version and the matching data backup. An older version can't use a database that a newer version has already migrated.
When a release includes both, upgrade the Hub first, then the clients.

harness harnesses runtime runtimes 底座