ScienceDiscovery
中文 GitHub

Deploy ScienceDiscovery

If this is your first time using ScienceDiscovery, start with the Quick Start. This page is for users who need another deployment path, want to run the service long-term, or need startup troubleshooting.

Choose a deployment path

Mode Supported platforms Best for Recommendation
Prepackaged single file glibc-based Linux x86_64 / aarch64, Windows x64 (WSL 2 with a glibc-based distribution, experimental) Users who want the shortest startup path Recommended on native Linux
Local source mode Linux x86_64 / aarch64, macOS 13+ x64 / arm64, Windows x64 (WSL 2, experimental) macOS users, development, source changes Recommended on macOS
Docker Linux x86_64 / aarch64, macOS (Docker Desktop or an existing Docker engine, experimental), Windows (Docker Desktop, experimental) Existing container environments and operational isolation As needed

macOS Docker and all Windows installation paths are experimental because Agent behavior there has not been fully validated.

The three paths are independent. Choose one. Once the service is running, return to the Quick Start for model configuration and the first task.

Prepackaged single-file deployment (Linux)

Prerequisites

This release binary does not run directly on musl-based distributions such as Alpine Linux.

On Windows, run the commands in this section inside your WSL 2 Linux distribution. Keep the downloaded file in the distribution's Linux filesystem, such as your home directory. If you downloaded it in a Windows browser, open your WSL 2 Linux terminal (for example, Ubuntu) and run cd ~ && explorer.exe . there. Windows File Explorer opens your Linux home directory; copy the download into it.

Install Bubblewrap:

sudo apt-get install -y bubblewrap   # Debian / Ubuntu
# Or
sudo dnf install -y bubblewrap       # Fedora / RHEL / openEuler

Download and start

Download the file matching your architecture from the Releases page:

ScienceDiscovery-<version>-linux-x86_64
ScienceDiscovery-<version>-linux-aarch64

You can run the downloaded file directly or rename it first. In the directory containing the download, use the following commands if you have one matching binary for your architecture:

mv ScienceDiscovery-*-linux-"$(uname -m)" ScienceDiscovery
chmod +x ./ScienceDiscovery
./ScienceDiscovery serve

A successful startup prints an Open to sign in URL. Open it in your browser.

What happens on first launch

The first serve prepares some runtime dependencies and therefore needs network access. Later launches reuse the prepared environment.

For offline hosts, prepare the data directory on a connected machine or configure reachable package mirrors. See the configuration reference.

Common startup options

ScienceDiscovery serve [options]

Most users only need:

Option Purpose
--data-dir <path> Set the data directory
--host <address> Set the Web/API bind address
--port <port> Set the Web/API port
--env-file <path> Read environment variables from a file
--skip-sandbox-check Start the UI when sandbox execution is unavailable; code execution will not work

The service binds to the local machine by default. If you must expose it, configure a separate authentication token first and use only a trusted network.

Local source mode (Linux / macOS)

Use local source mode when:

Prerequisites

All supported local environments require:

The setup script calls python3 before uv creates its Python 3.12 environment.

Sandbox requirements differ:

Debian 11's default Bubblewrap package is 0.4.1, below the listed Linux requirement. Use a newer package or distribution if it applies to you.

On macOS, use version 13 or newer for local source mode, as required by the current uv platform policy.

Clone and start

On Windows, run these commands inside your WSL 2 Linux distribution. In WSL 2, clone into the distribution's Linux filesystem, such as your home directory, rather than under /mnt/c. Dependency installation is much faster there, and Linux file permissions behave as expected. Run cd ~ before the commands below.

git clone https://github.com/openJiuwen-ai/sciencediscovery.git
cd sciencediscovery

scripts/jiuwenswarm.sh setup
./scripts/start-stack.sh --mode local

Source mode now starts JiuwenSwarm by default. To run the older native Node loop instead, use ./scripts/start-stack.sh --mode local --no-jiuwenswarm or set SCIENCE_AGENT_EXECUTOR=native in .env. See Agent backends for behavior differences and an active-backend check.

The first run installs dependencies and builds the project, so it needs network access.

After a successful build, later starts can use:

./scripts/start-stack.sh --mode local --no-build

A successful startup prints the same Open to sign in URL.

macOS notes

If local source mode reports that Seatbelt is unavailable, check:

test -x /usr/bin/sandbox-exec

If this fails, or your terminal is itself inside a stricter sandbox, fix the host restriction first.

Docker deployment (Linux containers)

Docker is intended for users who already operate containerized services and want the runtime isolated from the host.

Prerequisites

1. Prepare configuration and storage

If you do not have a local checkout yet, clone the repository first:

git clone https://github.com/openJiuwen-ai/sciencediscovery.git
cd sciencediscovery

On Windows, use PowerShell in the repository root:

Copy-Item .env.docker.example .env
New-Item -ItemType Directory -Force data

On Windows, Docker Desktop must be running Linux containers. Its WSL 2 engine is normally enabled by default; check Docker's WSL 2 settings if Docker reports that it cannot start Linux containers.

On Linux or macOS, use a Unix shell in the repository root:

cp .env.docker.example .env
mkdir -p data
id -u
id -g

If your uid/gid is not 1000:1000, set these values in .env:

