ci: run shellcheck at warning severity

The first run reported only info-level notes (SC2015 in update.sh, SC2012 and
SC2086 on the intentional glob in backup.sh), which made the job fail.

.env.example

@@ -1,5 +1,8 @@
 # Docker deployment configuration (copy to .env)
 # The image is built locally by `docker compose build`; there is no registry tag.
+# Address the web UI is published on. 127.0.0.1 keeps it host-local; set 0.0.0.0
+# to reach it from another machine or from Windows when ARTEX runs inside WSL.
+ARTEX_BIND_ADDR=127.0.0.1
 POSTGRES_USER=artex
 POSTGRES_PASSWORD=change-me-please
 POSTGRES_DB=artex

.github/workflows/ci.yml

@@ -44,6 +44,21 @@ jobs:
         # as rotating failures in the agent package). Serial package execution
         # keeps the database state deterministic.
         run: go test -p 1 ./...
+      - name: go test -race
+        # Race detector on the packages that pass under -race today. ./server is
+        # left out until it has been checked with -race against postgres.
+        run: >-
+          go test -race -p 1 ./agent ./cmd/artex ./config ./db ./evidence ./guard
+          ./intercept ./llmpool ./llmrec ./mcphttp ./notify ./sidequestion ./traffic
+
+  shell:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      # shellcheck is preinstalled on the ubuntu runners. -S warning: the scripts
+      # currently have only info-level notes (intentional A && B || C chains in
+      # update.sh, an unquoted glob in backup.sh's prune), so fail on warnings.
+      - run: shellcheck -S warning install.sh update.sh start.sh scripts/backup.sh
 
   web:
     runs-on: ubuntu-latest

README.md

@@ -88,6 +88,9 @@ The script will: detect / auto-install Docker → then let you choose **① all-
 - **② Local run**: choose a database (connect to an existing one / start one with Docker) → generates `config.json` → `go` builds the embedded single binary → starts.
 
 Once installed, open **http://localhost:8787** (on first entry, `/setup` sets the admin password).
+`/setup` asks for a one-time setup token: while no password is set, the backend prints it at startup in its log (`docker compose logs artex | grep "Setup token"`, or the terminal running `./start.sh`).
+
+The web UI is published on `127.0.0.1` by default. To reach it from another machine, or from Windows when ARTEX runs inside WSL, set `ARTEX_BIND_ADDR=0.0.0.0` in `.env` (the setup token still protects the first-run claim), or keep loopback and use a reverse proxy or an SSH tunnel.
 
 ### Option 2: Docker Compose (manual)
 

docker-compose.yml

@@ -35,7 +35,7 @@ services:
       ARTEX_LLM_BASE_URL: ${ARTEX_LLM_BASE_URL:-}
       ARTEX_LLM_PROXY: ${ARTEX_LLM_PROXY:-}
     ports:
-      - "8787:8787"
+      - "${ARTEX_BIND_ADDR:-127.0.0.1}:8787:8787"
       - "127.0.0.1:8788:8788"
     volumes:
       # Bind the data directory (jwt.key, SQLite, etc.) to data/ in the project root,

server/auth.go

