Install the tools

For

Anyone who can open a terminal

Time

5 minutes, or 15 if Node.js must be installed

You need

Windows, macOS or Linux · An internet connection for the first run

Status

Draft

Open a terminal#

The tools have no window of their own: you type commands in a terminal and read what they print.

These tabs choose your shell for the whole documentation: every command below, and on the other pages, follows your choice.

Check Node.js#

Node.js runs the tools. Check its version:

node --version

It prints a version such as v22.20.0 or v24.12.0. The first number must be 22 or more.

If the terminal answers that node is not recognised, or command not found, Node.js is not installed. If the first number is below 22, it is too old. In both cases, install the current version.

Install or update Node.js#

• From nodejs.org: download the installer marked LTS, for long-term support, from nodejs.org. Run it with its default options, then close the terminal and open a new one, so that it finds node.
• With a package manager, if you already use one: winget on Windows, Homebrew on macOS.

winget install OpenJS.NodeJS.LTS

winget install OpenJS.NodeJS.LTS

brew install node

On Linux, the nodejs package of your distribution may be older than 22: follow the instructions for your distribution on nodejs.org instead.

If you need several versions of Node.js side by side, use a version manager: nvm on macOS and Linux, nvm-windows on Windows.

Choose how to run hos#

The hos command is the npm package @hos-ai/cli. There are three ways to run it:

• npx downloads the package the first time, keeps it in npm's cache and runs it. There is nothing to install or remove: it is the best way to try the tools, and the one the Quickstart uses.
• A global install puts hos on your computer, in every folder. You update it yourself.
• A project install writes the version in the project's package.json and package-lock.json, so every developer and the CI run the same one. Run it from the project's folder.

The first time npx runs the package, it asks before downloading it:

Need to install the following packages:
@hos-ai/cli@0.1.0-alpha.1
Ok to proceed? (y)

Press Enter to accept. It does not ask again for this version.

Check the install#

npx @hos-ai/cli --version

@hos-ai/cli 0.1.0-alpha.1 (HOS 0.1.0-draft.2)

With a global install, type hos --version; with a project install, npx hos --version. The first number is the version of the command, the second the draft of the HOS specification it checks.

--help lists the commands:

npx @hos-ai/cli --help

PowerShell and Windows#

Three things behave differently on Windows. The Command Prompt is not affected by the first two.

Running scripts is disabled#

PowerShell may refuse to run npx, npm or hos with a message that contains:

cannot be loaded because running scripts is disabled on this system.

Windows ships with PowerShell scripts disabled, and npx, npm and hos are started by small scripts. There are two ways around it:

• Type npx.cmd, npm.cmd or hos.cmd instead. They do the same, without a script.
• Or allow scripts written on your computer, and signed ones from elsewhere, for your account only. Your organisation may forbid it: then use the first way.

Set-ExecutionPolicy -Scope CurrentUser RemoteSigned

curl is another command#

In Windows PowerShell 5.1, the version that comes with Windows, curl is another name for Invoke-WebRequest, which takes other options: it asks for a Uri instead of downloading. Press Ctrl+C, and type curl.exe, the real curl, which comes with Windows 10 and 11. The commands on these pages do it for you when PowerShell is your shell.

Quotes in --impl#

hos conformance run --impl starts your program through the Command Prompt, whatever your shell: quote paths with double quotes, not single quotes.

Install the SDK#

For developers who write TypeScript or JavaScript. In your project's folder:

npm install @hos-ai/sdk

The SDK runs in Node.js 22 or later, and in a browser through a bundler. It is an ES module. To check it, save these two lines as check.mjs:

import { HOS_SPEC_VERSION } from "@hos-ai/sdk";
console.log(HOS_SPEC_VERSION);

and run them:

node check.mjs

0.1.0-draft.2

The SDK reference and Build an adapter will describe what it offers. Meanwhile, its npm page has an example of each part.

Behind a company network#

If npm cannot reach the internet, it fails with codes such as ETIMEDOUT, ECONNREFUSED, ENOTFOUND or SELF_SIGNED_CERT_IN_CHAIN. Ask your IT team for the address of the company proxy or npm registry, then give it to npm:

npm config set proxy http://proxy.example.com:8080
npm config set https-proxy http://proxy.example.com:8080

or, with an internal registry that mirrors npm:

npm config set registry https://npm.example.com/

npm config get registry shows the registry npm uses now. An internal registry must carry @hos-ai/cli and @hos-ai/sdk, and the packages they depend on.

Update or remove#

npx may reuse the version it downloaded before: add @latest to be sure you run the newest. The tools are alphas, and their changelog lists what changes between versions.

Next steps#

• Quickstart: a first result in ten minutes.
• Concepts: the ideas behind what the tools print.