Deploy

Deploy ScienceDiscovery (local or Docker)

Project-local skill for ScienceDiscovery. Authoritative facts live in README.md → Quick start, in docs/zh/getting-started/deployment.md (Chinese) → local mode and Docker deployment, and in docs/zh/reference/configuration.md → variable tables. Read the matching section before improvising; never invent ports, tokens, flags, or paths.

You assist the user through a deployment. You do not silently reconfigure their machine.

Rules

1. Ask the deployment form first (Docker Compose vs. host processes). Do not install, build, or start anything before the user answers.
2. Detect before deploying. Environment checks are read-only commands only. Report what is missing; do not fix it on your own initiative.
3. Never run sudo on the user's behalf unless they explicitly ask for that specific command in this conversation.
4. Never install global software (apt/dnf/brew/npm -g, persistent sysctl, systemd units, editing files outside the repository). List the gap and the command you suggest the user run themselves. After written consent you may assist, still preferring project-local installs (uv/pnpm/corepack) over system-wide ones.
5. Environment must pass before deploying. On any failed check, stop, report, and wait for the user's decision.
6. Repository-local writes are fine (.env, .sciencediscovery-data/), but say what you are writing before you write it.
7. After a successful start, always report the URL and the bearer token source, then the management commands for the mode actually used.

Step 1 — Ask the form

Docker Compose, or host processes?

Both need Linux x86_64 or aarch64 with unprivileged user namespaces — the bubblewrap sandbox is not optional and Docker Desktop on macOS/Windows is unsupported.

Step 2 — Detect (read-only)

Run from the repository root. Report each check as pass/fail with the value seen.

Common

uname -s -m                              # expect: Linux x86_64 or aarch64
ss -ltn | grep -E ':(4310|4311)' || echo "ports free"

Sandbox availability is decided by running the product's probe, never by reading a sysctl. Use the probe below for host-process mode, and the in-container probe under Docker mode for Compose. A sysctl value is a diagnostic to reach for after a probe fails — see Step 3.

Host-process mode (mirrors README.md → Quick start → Requirements)

node --version    # v22.19+
pnpm --version    # 11.1.2
python3 --version
uv --version      # 0.9+
bwrap --version   # 0.6+; 0.8+ recommended (adds --disable-userns where the environment allows it; otherwise the runner logs a startup warning and omits it)
curl --version | head -1

Sandbox preflight — the same probe scripts/start-stack.sh and packages/sandbox-capability run, harmless and read-only:

bwrap --unshare-all --unshare-user --die-with-parent \
  --ro-bind /usr /usr --symlink usr/bin /bin --symlink usr/lib /lib \
  --symlink usr/lib64 /lib64 --proc /proc /usr/bin/true && echo "sandbox ok"

Docker mode

docker version --format '{{.Server.Version}}'   # 24+
docker compose version                          # v2.x
docker info >/dev/null && echo "daemon reachable"
id -u; id -g                                    # → SCIENCE_AGENT_UID / _GID

The container's sandbox can only be probed once the image exists, and the entry point already probes it at startup: a failure is printed to docker compose logs. To confirm it positively after up -d:

docker compose exec sciencediscovery sh -c '
  bwrap --unshare-all --unshare-user --die-with-parent \
    --ro-bind /usr /usr --symlink usr/bin /bin --symlink usr/lib /lib \
    --symlink usr/lib64 /lib64 --proc /proc /usr/bin/true' && echo "sandbox ok"

Keep the outer sh -c. With bwrap as the exec session's first process the loopback setup fails for reasons unrelated to sandbox capability, which reads as a false negative.

Step 3 — Report gaps, do not close them yourself

Present a short table: check / expected / actual / suggested fix. Suggested fixes are for the user to run, quoted as such:

• Missing Node/pnpm/uv → suggest user-level installs that need no sudo and touch nothing outside $HOME: Node 22 tarball extracted to ~/opt/node22 (add its bin to PATH), corepack enable --install-directory ~/.local/bin && corepack prepare $(node -p "require('./package.json').packageManager") --activate for the pinned pnpm, and the official uv installer script (installs to ~/.local/bin). Missing bubblewrap has no user-level path — it is a distro package the user must install.
• Sandbox probe passed → the environment is fine. Do not read kernel.apparmor_restrict_unprivileged_userns, do not report it, and never ask for sudo sysctl -w ...=0. That restriction is configured per AppArmor profile, so the value is routinely 1 on Ubuntu 24.04+ hosts where the probe passes; quoting a root command there is wrong advice.
• Sandbox probe failed → report it and work through the causes in order: the container's security_opt (Docker mode needs seccomp, apparmor and systempaths all unconfined); then the host AppArmor configuration, where /etc/apparmor.d/ can grant userns create per program; and only then sysctl kernel.unprivileged_userns_clone and sysctl kernel.apparmor_restrict_unprivileged_userns. If the last one is the confirmed cause, quote sudo sysctl -w kernel.apparmor_restrict_unprivileged_userns=0, say it needs root and does not persist, and stop for the user's decision.
• Port already in use → offer SCIENCE_AGENT_PORT (host mode) or SCIENCE_AGENT_PUBLISH_PORT (Docker) instead of killing the other process. When moving the runner port, also update the explicit SCIENCE_AGENT_RUNNER_URL in .env — it does not follow *_PORT automatically.
• npm / PyPI unreachable or very slow → set SCIENCE_AGENT_NPM_REGISTRY / SCIENCE_AGENT_PYPI_INDEX in .env (e.g. the Huawei Cloud mirrors; see the variable table in docs/zh/reference/configuration.md). Both are scoped to start-stack.sh's install commands and never touch user or global npm/uv config.

