Guides / JavaScript & TypeScript / Install and prerequisites

Install and prerequisites

The npm packages are clients. They do nothing without kosa8 installed and its daemon running on the same machine. This page installs both, checks the connection, and sets up TypeScript.

What you need

$ curl -fsSL https://kosa8.com/install.sh | sh

$ kosa8 version
kosa8 client 0.9.10 (ffaa677, darwin/arm64)
kosa8 daemon: not running (start with `kosa8 daemon start`)

$ kosa8 daemon start
kosa8d started (pid 39965, log /tmp/k8d/.kosa8/log/kosa8d.log)

2026/10/15 19:50:12 fetching guest image kosa8-guest-arm64.tar.gz for v0.9.10
2026/10/15 19:50:46 guest image v0.9.10 installed in /tmp/k8d/.kosa8/guest

$ npm install @kosa8/sdk
# for the Vercel AI SDK, instead or as well:
$ npm install @kosa8/ai-sdk-sandbox ai

import { Kosa8Client } from '@kosa8/sdk';

const kosa8 = new Kosa8Client();
console.log('talking to', kosa8.transport.target);
console.log(await kosa8.health());
console.log('version', await kosa8.version());

$ node health.mjs
talking to unix:///tmp/k8d/.kosa8/run/kosa8.sock
{
  commit: 'ffaa677',
  go: 'go1.26.9',
  phase: '0-foundations',
  status: 'ok',
  uptime_seconds: 34,
  version: '0.9.10'
}
version 0.9.10

When the daemon is not running

Every method rejects with Kosa8ConnectionError, and the message says what to do:

import { Kosa8Client, Kosa8ConnectionError } from '@kosa8/sdk';

const kosa8 = new Kosa8Client({ socketPath: '/tmp/k8d/no-daemon-here.sock' });
try {
  await kosa8.health();
} catch (err) {
  console.log(err instanceof Kosa8ConnectionError, err.name);
  console.log(err.message);
  console.log('cause:', err.cause.code);
}

$ node conn2.mjs
true Kosa8ConnectionError
kosa8 daemon unreachable at unix:///tmp/k8d/no-daemon-here.sock: connect ENOENT /tmp/k8d/no-daemon-here.sock (is kosa8 installed and its daemon running? start it with `kosa8 daemon start`)
cause: ENOENT

TypeScript

Both packages ship .d.ts files for ESM and CommonJS, so there is nothing extra to install. Every option and result has a type. This file typechecks with strict on and runs unchanged under Node's built-in type stripping:

import { Kosa8Client, Kosa8ConnectionError, type Health, type CreateSandboxOptions } from '@kosa8/sdk';
import { createKosa8NetworkSandboxSession } from '@kosa8/ai-sdk-sandbox';

const kosa8 = new Kosa8Client();
const opts: CreateSandboxOptions = { name: 'typed', egressAllow: ['registry.npmjs.org'], memMb: 1024 };
try {
  const h: Health = await kosa8.health();
  console.log(h.version, opts.name, typeof createKosa8NetworkSandboxSession);
} catch (err) {
  if (err instanceof Kosa8ConnectionError) console.error('daemon not running:', err.message);
  else throw err;
}

{ "compilerOptions": { "target": "ES2022", "module": "NodeNext", "moduleResolution": "NodeNext", "strict": true, "skipLibCheck": true, "noEmit": true }, "files": ["check.ts"] }

$ npx tsc -p . && echo CHECK-OK
CHECK-OK
$ node check.ts
0.9.10 typed function

The types catch a misspelt option or an egress value the daemon would refuse:

import { Kosa8Client } from '@kosa8/sdk';
const kosa8 = new Kosa8Client();
await kosa8.createSandbox({ name: 'x', memoryMb: 512 });
await kosa8.createSandbox({ name: 'y', egress: 'none' });

$ npx tsc --ignoreConfig --noEmit --strict --module NodeNext --moduleResolution NodeNext --target ES2022 --skipLibCheck bad.ts
bad.ts(3,40): error TS2353: Object literal may only specify known properties, and 'memoryMb' does not exist in type 'CreateSandboxOptions'.
bad.ts(4,40): error TS2322: Type '"none"' is not assignable to type 'EgressPolicy | undefined'.

Tested with TypeScript 7.0.2. tsx and ts-node work as usual.

CommonJS

const { Kosa8Client } = require('@kosa8/sdk');
new Kosa8Client().version().then((v) => console.log('CommonJS require works, daemon', v));

$ node check.cjs
CommonJS require works, daemon 0.9.10

Apple silicon and Linux