TypeScript SDK

Install

npm install @hoststack.dev/sdk

bun add @hoststack.dev/sdk

import { HostStack } from 'npm:@hoststack.dev/sdk';

The package ships ES module and CommonJS builds with type definitions, and declares Node.js 18 or later. It has no runtime dependencies: it needs only the global fetch and AbortSignal.timeout, so Bun and Deno work too.

Create a client

Create an API key under Settings → API keys in the dashboard, then pass it to the constructor. The key is sent as a bearer token on every request.

import { HostStack } from '@hoststack.dev/sdk';

const client = new HostStack({ apiKey: process.env.HOSTSTACK_API_KEY! });

// An API key is bound to one team; me() tells you which.
const { team } = await client.me();
const teamId = team!.id;

const { services } = await client.services.list(teamId);

apiKey

stringrequired

An hs_live_… or hs_test_… key. The constructor throws apiKey is required without one.

baseUrl

string

The API origin. A trailing slash is removed. A non-https URL other than localhost or 127.0.0.1 logs a warning, because the key would travel in cleartext.

Default: https://hoststack.dev

timeoutMs

number

Per-request timeout in milliseconds. A request that runs over is aborted and throws a HostStackError with statusCode 0. 0 turns the timeout off.

Default: 30000

maxRetries

number

Automatic retries for failures that are safe to repeat — see Retries and timeouts. 0 turns them off.

Default: 2

userAgent

string

The User-Agent header. Set it to name your integration in the API's logs.

Default: hoststack-sdk/<version>

A key's permission is either full access or deploy only. A deploy-only key is refused with a ForbiddenError on every call that needs full access — bulk env var writes and deleting a volume among them.

Team IDs

Every resource method takes the team as its first argument. The only calls that don't are client.me() and client.teams.list(), which are how you find it:

• client.me() returns { user, team, apiKey }. With an API key, user is null and team is the team the key belongs to.
• client.teams.list() returns the teams the caller can reach — for an API key, that one team.
• hoststack whoami prints it as Team ID, and the MCP server's get_me tool returns it.

The team argument takes the numeric id or the team's team_… public id.

IDs

Most id arguments are typed IdInput: a number, a numeric string, or a public id with the right prefix. The SDK turns a public id into the numeric id the API uses by reading the matching list once, then caches the answer for the life of the client.

A public id with the wrong prefix throws a HostStackError with status 400; one that matches nothing throws NotFoundError.

Resources

The client has 18 resources. Each method returns a promise of the JSON the API answers with, usually wrapped in a named key — { service }, { databases } — and undefined for calls that answer 204 No Content.

client.request(method, path, body?) is public too: it sends an authenticated request to any API path with the same retries and typed errors, for an endpoint the resources don't wrap yet. See the API reference.

Projects, environments and teams

Services

streamLogs polls the logs endpoint — 100 lines first, then every 2 seconds — and yields each new entry. Stop it with an AbortSignal; the loop ends without throwing.

const ac = new AbortController();
setTimeout(() => ac.abort(), 60_000); // stop after a minute

for await (const entry of client.services.streamLogs(teamId, 'svc_...', {
  signal: ac.signal,
  stream: 'stderr',     // optional
  pollInterval: 2000,   // default
  initialLines: 100,    // default
})) {
  console.log(entry.timestamp, entry.level, entry.message);
}

Deploys

A deploy's status is one of pending, building, build_failed, deploying, live, failed, cancelled, deactivated or superseded.

const { deploy } = await client.deploys.trigger(teamId, 'svc_...');

const done = new Set(['live', 'failed', 'build_failed', 'cancelled']);
let status = deploy.status;
while (!done.has(status)) {
  await new Promise((r) => setTimeout(r, 5_000));
  ({ deploy: { status } } = await client.deploys.get(teamId, 'svc_...', deploy.id));
}

Environment variables

Keys match ^[A-Za-z_][A-Za-z0-9_]*$, up to 256 characters, and are case-sensitive. Values can be up to 32,768 characters. Changes reach the container on the next deploy.

await client.envVars.create(teamId, 'svc_...', {
  key: 'STRIPE_SECRET_KEY',
  value: 'sk_live_...',
  isSecret: true,
});

