HostStack Docs

TypeScript SDK Reference

Manage your HostStack infrastructure programmatically with full TypeScript types. Works on Node.js 18+, Bun 1.1+, and Deno.

Installation

npm

npm install @hoststack.dev/sdk

bun

bun add @hoststack.dev/sdk

deno

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

Quick Start

typescript

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

const client = new HostStack({
  apiKey: process.env.HOSTSTACK_API_KEY!, // hs_live_... or hs_test_...
});

const teamId = 1; // your team ID — see hoststack whoami

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

// Trigger a deploy
const { deploy } = await client.deploys.trigger(teamId, 'svc_abc123');

// Get build logs for that deploy
const { logs } = await client.deploys.getLogs(teamId, 'svc_abc123', deploy.publicId);

Every resource method takes teamId as its first argument. Find your team ID in the dashboard URL, with hoststack whoami, or via the get_me MCP tool. Public IDs like svc_abc123, dpl_xyz, and db_def are accepted anywhere a string id is expected.

Available Resources

client.projectslist, get, create, update, delete

client.serviceslist, get, create, update, delete, suspend, resume, getMetrics, getMetricsHistory, getConfig, updateConfig, getRuntimeLogs, streamLogs

client.deployslist, get, trigger, cancel, rollback, promote, getLogs

client.databaseslist, get, create, update, delete, suspend, resume, getCredentials, resetPassword, query, upgradeToHa

client.domainslist, add, update, remove, verify

client.envVarslist, create, update, delete, bulkSet

client.volumeslist, create, update, delete

client.environmentslist, get, create, update, delete

client.cronlist, get, trigger

client.notificationslistChannels, createChannel, updateChannel, deleteChannel, testChannel

Examples

Manage environment variables

typescript

// Create a single variable. Keys must match /^[A-Z_][A-Z0-9_]*$/.
await client.envVars.create(teamId, 'svc_abc123', {
  key: 'DATABASE_URL',
  value: 'postgres://...',
  isSecret: true,
});

// Bulk set up to 1000 variables in one call.
await client.envVars.bulkSet(teamId, 'svc_abc123', {
  vars: [
    { key: 'NODE_ENV', value: 'production' },
    { key: 'API_SECRET', value: 'sk_...', isSecret: true },
  ],
});

Deploy and monitor

typescript

// Trigger a deploy
const { deploy } = await client.deploys.trigger(teamId, 'svc_abc123');

// Poll status until terminal
const { deploy: status } = await client.deploys.get(teamId, 'svc_abc123', deploy.publicId);
console.log(status.status); // 'pending' | 'building' | 'deploying' | 'live' | 'failed' | 'cancelled'

// Roll back to a previous deploy
await client.deploys.rollback(teamId, 'svc_abc123', 'dpl_previous');

Database management

typescript

// Create a Postgres database.
// projectId here is the numeric internal id, NOT the 'prj_...' publicId
// — pass team.publicId / svc.publicId everywhere else, but project id is
// numeric for backwards-compat with v0.x callers.
const { database } = await client.databases.create(teamId, {
  name: 'my-db',
  engine: 'postgres',
  version: '18',
  projectId: 42,
});

// Get connection credentials — accepts the publicId returned above
const { credentials } = await client.databases.getCredentials(teamId, database.publicId);
console.log(credentials.connectionUrl);

Stream runtime logs

typescript

// Async-iterable runtime-log stream. AbortController stops the stream
// cleanly (server detects the close and tears down the subscription).
const ac = new AbortController();
setTimeout(() => ac.abort(), 60_000); // run for 60s

for await (const entry of client.services.streamLogs(teamId, 'svc_abc123', {
  signal: ac.signal,
})) {
  console.log(entry.timestamp, entry.level, entry.message);
}

Error Handling

Every HTTP error becomes a typed exception. Catch the specific subclass for the cases you want to recover from; fall back to HostStackError for everything else. err.statusCode is the underlying HTTP status.

typescript

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

try {
  await client.services.get(teamId, 'svc_invalid');
} catch (error) {
  if (error instanceof NotFoundError) {
    console.log('Service not found');
  } else if (error instanceof RateLimitError) {
    // Back off and retry — the underlying request did not mutate.
    await new Promise((r) => setTimeout(r, 5_000));
  } else if (error instanceof AuthenticationError) {
    console.log('API key rejected — rotate it at Settings → API Keys');
  } else if (error instanceof HostStackError) {
    console.log(error.statusCode, error.message);
  } else {
    throw error;
  }
}

Next: Managed Databases · CLI Reference