Installation Modes and Provider Matrix

March 15, 2026 ยท View on GitHub

Use the interactive installer:

./scripts/install.sh

It generates:

  • backend/.env.generated
  • frontend/.env.generated
  • deployment.mode.generated

Installer prompts include:

  • Deployment mode preset (1-4)
  • Object storage provider
  • Document metadata provider (sqlite/Turso)
  • ResearchOps metadata provider (Mongo local/Atlas)
  • Network topology (direct/FRP/FRP+Tailscale)
  • Twitter/X Playwright refresh execution target (backend vs client)
  • Frontend compile target + deploy target
  • Backend compile target + deploy target
  • Optional ARIS workflow integration flag

Supported deployment modes

  1. Frontend local, backend remote, cloud databases
  2. All local (frontend + backend + local databases)
  3. All remote with cloud databases
  4. All remote with self-hosted databases on same server

Paper storage providers

  • aws-s3
  • minio (local host server, local client machine, or LAN device)
  • aliyun-oss (S3 compatible endpoint mode)

Configured by:

  • OBJECT_STORAGE_PROVIDER
  • OBJECT_STORAGE_BUCKET
  • OBJECT_STORAGE_REGION
  • OBJECT_STORAGE_ACCESS_KEY_ID
  • OBJECT_STORAGE_SECRET_ACCESS_KEY
  • OBJECT_STORAGE_ENDPOINT
  • OBJECT_STORAGE_FORCE_PATH_STYLE
  • OBJECT_STORAGE_PUBLIC_BASE_URL

Common MinIO endpoint examples:

  • MinIO on backend host: OBJECT_STORAGE_ENDPOINT=http://127.0.0.1:9000
  • MinIO on another LAN device/client: OBJECT_STORAGE_ENDPOINT=http://192.168.x.x:9000

Metadata providers

Documents/tags/auth (libSQL layer):

  • local sqlite: TURSO_DATABASE_URL=file:./local.db
  • Turso cloud: TURSO_DATABASE_URL=libsql://...

ResearchOps metadata (Mongo layer):

  • local MongoDB: MONGODB_URI=mongodb://127.0.0.1:27017/...
  • MongoDB Atlas: MONGODB_URI=mongodb+srv://...

Remote offload options

  • direct (no FRP)
  • FRP offload
  • FRP + Tailscale

Related env keys:

  • PROCESSING_ENABLED
  • PROCESSING_DESKTOP_URL
  • TRACKER_PROXY_HEAVY_OPS
  • TRACKER_PROXY_STRICT
  • TRACKER_EXECUTION_TARGET
  • TRACKER_STALE_AUTO_RUN
  • TRACKER_STALE_PROXY_AUTO_RUN
  • TRACKER_STALE_RUN_TRIGGER_MS
  • TAILSCALE_ENABLED
  • TAILSCALE_DESKTOP_URL

Tracker execution target

Installer now asks where Twitter/X Playwright refresh should run:

  • backend target:

    • TRACKER_ENABLED=true
    • TRACKER_PROXY_HEAVY_OPS=false
    • scheduler/refresh runs on backend node.

  • client target (proxied):

    • TRACKER_ENABLED=false
    • TRACKER_PROXY_HEAVY_OPS=true
    • TRACKER_PROXY_STRICT=true (no fallback to backend-local heavy run)
    • refresh only runs when the client executor is reachable/online.

24h stale refresh behavior:

  • Installer sets TRACKER_STALE_RUN_TRIGGER_MS=86400000 (24h).
  • On client checks (/api/tracker/status), if last refresh is older than threshold and client executor is online, backend triggers a proxied refresh.
  • If client executor is offline, no refresh is started.

Helper scripts:

./scripts/set-do-tracker-proxy.sh
./scripts/verify-frp-offload.sh

ARIS workflow integration

The installer can also enable ARIS integration metadata in deployment.mode.generated.

ARIS is intended to run on the always-on WSL/local executor host, not on the browser machine. The frontend ARIS workspace launches runs against that persistent runner so autonomous loops can continue if the laptop sleeps or the browser tab closes.

The actual project-side install is handled by:

./scripts/setup-aris-integration.sh /path/to/project

That flow:

  • materializes the full AIRS skill tree into the target project's .claude/skills/*
  • applies the Auto Researcher overlay for research-lit
  • writes a managed CLAUDE.md block into the target project
  • prints the MCP registration commands for the Auto Researcher library backend
  • assumes a persistent remote workspace model where code sync is incremental and datasets remain on remote paths instead of being uploaded from the client
  • pairs naturally with managed SSH server records, where the WSL runner is the ARIS control plane and other servers are downstream experiment targets
  • expects the chosen WSL runner to have claude installed and reachable through the configured SSH server record; set ARIS_REMOTE_AGENT_BIN if the binary name differs

Configurable environment variables:

  • ARIS_SKILLS_REPO
  • ARIS_SKILLS_REF
  • ARIS_INTEGRATION_ENABLED

VS Code companion surface

The VS Code companion is not a separate deployment mode. It is a client surface that talks to the existing backend.

Use it when:

  • ARIS is already running through the normal backend/local-executor topology
  • you want a compact in-editor control surface for tracked papers, library actions, and ARIS runs
  • you do not need Chrome-extension save flows or browser capture inside VS Code

The extension currently depends on the backend exposing:

  • GET /api/tracker/feed
  • POST /api/upload/arxiv
  • GET /api/documents
  • GET /api/documents/:id/notes
  • PATCH /api/documents/:id/read
  • POST /api/reader/queue/:documentId
  • GET /api/aris/context
  • GET /api/aris/runs
  • GET /api/aris/runs/:runId
  • POST /api/aris/runs
  • POST /api/aris/runs/:runId/retry
  • POST /api/aris/runs/:runId/actions

The ARIS web workspace also assumes:

  • projects are created inside the ARIS workspace, not invented as a default placeholder
  • the local project folder is linked from the browser with the File System Access API
  • each project stores one or more saved deployment targets
  • each target points to an existing SSH server record plus a remote project path
  • remote dataset/checkpoint/output roots live on the saved target, not in the main launcher
  • launches select project + target + workflow + prompt
  • sync should be incremental and may become a no-op when files are already current or when shared filesystem metadata applies

The extension package lives in vscode-extension/. Development details are in vscode-extension/README.md.