// Everything not listed here is removed from the service.
await client.envVars.bulkSet(teamId, 'svc_...', {
  vars: [
    { key: 'NODE_ENV', value: 'production' },
    { key: 'API_SECRET', value: '...', isSecret: true },
  ],
});

Databases

const { database } = await client.databases.create(teamId, {
  name: 'app-db',
  engine: 'postgres',
  projectId: project.id, // numeric, not the prj_… public id
});

const { credentials } = await client.databases.getCredentials(teamId, database.publicId);
console.log(credentials.connectionUrl);

Resource links

A database is not reachable from a service until you link it. A link injects the resource's connection details as environment variables, prefixed with its alias — a database linked as APP_DB gives APP_DB_URL, APP_DB_HOST, APP_DB_PORT, APP_DB_DATABASE, APP_DB_USERNAME and APP_DB_PASSWORD. The first linked database of each kind also sets DATABASE_URL (Postgres, MySQL, MariaDB), REDIS_URL or MONGO_URL, unless you set that variable yourself.

await client.serviceResourceLinks.create(teamId, 'svc_...', {
  resourceType: 'database',
  resourceId: database.id, // numeric id, not db_…
  alias: 'APP_DB',
});

// A link takes effect on the NEXT deploy — nothing changes until then.
await client.deploys.trigger(teamId, 'svc_...');

Domains and DNS

Volumes

Cron jobs

Machines

Your own hardware, once enrolled. The SDK can only read machines: enrolling one prints an installer that has to be run on the machine itself, so it is done with hoststack machines add or in the dashboard.

const { machines } = await client.machines.list(teamId);
const desktop = machines.find((m) => m.name === 'desktop');
if (!desktop) throw new Error('enrol it first: hoststack machines add desktop');

await client.services.create(teamId, {
  name: 'api',
  type: 'web_service',
  projectId: project.id,
  githubRepo: 'acme/my-app',
  machineId: desktop.id, // leave it out to run on HostStack compute
});

machineId is fixed when a service, database or dev box is created. A database on your own machine can only be linked to services on that same machine.

Dev tasks

Error tracking

Uptime checks

The input fields are enabled, path, method (GET or HEAD), expectedStatus, timeoutMs, intervalSeconds (30 to 3600) and failureThreshold.

Analytics

range is 24h, 7d, 30d, 90d or 12mo.

Notifications

Retries and timeouts

Retries depend on whether repeating the request is safe:

• GET requests are retried on 429, any 5xx, a network error and a timeout.
• POST, PUT, PATCH and DELETE are retried only on 429, which means the request was refused before it ran. After a 5xx or a dropped connection the change may already have happened, so retrying could deploy twice.

A retry waits for the Retry-After header when there is one (up to 60 seconds), and otherwise backs off from 250 ms, doubling each time. With the default maxRetries: 2, a call is tried at most three times before the error reaches you.

Error handling

Every failed request throws a HostStackError or one of its subclasses. statusCode is the HTTP status (0 for a timeout or network error), message is the API's error text, and body is the parsed response, with field-level validation details when there are any.

import {
  AuthenticationError,
  HostStackError,
  NotFoundError,
  RateLimitError,
} from '@hoststack.dev/sdk';

try {
  await client.services.get(teamId, 'svc_...');
} catch (err) {
  if (err instanceof NotFoundError) {
    console.log('No such service');
  } else if (err instanceof RateLimitError) {
    // The SDK has already retried; wait as long as the API asked.
    await new Promise((r) => setTimeout(r, (err.retryAfter ?? 5) * 1000));
  } else if (err instanceof AuthenticationError) {
    console.log('API key rejected — create a new one under Settings → API keys');
  } else if (err instanceof HostStackError) {
    console.log(err.statusCode, err.message);
  } else {
    throw err;
  }
}

Next steps

• CLIThe same operations from a terminal or a CI step.
• MCP serverLet Claude, Cursor and other agents call these for you.
• API referenceThe REST endpoints underneath every SDK method.
• Managed databasesEngines, plans, backups and linking in depth.