If the sandbox probe keeps failing, the API and UI still start and /health still reports the runner, but every run_python / run_shell fails. Say this plainly and let the user choose whether to continue.

Step 4a — Deploy: host processes

cp .env.example .env                               # first time only; never overwrite an existing .env
./scripts/start-stack.sh --mode local              # install + build + start
./scripts/start-stack.sh --mode local --no-build   # start only, after a previous build

• Runs in the foreground; it starts the runner (127.0.0.1:4311) and the memory-graph sidecar (127.0.0.1:17674) in the background and the API (0.0.0.0:4310) in front. It also starts the bundled Python MCP sidecars.
• Backgrounding it (nohup ./scripts/start-stack.sh --mode local &, tmux, a supervisor) changes how it must be stopped — see Stopping a backgrounded host stack below. Ctrl-C no longer applies.
• First run provisions .sciencediscovery-data/envs/gateway and .sciencediscovery-data/envs/paper through uv and needs outbound network.
• ./scripts/run-local.sh [--no-build] is the compatibility wrapper; pnpm start and pnpm server go through it.
• Never launch it with sudo. For unattended operation, hand the user a supervisor option (tmux, or a systemd user unit) — do not install one.

Step 4b — Deploy: Docker Compose

cp .env.docker.example .env      # or merge its keys into an existing .env
# set SCIENCE_AGENT_UID / SCIENCE_AGENT_GID to `id -u` / `id -g` when they are not 1000
mkdir -p data                    # before `up`: Docker creates a missing bind-mount source as root
docker compose build             # first build is long and needs network
docker compose up -d
curl -fsS http://127.0.0.1:4310/health

• ./data is bind-mounted to /app/data and is the only persisted location; it survives docker compose down and rebuilds.

• A uid/gid mismatch is the most common first-run failure: the entry point exits with an explicit "not writable" message. Fix it via SCIENCE_AGENT_UID / SCIENCE_AGENT_GID and recreate the container. The same message appears when the data directory did not exist at up time: Docker then created it as root, so remove it and mkdir -p it as the user first.

• The sign-in URL in docker compose logs always names the container port

  4310. When SCIENCE_AGENT_PUBLISH_PORT differs, tell the user to substitute the published port before opening it.

• The first start seeds micromamba into ./data/scientific-envs/bin/ and then creates the starter Python environment in the background (conda-forge, about 2 GB into ./data). The UI works meanwhile; runner.scientificEnvs.startersReady in /health turns true when it is done. SCIENTIFIC_ENVS=0 skips it.

• Several instances on one host: give each its own Compose project name, port and data directory. The service sets no container_name, so the project name alone separates container and network names.

  mkdir -p data-b
  COMPOSE_PROJECT_NAME=sciencediscovery-b SCIENCE_AGENT_PUBLISH_PORT=4320 \
    SCIENCE_AGENT_DATA_HOST_DIR=./data-b docker compose up -d

  Every later ps / logs / down needs the same project name, or it acts on the other instance. Add SCIENCE_AGENT_IMAGE when the instances are built from different checkouts.

• The service already sets seccomp=unconfined, apparmor=unconfined and systempaths=unconfined for bubblewrap. Do not add capabilities or privileged: true. Dropping systempaths=unconfined still works, but the runner then falls back to binding the container's /proc and warns at startup: sandboxed code sees the container's process list.

Step 5 — Report the URL

• Default: http://127.0.0.1:4310
• Sign in with SCIENCE_AGENT_AUTH_TOKEN. There is no shipped default: when the variable is unset, the stack generates a token on its first start, prints it at startup, and stores it in <data dir>/secrets/auth-token. Read the value from the user's .env or that file — do not print a token into a shared channel.
• Host-process mode binds all interfaces by default, so http://<machine-ip>:4310 also works. Docker publishes on 127.0.0.1 unless SCIENCE_AGENT_PUBLISH_HOST is changed, and the Open to sign in URL in its log always says port 4310 — report the published port instead when it differs. Auth is one bearer token with no TLS: recommend loopback plus SSH forwarding over exposing the port, and tell the user to change the token first if they do expose it.
• There is no built-in model. A usable session needs a profile plus credential under System configuration → Model registry (docs/zh/reference/runtime-behavior.md → 模型).

Remote host, browser on a laptop

When the stack runs on a remote development machine, forward the port instead of publishing it. Run from the laptop:

remote_user="alice"; remote_host="science-host.example"
ssh -N -L 4310:127.0.0.1:4310 "${remote_user}@${remote_host}"

local_port=4310; remote_port=4310
ssh -f -N -o ServerAliveInterval=30 \
  -L "${local_port}:127.0.0.1:${remote_port}" "${remote_user}@${remote_host}"

Then open http://127.0.0.1:<local-port> locally. <remote-port> is the published port: SCIENCE_AGENT_PORT in host-process mode, SCIENCE_AGENT_PUBLISH_PORT in Docker mode. Pick a different <local-port> if 4310 is taken locally. Stop the tunnel by closing the session, or by killing the backgrounded ssh -f process.

Forward only the API port. The runner (4311) is loopback-only by design.