@hoststack.dev/sdk

Official TypeScript SDK for HostStack — the European PaaS for deploying web services, databases, cron jobs, and domains on Hetzner infrastructure.

Think Render.com, but hosted in Europe, built for developers who care about latency and data residency.

• Website: hoststack.dev
• Documentation: hoststack.dev/docs
• SDK reference: hoststack.dev/docs/sdk
• Source: github.com/miccidk/hoststack

Installation

npm install @hoststack.dev/sdk
# or
bun add @hoststack.dev/sdk
# or
pnpm add @hoststack.dev/sdk

Requires Node.js 18+ (uses native fetch). Works in Bun and Deno too.

Quick start

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

const client = new HostStack({
	apiKey: 'hs_live_your_api_key',
});

const teamId = 1;

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

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

// Stream runtime logs
const ac = new AbortController();
for await (const entry of client.services.streamLogs(teamId, 'svc_abc123', { signal: ac.signal })) {
	console.log(entry.timestamp, entry.message);
}

Generate an API key from your HostStack dashboard → Settings → API Keys.

Resources

| Resource | Methods | | ---------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------- | | client.projects | list, get, create, update, delete | | client.services | list, get, create, update, delete, suspend, resume, getMetrics, getMetricsHistory, getConfig, updateConfig, getRuntimeLogs, streamLogs | | client.deploys | list, get, trigger, cancel, rollback, promote, getLogs | | client.databases | list, get, create, update, delete, suspend, resume, getCredentials, resetPassword, query, upgradeToHa | | client.domains | list, add, update, remove, verify | | client.envVars | list, create, update, delete, bulkSet | | client.volumes | list, create, update, delete | | client.environments | list, get, create, update, delete | | client.cron | list, get, trigger | | client.notifications | listChannels, createChannel, updateChannel, deleteChannel, testChannel |

Every method's first argument is the team id — accepts either the numeric id or the team_… publicId (the SDK resolves publicIds to numeric ids internally and caches the lookup). Full API reference: hoststack.dev/docs/sdk.

client.deploys.promote(teamId, serviceId, deployId, targetEnvironmentId) performs image-based promotion: it pins the same built image into a sibling environment without rebuilding.

Error handling

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

try {
	await client.services.get(teamId, 'svc_missing');
} catch (err) {
	if (err instanceof NotFoundError) {
		// 404
	} else if (err instanceof AuthenticationError) {
		// 401 — API key missing or expired
	} else if (err instanceof ForbiddenError) {
		// 403 — key lacks the required scope (e.g. deploy_only trying to mutate)
	} else if (err instanceof ConflictError) {
		// 409 — resource state prevents the op (already exists, in-flight migration, …)
	} else if (err instanceof RateLimitError) {
		// 429 — err.retryAfter is seconds to wait (from Retry-After header), or undefined
	} else if (err instanceof HostStackError) {
		// any other API error — err.statusCode and err.body are available
	}
}

Related packages

• @hoststack.dev/cli — command-line interface for HostStack
• @hoststack.dev/mcp — MCP server for Claude, Cursor, and other AI agents
• Terraform provider — see hoststack.dev/docs for installation and resource reference

Support

• Issues: github.com/miccidk/hoststack/issues
• Docs: hoststack.dev/docs
• Homepage: hoststack.dev

License

MIT © HostStack Contributors