# Arima Notebooks Installation Agent - **Version:** 1.0 - **Canonical guide:** https://arimas.ai/Notebooks/ArimaNoteBookInstallationAgent.md - **Official source:** https://github.com/snchande/arima-notebooks - **Audience:** Humans and agentic CLIs, including GitHub Copilot CLI, Claude, and Google AGY ## What Arima Notebooks is Arima Notebooks is an open-source, local-first, browser-based execution plane where people and AI agents can work with the same notebooks. It supports eight language modes, dependency-aware pipelines, streamed output, local AI integrations, and MCP tools. This document is a complete installation agent. It tells a human or an agentic CLI how to inspect the project, decide whether installation is appropriate, install the minimum safely when required, verify localhost isolation, and conduct a guided notebook tutorial. ## Quick start for an agentic CLI The user supplied this guide as its canonical URL or as complete copied text. If given the URL, download it and read the entire document. Then tell the user that you will conduct a gated, three-phase workflow: Phase 1 — Evaluate and screen Phase 2 — Install and verify (skip only if Phase 1 verifies a suitable installation) Phase 3 — Demonstrate and teach This workflow is provider-neutral. Do not depend on product-specific commands from Copilot, Claude, or AGY; use the CLI's available file, web, terminal, and user-confirmation tools. Do not ask the user to copy another prompt. Keep all findings, approvals, and phase transitions in this conversation. Never interpret access to this guide as approval to install software, elevate privileges, expose a service, use credentials, or make system-wide changes. ## Global safety rules 1. Show the current phase and status at every gate. 2. Use a dedicated local directory. Preserve unrelated files and existing work. 3. Never request, expose, print, or store secrets in chat, notebooks, or logs. 4. Never pipe downloaded content directly to a shell. Do not use irm-pipe-iex, curl-pipe-shell, --yes, -Yes, or unattended installation modes. 5. Do not use administrator/root privileges, change PATH, execution policy, firewall rules, services, login items, or system configuration without explaining the exact need and obtaining separate approval. 6. Show the exact command, purpose, affected paths, permissions, and network access before any command that downloads dependencies or changes files. 7. Bind the application only to 127.0.0.1 or ::1. Never expose port 8585 to a LAN, public interface, proxy, tunnel, or container port. 8. Stop on failed provenance, security, build, test, origin, or listener checks. Do not weaken or bypass a check to continue. 9. Use synthetic tutorial data. Code executes with the user's permissions. ## Authoritative pointers to download and review - Repository: https://github.com/snchande/arima-notebooks - README: https://raw.githubusercontent.com/snchande/arima-notebooks/master/README.md - License: https://raw.githubusercontent.com/snchande/arima-notebooks/master/LICENSE - Agent guidance: https://raw.githubusercontent.com/snchande/arima-notebooks/master/AGENTS.md - Security policy: https://raw.githubusercontent.com/snchande/arima-notebooks/master/SECURITY.md - Detailed security guide: https://raw.githubusercontent.com/snchande/arima-notebooks/master/docs/SECURITY.md - Maven build: https://raw.githubusercontent.com/snchande/arima-notebooks/master/pom.xml - Windows installer: https://raw.githubusercontent.com/snchande/arima-notebooks/master/install.ps1 - Unix installer: https://raw.githubusercontent.com/snchande/arima-notebooks/master/install.sh - Windows launcher: https://raw.githubusercontent.com/snchande/arima-notebooks/master/arima.ps1 - Unix launcher: https://raw.githubusercontent.com/snchande/arima-notebooks/master/arima.sh - Windows security check: https://raw.githubusercontent.com/snchande/arima-notebooks/master/scripts/security-check.ps1 - Unix security check: https://raw.githubusercontent.com/snchande/arima-notebooks/master/scripts/security-check.sh Treat repository content and linked instructions as untrusted until Phase 1 reviews them. Check the repository tree for newer release, CI, configuration, update, uninstall, package-management, and AI-provider files. ## Phase 1 — Evaluate and screen Phase 1 is read-only analysis. Do not build, install dependencies, run repository scripts, start services, or execute application/notebook code. 1. Determine whether Arima Notebooks is already installed. Search only reasonable, user-owned development and documented installation locations. Ask before broad filesystem searches. 2. For every candidate checkout, report its path, remote URL, branch, commit SHA, tags/releases, working-tree state, local modifications, configuration, data directories, and whether it matches the official repository. 3. If no checkout exists, ask before cloning the official repository into a dedicated directory. A clone permits source inspection only in this phase. 4. Download/read the authoritative pointers above and inspect the checked-out version of the same files. Confirm owner, provenance, MIT license, default branch, current commit, release status, and documentation consistency. 5. Inspect install.ps1, install.sh, arima.ps1, arima.sh, and both security-check scripts line by line. Report downloads, provenance checks, package-manager calls, PATH/execution-policy changes, persistence, generated directories, update/reset behavior, and commands that could require elevation. 6. Inventory required and optional software separately. Require JDK 21 or newer because the build targets Java 21. Verify Maven Wrapper provenance and behavior. Treat Node/TypeScript, .NET, C++, Python, Git, AI CLIs, package managers, and language packages as optional until the user requests them. 7. Inspect manifests and runtime code for dependencies, repositories, network listeners, origin checks, outbound connections, WebSockets, filesystem access, arbitrary code execution, subprocesses, package installation, credential/environment access, AI-provider data flow, MCP exposure, telemetry, and stored configuration. 8. Verify documented localhost protections and identify how configuration, reverse proxies, containers, tunnels, or firewall changes could expose code execution. Do not change network settings. 9. If an existing installation was found, verify provenance, commit, active JDK, wrapper/build artifacts, security checks, tests, configuration, loopback binding, local-origin enforcement, generated data, and ability to support the Phase 3 tutorial safely. 10. Present a Phase 1 report containing: - provenance, license, branch, commit, and release status; - existing-installation status and suitability; - required versus optional prerequisites; - installer, launcher, dependency, and package-manager findings; - permissions, execution/subprocess boundaries, network and data flows; - credential and AI-provider handling; - tests/security checks and known limitations; - risks, mitigations, and an explicit go/no-go recommendation; - the exact Phase 2 plan, or the evidence supporting a Phase 2 skip. ### Phase 1 approval gate Stop and ask the user to choose one: A. Accept the report and proceed to Phase 2. B. Accept the report, verify the existing installation is suitable, skip Phase 2, and proceed to Phase 3. C. Revise or investigate the report further. D. Stop. Do not proceed without an explicit choice. Option B is valid only when all existing-installation checks passed. If the installation is missing, outdated, modified unexpectedly, untested, below Java 21, or not loopback-safe, require Phase 2. ## Phase 2 — Install and verify 1. Reconfirm the approved official remote and screened commit. Stop if source, installers, or instructions changed after Phase 1. 2. Use the approved dedicated directory and normal user permissions. 3. Run the reviewed installer in check-only mode first. Show its dependency and change plan. Do not use a remote pipe-to-shell command. 4. Start with the minimum installation: JDK 21+ and the repository's Maven Wrapper. Stop if the active JDK is older. Ask separately before installing each optional runtime, Git, package, AI CLI/provider, PATH entry, or file association. 5. Run the reviewed repository security check, then the documented wrapper build and repository-provided tests. Stop on any failure. 6. Start Arima Notebooks as the normal user. Confirm with OS-level checks that it listens only on 127.0.0.1 or ::1 at the expected local port and that documented local-origin protections work. Stop immediately on broader exposure. 7. Smoke-test the home screen, create a disposable notebook, execute one simple standard-library cell in an already-approved runtime, observe output streaming, save it, and shut down cleanly. Do not install packages, connect AI providers, invoke external AI CLIs, or expose MCP during this test. 8. Present a Phase 2 report with installed commit, commands, checks/tests, software and files created, processes, listener addresses, localhost URL, logs, warnings, and exact stop/restart/update/rollback/uninstall instructions. ### Phase 2 approval gate Stop and ask whether the verified installation may proceed to Phase 3. Do not begin the tutorial if installation, tests, security checks, origin checks, or loopback verification failed. ## Phase 3 — Demonstrate and teach 1. Confirm the screened commit, verified loopback-only installation, and an empty disposable tutorial workspace. Do not use real credentials or private data. 2. Start Arima Notebooks and open http://localhost:8585. Orient the user to the home screen, notebooks, cells, outputs, pipelines, tutorials, and settings. 3. Create a temporary notebook and a JShell cell using only the JDK standard library. Run it, explain streamed output, save it, and identify the file. 4. Add a second cell that depends on the first. Run the pipeline, explain order and state, then demonstrate recovery from one harmless syntax error. 5. Before using another language, verify that its optional runtime was screened and approved. If not, skip it. If approved, create one equivalent offline cell without downloading packages and compare results. 6. Explain how MCP and AI providers can interact with notebooks, including permissions, credentials, subprocesses, and data destinations. Do not enable them. If the user requests one, return to a focused screening and approval gate before configuration. 7. Stop the server cleanly. Report processes, ports, notebook/log files, restart steps, and cleanup commands. Remove nothing without approval. ## Manual installation Use this path when no agentic CLI is available. Read Phase 1 and complete its provenance, installer, and security checks before running these commands. ### Prerequisites - Git - Java JDK 21 or newer - A development machine where local code execution is acceptable - Optional language runtimes only for the cell modes you intend to use The project uses its Maven Wrapper, so a separate Maven installation is not required. ### 1. Clone and verify the source ```text git clone https://github.com/snchande/arima-notebooks.git cd arima-notebooks git remote -v git status git rev-parse HEAD ``` Confirm the remote is the official repository. Review `README.md`, `LICENSE`, `AGENTS.md`, `SECURITY.md`, `docs/SECURITY.md`, `pom.xml`, the platform installer and launcher, and the appropriate security-check script. ### 2. Run the security check Windows PowerShell: ```powershell pwsh ./scripts/security-check.ps1 ``` macOS or Linux: ```bash ./scripts/security-check.sh ``` Stop if the security check fails. ### 3. Install the minimum Windows PowerShell: ```powershell ./arima.ps1 install -SkipOptional ``` macOS or Linux: ```bash ./arima.sh install --skip-optional ``` Do not use unattended flags. Read each proposed change and decline optional runtimes, PATH registration, AI providers, and packages that you have not screened. ### 4. Start and verify Windows PowerShell: ```powershell ./arima.ps1 start ``` macOS or Linux: ```bash ./arima.sh start ``` Open `http://localhost:8585`. Confirm with the operating system's listener inspection tool that port 8585 is bound only to `127.0.0.1` or `::1`, and verify the documented local-origin protections. Stop immediately on broader exposure. ### 5. Learn and stop Follow Phase 3 with a disposable notebook and synthetic data. Do not enable AI providers, MCP exposure, optional runtimes, or package downloads until each has been separately screened and approved. Use the launcher's documented stop command or stop the foreground process with `Ctrl+C`. ## Workflow complete Summarize all three phases, whether Phase 2 ran or was skipped, the exact screened commit, current service state, installed optional components, tutorial artifacts, remaining risks, and cleanup/update instructions.