1. Install Node.js

In this guide, you write one page and open it in your browser. Cow is a web runtime that runs a directory of .cow files. A folder with one page in it is a complete site.
Install Node.js 22.16 or newer with npm.

2. Make a page

Create a folder called my-site and save this as my-site/index.cow:
my-site/index.cow
<?js const name = req.get('name') || 'world' ?>
<h1>Hello, <?= h(name) ?>!</h1>
The code runs on the server. The HTML goes to the browser. h() escapes the name, so the browser treats it as text, not HTML.

3. Run it

Terminal — from the directory containing my-site
npx @cowlang/cow my-site
If npx asks to install the package, accept. npx downloads Cow into its cache when needed. Add a package.json file only when you install third-party packages.
Open http://127.0.0.1:8000. To say hello to someone else, add ?name=Clover to the URL.
Output — http://127.0.0.1:8000/?name=Clover
<h1>Hello, Clover!</h1>
Edit the page and refresh. Ordinary page and helper changes take effect on the next request.
To stop the server, press Ctrl+C. To use another port, add --port 8001. With no directory argument, Cow serves the current directory.
Note: Use @cowlang/cow. The npx cow command runs an unrelated package.
Bundled helpers such as cow:web and cow:sqlite come from the running Cow installation. They work in plain directories too. Install third-party packages in your site as usual.

Check syntax and choose a runtime

Check a site without running it
npx @cowlang/cow check my-site
Output
Checked 1 file: no syntax errors. Skipped 0 entries.
The syntax check is optional. It is not a build step, and it does not check TypeScript types or resolve imports.
Other guides write cow ... as shorthand. Replace it with npx @cowlang/cow ..., or use one of the installations below.
To run your site on another installed runtime, add --runtime. Stop the server before you switch runtimes.
Choose an installed runtime
npx @cowlang/cow my-site --runtime bun
Node.js starts the npm-installed launcher, which then selects your runtime. Install other runtimes separately. See Runtimes for runtime support and limits.

Install a global command (optional)

Terminal
npm install --global @cowlang/cow
cow my-site
This adds a machine-wide cow command, including its bundled helpers. Sites do not need their own Cow installation. Third-party dependencies remain local to each site.

Install Cow in your project (optional)

To pin the Cow version and make deployments reproducible, install Cow in your site:
Terminal
cd my-site
npm install --save-exact @cowlang/cow
npm exec --offline -- cow .
The install creates package.json and package-lock.json if needed. Keep both in version control. Cow is a runtime dependency, not a development-only build tool. npm exec --offline -- runs the local command without downloading a missing package.
A local install also supplies editor types and exports for standalone Node.js scripts or the embedding API. Cow’s bundled helper resolution applies inside its request loader, not to arbitrary runtime scripts or native adapter dependencies.

Run from a local package

From a Cow source checkout, make an installable archive:
Terminal — Cow repository
npm ci
npm pack
In the next command, use the actual archive path and the filename that npm printed. Replace VERSION to match. Quote paths that contain spaces.
Terminal — from the directory containing my-site
npx --package /path/to/cowlang-cow-VERSION.tgz cow my-site
You do not need a publishing account. npm may download public dependencies. For a project-local install, pass the archive to npm install instead. To run directly from the source checkout, use npm ci followed by node bin/cow.mjs /path/to/site.

Deploy a pinned installation

Use the project-local installation above. Copy your site, its package.json, and its package-lock.json to the server. Keep private data outside public assets. Then, from your my-site directory, run:
Terminal
npm ci --omit=dev
npm exec --offline -- cow check .
npm exec --offline -- cow . --host 127.0.0.1 --port 8000 --mode production
For an application with a separate public directory, replace . in the Cow commands with site. Run Cow with a service manager behind an HTTPS reverse proxy.
Warning: The built-in server uses HTTP and does not trust forwarded headers. Restrict diagnostic routes, and explicitly configure Secure session cookies behind TLS termination.
To upgrade, choose a version, check the site, and restart Cow. Keep the previous lockfile and data backups so that you can roll back.