@@ -2,6 +2,8 @@ package server
 
 import (
 	"crypto/rand"
+	"crypto/subtle"
+	"encoding/hex"
 	"fmt"
 	"log"
 	"math/big"
@@ -154,7 +156,34 @@ func (s *Server) authStatus(w http.ResponseWriter, r *http.Request) {
 	writeJSON(w, 200, map[string]any{"initialized": hash != ""})
 }
 
+// initSetupToken generates the one-time setup token when no admin password is set
+// and writes it to the server log. Without it, anyone who can reach the port
+// before the operator could claim the instance through POST /api/auth/init.
+func (s *Server) initSetupToken() {
+	if s.m == nil || s.m.pg == nil {
+		return
+	}
+	if hash, _, err := s.m.pg.GetSetting(authPassKey); err == nil && hash != "" {
+		return
+	}
+	buf := make([]byte, 16)
+	if _, err := rand.Read(buf); err != nil {
+		log.Fatalf("[auth] generate setup token: %v", err)
+	}
+	s.setupToken = hex.EncodeToString(buf)
+	log.Printf("[auth] no admin password is set. Setup token for the /setup page: %s", s.setupToken)
+}
+
+// checkSetupToken compares got with the active setup token in constant time.
+// It fails when no token is active.
+func (s *Server) checkSetupToken(got string) bool {
+	s.setupMu.Lock()
+	defer s.setupMu.Unlock()
+	return s.setupToken != "" && subtle.ConstantTimeCompare([]byte(got), []byte(s.setupToken)) == 1
+}
+
 // POST /api/auth/init — sets the password for the first time; rejected if already set.
+// Requires the setup token from the server log.
 func (s *Server) authInit(w http.ResponseWriter, r *http.Request) {
 	pg := s.pg(w)
 	if pg == nil {
@@ -170,12 +199,18 @@ func (s *Server) authInit(w http.ResponseWriter, r *http.Request) {
 		return
 	}
 	var req struct {
-		Password string `json:"password"`
+		Password   string `json:"password"`
+		SetupToken string `json:"setup_token"`
 	}
 	if err := decode(r, &req); err != nil || req.Password == "" {
 		writeErr(w, 400, "Password cannot be empty")
 		return
 	}
+	// 403, not 401: the frontend treats any 401 as an expired session and redirects to /login.
+	if !s.checkSetupToken(req.SetupToken) {
+		writeErr(w, 403, "Invalid setup token. The server log prints it at startup while no password is set")
+		return
+	}
 	if msg := validatePassword(req.Password); msg != "" {
 		writeErr(w, 400, msg)
 		return
@@ -197,6 +232,9 @@ func (s *Server) authInit(w http.ResponseWriter, r *http.Request) {
 		writeErr(w, 403, "Password is already set")
 		return
 	}
+	s.setupMu.Lock()
+	s.setupToken = ""
+	s.setupMu.Unlock()
 	tok, err := signJWT(s.jwtKey)
 	if err != nil {
 		writeErr(w, 500, "token generation failed")

server/auth_test.go

@@ -62,6 +62,62 @@ func TestAuthInitFailsClosedWhenDataSourceUnavailable(t *testing.T) {
 	}
 }
 
+// While no password is set, authInit must reject a missing or wrong setup token
+// and accept the one generated at startup, once.
+func TestAuthInitRequiresSetupToken(t *testing.T) {
+	m, err := NewManager(t.TempDir(), "")
+	if err != nil {
+		t.Skipf("postgres unavailable (%v)", err)
+	}
+	defer m.Close()
+	clearPassword := func() {
+		if _, err := m.pg.Exec(`DELETE FROM settings WHERE key=$1`, authPassKey); err != nil {
+			t.Fatal(err)
+		}
+	}
+	clearPassword()
+	defer clearPassword()
+
+	s := &Server{m: m, jwtKey: []byte("0123456789abcdef0123456789abcdef")}
+	s.initSetupToken()
+	setupToken := s.setupToken
+	if setupToken == "" {
+		t.Fatal("no setup token generated while no password is set")
+	}
+	post := func(body string) *httptest.ResponseRecorder {
+		w := httptest.NewRecorder()
+		s.authInit(w, httptest.NewRequest("POST", "/api/auth/init", strings.NewReader(body)))
+		return w
+	}
+
+	for name, body := range map[string]string{
+		"missing": `{"password":"correct horse battery"}`,
+		"empty":   `{"password":"correct horse battery","setup_token":""}`,
+		"wrong":   `{"password":"correct horse battery","setup_token":"0000"}`,
+	} {
+		if w := post(body); w.Code != 403 || strings.Contains(w.Body.String(), `"token"`) {
+			t.Fatalf("%s setup token: status=%d want 403 without a token; body=%s", name, w.Code, w.Body.String())
+		}
+	}
+	if hash, _, err := m.pg.GetSetting(authPassKey); err != nil || hash != "" {
+		t.Fatalf("a rejected request changed the password state: hash set=%v err=%v", hash != "", err)
+	}
+
+	ok := `{"password":"correct horse battery","setup_token":"` + setupToken + `"}`
+	if w := post(ok); w.Code != 200 || !strings.Contains(w.Body.String(), `"token"`) {
+		t.Fatalf("right setup token: status=%d want 200 with a token; body=%s", w.Code, w.Body.String())
+	}
+	if hash, _, err := m.pg.GetSetting(authPassKey); err != nil || hash == "" {
+		t.Fatalf("password not stored: err=%v", err)
+	}
+
+	// The token is spent: even with the password row removed, it is refused.
+	clearPassword()
+	if w := post(ok); w.Code != 403 {
+		t.Fatalf("reused setup token: status=%d want 403; body=%s", w.Code, w.Body.String())
+	}
+}
+
 func TestValidatePassword(t *testing.T) {
 	for _, tc := range []struct {
 		name, pw string

server/server.go

@@ -48,6 +48,9 @@ type Server struct {
 
 	scrubSecrets bool // drop ARTEX_PG_DSN and the API keys from the environment once read (binary only)
 
+	setupMu    sync.Mutex
+	setupToken string // one-time token POST /api/auth/init requires; empty when none is active
+
 	// concMu serializes concurrency-cap decisions (admission + reconcile) so a
 	// scheduler tick and an HTTP settings change / task creation can't both count
 	// free slots off the same snapshot and over-promote past the limit.
@@ -153,6 +156,7 @@ func New(ctx context.Context, m *Manager, skillDir string, dataDir string, keyDi
 		profChatAgents: map[int64]*agent.ChatAgent{},
 		provByProfile:  map[int64]*provEntry{}, llmHealth: newLLMHealthRegistry(m.pg),
 		taskAgents: map[string]*taskAgentBundle{}, archiveWake: make(chan struct{}, 1)}
+	s.initSetupToken()
 	s.initSideQuestions()
 	// Circuit-breaker thresholds/cooldowns are hot parameters on the failure path; push the global retry policy to the Registry once at startup,
 	// and again on every policy save (saveLLMRetryPolicy).

web/src/app/(auth)/setup/page.tsx

@@ -14,6 +14,7 @@ export default function SetupPage() {
   const router = useRouter();
   const [password, setPassword] = useState("");
   const [confirm, setConfirm] = useState("");
+  const [setupToken, setSetupToken] = useState("");
   const [error, setError] = useState("");
   const [loading, setLoading] = useState(false);
   const [checking, setChecking] = useState(true);
@@ -47,7 +48,7 @@ export default function SetupPage() {
     setLoading(true);
     setError("");
     try {
-      const { token } = await api.initPassword(password);
+      const { token } = await api.initPassword(password, setupToken.trim());
       auth.setToken(token);
       router.replace("/function/tasks");
     } catch (err) {
@@ -80,7 +81,7 @@ export default function SetupPage() {
             <p className="mx-auto max-w-xl text-muted-foreground">
               {unavailable
                 ? "The backend or database is temporarily unavailable. To avoid overwriting a password already set on this instance, setup is temporarily closed — restore the service and try again."
-                : "First time using ARTEX? Set a login password for the account (at least 8 characters)"}
+                : "First time using ARTEX? Enter the setup token from the server log, then set a login password for the account (at least 8 characters)"}
             </p>
           </div>
           {unavailable ? (
@@ -92,6 +93,17 @@ export default function SetupPage() {
             </div>
           ) : (
             <form onSubmit={handleSubmit} className="flex flex-col gap-4">
+              <div className="space-y-1.5">
+                <Label htmlFor="setup-token">Setup token</Label>
+                <Input
+                  id="setup-token"
+                  value={setupToken}
+                  onChange={(e) => setSetupToken(e.target.value)}
+                  placeholder="Printed in the server log at startup"
+                  autoFocus
+                  autoComplete="off"
+                />
+              </div>
               <div className="space-y-1.5">
                 <Label htmlFor="password">New password</Label>
                 <Input
@@ -100,7 +112,6 @@ export default function SetupPage() {
                   value={password}
                   onChange={(e) => setPassword(e.target.value)}
                   placeholder="At least 8 characters"
-                  autoFocus
                   autoComplete="new-password"
                 />
               </div>
@@ -116,7 +127,11 @@ export default function SetupPage() {
                 />
               </div>
               {error && <p className="text-sm text-destructive">{error}</p>}
-              <Button type="submit" className="w-full" disabled={loading || !password || !confirm}>
+              <Button
+                type="submit"
+                className="w-full"
+                disabled={loading || !setupToken.trim() || !password || !confirm}
+              >
                 {loading ? "Saving..." : "Set password and sign in"}
               </Button>
             </form>

web/src/lib/api.ts

@@ -240,7 +240,8 @@ export const api = {
   // ---- auth ----
   authStatus: () => get<{ initialized: boolean }>("/auth/status"),
   login: (username: string, password: string) => post<{ token: string }>("/auth/login", { username, password }),
-  initPassword: (password: string) => post<{ token: string }>("/auth/init", { password }),
+  initPassword: (password: string, setupToken: string) =>
+    post<{ token: string }>("/auth/init", { password, setup_token: setupToken }),
   changePassword: (oldPassword: string, newPassword: string) =>
     post<{ ok: boolean }>("/auth/change-password", { old_password: oldPassword, new_password: newPassword }),