SCIENCE_AGENT_UID=<your uid>
SCIENCE_AGENT_GID=<your gid>

The data/ directory stores projects, sessions, workspaces, credentials, and other runtime state.

2. Build and start

docker compose build
docker compose up -d

Check the service:

docker compose ps
docker compose exec sciencediscovery curl -fsS http://127.0.0.1:4310/health

You can also open http://127.0.0.1:4310/health in a browser. Top-level status: ok confirms that the API can reach the Runner. It does not prove that the code-execution sandbox works. After signing in, run the small Python calculation in the Quick Start to check that part of the installation.

If it reports degraded, inspect logs first:

docker compose logs --tail=200

3. Open the Web UI

View the logs and find the Open to sign in URL:

docker compose logs -f

Open the printed Open to sign in URL in your browser.

You can also open http://127.0.0.1:4310 directly and paste the local service access token when prompted.

Treat the sign-in URL and token like a password.

4. Routine operations

Action Command
Check status docker compose ps
Follow logs docker compose logs -f
Stop docker compose down
Restart docker compose restart
Rebuild after code changes docker compose up -d --build
Enter the container docker compose exec sciencediscovery sh

docker compose down does not delete the host data/ directory.

5. Remote access

For a remote host, prefer SSH port forwarding instead of exposing the service directly to the public network:

ssh -N -L 4310:127.0.0.1:4310 <user>@<remote-host>

Then open http://127.0.0.1:4310 locally.

First-run troubleshooting for binary and local mode

No Open to sign in URL appears

Read the earliest startup error first. Later failures are often consequences of the first one.

The browser rejects the token

Open the Open to sign in URL from the latest startup output again.

If entering a token manually, use the local service access token, not the model provider API key.

/health reports degraded

Run:

curl -fsS http://127.0.0.1:4310/health

A degraded status means the API cannot reach the Runner. Check the startup log. On Linux or WSL 2, a warning containing could not build a sandbox means code execution will fail, even when /health reports ok. Follow the sandbox steps below in that case.

Linux reports missing bwrap

Install Bubblewrap:

sudo apt-get install -y bubblewrap
# Or
sudo dnf install -y bubblewrap

If Bubblewrap is installed but still fails, follow the sandbox checks below.

Bubblewrap is installed, but code execution fails

If the startup log says could not build a sandbox, check the error before changing system settings. On Linux or inside WSL 2, run:

bwrap --version
sysctl kernel.unprivileged_userns_clone
sysctl kernel.apparmor_restrict_unprivileged_userns

A missing sysctl key is normal on some kernels. If kernel.unprivileged_userns_clone exists and is 0, unprivileged user namespaces are disabled on that host. Ask the host administrator to enable them before retrying. If the AppArmor key is 1 and the error is a permission denial, check whether AppArmor is active with sudo aa-status. On Ubuntu 24.04+, use a bwrap profile only when this restriction is present; see Ubuntu's AppArmor guidance. WSL 2 installations do not all use the same kernel policy. Enable systemd only if your chosen profile-loading method needs systemctl and it is unavailable; see Microsoft's WSL instructions. See Sandbox execution for the probe details.

macOS reports Seatbelt is unavailable

Check:

test -x /usr/bin/sandbox-exec

ScienceDiscovery does not silently fall back to unsandboxed execution when Seatbelt is unavailable.

Where are the logs?

Logs are stored under logs/ in the data directory by default. See the configuration reference for exact paths and overrides.

Docker FAQ

Compose rejects systempaths=unconfined

Run docker compose version. This option requires Compose v2.15+. Update the Compose plugin, or update Docker Desktop if it supplies Compose.

macOS Docker Desktop cannot mount the project directory

If Docker Desktop reports Mounts denied or file is not shared from the host, open Settings → Resources → File sharing and add the directory containing the checkout. See Docker's file-sharing settings.

data/ is not writable

Make sure data/ exists before docker compose up. If the logs show a permission error, test the bind mount from inside a container:

docker compose run --rm --entrypoint sh sciencediscovery -c 'id; ls -ld /app/data; touch /app/data/.write-test && rm /app/data/.write-test'

On Linux or macOS, use a Unix shell to check that uid/gid match the .env configuration:

ls -ld data
id -u
id -g

On Windows, check that your account can write to the host data/ directory and that Docker Desktop can share it. Windows accounts do not have Linux uid/gid values to enter in .env. If the Windows bind mount remains unwritable, move the checkout into a WSL 2 distribution's Linux filesystem, enable Docker Desktop's WSL integration, and run Compose there. Then use that Linux user's id -u and id -g values in .env and create data/ as that user.

The container is running but /health is degraded

Inspect:

docker compose logs --tail=200

Check the Runner startup error and the data/ mount first. A sandbox failure can also occur while /health remains ok.

If /health is ok but a code task fails, inspect the logs for could not build a sandbox and check the Linux-container requirements above. On Windows, check Docker Desktop and WSL updates if its sandbox probe fails.

The model or external resources are unreachable

The container needs outbound access to model providers, literature sources, and other external services. If your environment requires a proxy, configure network proxy settings.

After deployment succeeds

Once the service is running, stop reading deployment details and return to the Quick Start:

  1. configure a model;
  2. create a Project and Session;
  3. run the first scientific task;
  4. confirm code execution and the Artifact work.

Further reading