Docs/SDKs/TypeScript SDK

Node.js 18+ · 2026.8.17

TypeScript SDK

Hand-written TypeScript client for Node.js 18+. Full type definitions, ESM + CJS dual output, async-only API, single-flight 401 refresh. Entry class is exported under four interchangeable names (VxCloud / vxcloud / Vxsdk / Client) so it reads naturally from any of the platform's other-language SDKs.

19 modules — every method shipped in 2026.8.17 is documented below with a runnable example.

TypeScript SDK

Node.js 18+2026.8.17 · 19 modules

Install

install · typescriptbash

npm install @vxcloud/sdk
# or:  pnpm add @vxcloud/sdk
# or:  yarn add @vxcloud/sdk
 
# All four named exports below alias the SAME class — pick whichever
# import name your team prefers:
#   import { VxCloud } from '@vxcloud/sdk';     // canonical (PascalCase)
#   import { vxcloud } from '@vxcloud/sdk';     // lowercase brand
#   import { Vxsdk }   from '@vxcloud/sdk';     // mirrors Python `vxsdk`
#   import { Client }  from '@vxcloud/sdk';     // mirrors `vxsdk.Client`

Quickstart

quickstart.tstypescript

import { VxCloud } from '@vxcloud/sdk';
// Equivalent imports (all alias the same class):
//   import { vxcloud, Vxsdk, Client } from '@vxcloud/sdk';
 
// Auth: load credentials written by `vxcli auth login`
const c = await VxCloud.loadFromVxcli();
// or:  new VxCloud({ apiKey: 'xc_live_…', username: 'alice' });
 
// Provision a VM
const vm = await c.cloud.vm.provision({
  cloud: 'aws', instanceType: 't3.small', region: 'us-east-1',
  keyPairName: 'AWSPRODKEY2',
});
 
// Deploy a Docker container WITH HTTPS — single call.
// Installs host nginx + Let's Encrypt cert in front of the first port (3000).
// Requires grafana.example.com A record -> vm.public_ip already set.
const ssh = {
  host: vm.public_ip as string,
  sshUser: 'ubuntu',
  keyPairName: 'AWSPRODKEY1',          // must be in Vault
};
const sess = await c.deploy.container({
  image: 'grafana/grafana:latest', name: 'grafana',
  ports: ['3000:3000'],
  enableSsl: true,
  domain:    'grafana.example.com',
  sslEmail:  '[email protected]',
  ...ssh,
});
console.log(sess.sessionId, sess.sslCertificateStatus);
 
// Manage it
console.log(await c.services.list(ssh));
await c.services.restart('grafana', ssh);

Modules

Client construction & authentication — 4 examples
sessions — 1 example
deploy (container + 14 stacks) — 4 examples
install (script / compose) — 1 example
services (lifecycle + host ops) — 2 examples
cicd — 1 example
marketplace — 3 examples
cloud (vm / s3 / iam / network / database / kubernetes / serverless) — 5 examples
agentcontrol (full /api/v2/agentcontrol/* surface — 22 sub-resources) — 10 examples
metaldb (self-managed PostgreSQL over SSH) — 1 example
salesshift + leads (tracked email and the prospect pool) — 5 examples
networks (diagnostic scripts) — 1 example
agents (AI orchestration) — 2 examples
chat (multi-provider AI) — 2 examples
observability (backups / migrations / sync) — 1 example
billing — 1 example
workspace setup (35 endpoints) — 6 examples
errors — 1 example
Production notes & known issues — 4 examples

Client construction & authentication

Two constructors — explicit credentials or load from `~/.vxcloud/credentials.json`. Auto-refresh JWT on 401 with single-flight semantics.

1import { VxCloud } from '@vxcloud/sdk';
2 
3const c = new VxCloud({
4  apiKey:   'xc_live_…',
5  username: 'your-username',
6  // optional overrides:
7  // vxcloudURL: 'https://api.vxcloud.io',
8  // nodeURL:     'https://node1.vxcloud.io',
9});
10 
11const me = await c.auth.whoami();
12console.log(me.username);

4 examples

vxsdk

sessions

List, inspect, replay, fetch, or tear down deploy/install sessions.

1for (const s of await c.sessions.list({ limit: 20 })) {
2  console.log((s as any).session_id, (s as any).status);
3}
4 
5await c.sessions.show('adc2d5c4-…');
6await c.sessions.apply('adc2d5c4-…');
7const artifacts = await c.sessions.pull('adc2d5c4-…');
8await c.sessions.delete('adc2d5c4-…', /* force */ true);

1 example

vxsdk

deploy (container + 14 stacks)

Deploy any Docker image, or any of the 14 supported stacks (fastapi, react, nextjs, django, nodejs, python, golang, rust, cpp, php, static, angular, vuejs, expo, flask, java, laravel, metaldb). Source is either a pre-built zip Buffer or a git repo URL. Single-command HTTPS via `enableSsl`/`domain`/`sslEmail` — host nginx + certbot for `container`, shared Traefik for stack deploys.

1// Single call: deploy + cert + nginx vhost.
2// Requires grafana.example.com A record -> 13.216.243.13 already set.
3const sess = await c.deploy.container({
4  image: 'grafana/grafana:latest',
5  name:  'grafana',
6  ports: ['3000:3000'],
7  env:   ['GF_SECURITY_ADMIN_PASSWORD=changeme'],
8  restart: 'unless-stopped',
9  enableSsl: true,
10  domain:    'grafana.example.com',
11  sslEmail:  '[email protected]',
12  host: '13.216.243.13', sshUser: 'ubuntu',
13  keyPairName: 'AWSPRODKEY1',     // must be in Vault
14});
15console.log(sess.sessionId, sess.sslCertificateStatus);

4 examples

vxsdk

install (script / compose)

Apply a custom shell installer or a docker-compose.yml on a remote VM.

1import { readFileSync } from 'node:fs';
2 
3await c.install.script({
4  scriptContent: readFileSync('./my-installer.sh', 'utf-8'),
5  scriptName:    'my-installer.sh',
6  args:          ['--version=2.1'],
7  host: 'h', sshUser: 'ubuntu', keyPairName: 'AWSPRODKEY1.PEM',
8});
9 
10await c.install.compose({
11  composeContent:  readFileSync('./docker-compose.yml', 'utf-8'),
12  envFileContent:  readFileSync('./.env',               'utf-8'),
13  stack: 'myapi',
14  host:  'h', sshUser: 'ubuntu', keyPairName: 'AWSPRODKEY1.PEM',
15});

1 example

vxsdk

services (lifecycle + host ops)

Start / stop / restart / remove / status of a Docker container, plus host-level reboot, cleanup, and diagnostics under `services.vm`.

1const ssh = {
2  host: '203.0.113.24', sshUser: 'ubuntu',
3  keyPairName: 'AWSPRODKEY1.PEM',
4};
5 
6const containers = await c.services.list(ssh);
7for (const x of containers) console.log(x.name, x.status);
8 
9const status = await c.services.status('studio-backend', ssh);
10console.log(status.containers?.[0]?.image, status.containers?.[0]?.status);
11 
12await c.services.start  ('studio-backend', ssh);
13await c.services.stop   ('studio-backend', ssh);
14await c.services.restart('studio-backend', ssh);
15await c.services.remove ('studio-backend', ssh);
16 
17// Logs (systemd unit only)
18const logs = await c.services.logs('ollama', ssh, { tail: 200 });

2 examples

vxsdk

cicd

Manage CI/CD pipelines, trigger builds, inspect runs.

1for (const p of await c.cicd.pipelines.list()) console.log(p.id, p.name);
2 
3const triggered = await c.cicd.pipelines.trigger('studio-api', 'main');
4console.log(triggered);
5 
6const build = await c.cicd.builds.show('<build-id>');
7console.log(build.status);
8 
9const providers = await c.cicd.git.list();

1 example

vxsdk

marketplace

agents / models / solutions: list / show / deploy / provision.

1for (const a of await c.marketplace.agents.list()) {
2  console.log(a.id, a.name);
3}
4 
5await c.marketplace.agents.deploy(
6  'prompt_agent',
7  { host: 'h.vxcloud.io', sshUser: 'ubuntu', keyPairName: 'AWSPRODKEY1.PEM' },
8);

3 examples

vxsdk

cloud (vm / s3 / iam / network / database / kubernetes / serverless)

Per-provider helpers covering VM lifecycle, storage, IAM (policy / role / keypair), networking (VPC), managed databases, Kubernetes, and serverless. `c.cloud.vm.provision(...)` is the symmetric API shared with the Python SDK; pass `name` to use the prod-verified verbose body.

1// Pass `name` to use the prod-verified body shape (matches Python SDK).
2const vm = await c.cloud.vm.provision({
3  name: 'api-vm',
4  cloud: 'aws', instanceType: 't3.small', region: 'us-east-1',
5  keyPairName: 'AWSPRODKEY2',
6  tags: { env: 'staging' },
7});
8 
9// Lifecycle — start | stop | restart | reboot
10const state = await c.cloud.vm.status({ instanceId: vm.instance_id as string, cloud: 'aws' });
11await c.cloud.vm.action({ instanceId: vm.instance_id as string, action: 'restart', cloud: 'aws' });
12 
13// Flat shortcut that mirrors Python's `c.cloud.create_vm(...)`:
14const vm2 = await c.cloud.createVm({
15  name: 'worker-vm',
16  cloud: 'aws', instanceType: 't3.small', region: 'us-east-1',
17  keyPairName: 'AWSPRODKEY2',
18});

5 examples

vxsdk

agentcontrol (full /api/v2/agentcontrol/* surface — 22 sub-resources)

Full UI parity with /dashboard/?tab=agentcontrol. Original surfaces (fineTuning, training, knowledge, datasets, agents, github) plus the new sub-resources: embeddings, tools, mcp, evals, code, models, deployments, webAssets, benchmarks, catalog, health, events, llm, deployTargets, workflows, infra. Plus `runtimeMetrics(endpoint)` to proxy a marketplace agent's /metrics scrape through the node. `tenantId` is read from `~/.vxcloud/credentials.json` by `loadFromVxcli()` and sent as `X-Tenant-ID` on every request; pass `{ tenantId }` per call to override.

1// Top-level dashboard summary — counts, recent activity, etc.
2const summary = await c.agentcontrol.summary();
3console.log(summary.totalModels, summary.activeTrainingJobs);
4 
5// Browse each surface
6for (const j of await c.agentcontrol.fineTuning.list()) console.log('FT:',    j.id, j.status);
7for (const t of await c.agentcontrol.training.list())   console.log('Train:', t.id, t.status);
8for (const k of await c.agentcontrol.knowledge.list())  console.log('KB:',    k.id, k.name);
9for (const d of await c.agentcontrol.datasets.list())   console.log('DS:',    d.id, d.rowCount);

10 examples

vxsdk

metaldb (self-managed PostgreSQL over SSH)

Provision and verify a self-managed PostgreSQL instance on a customer VM. The platform installs Postgres, opens the firewall, creates the user / database, and stores the resulting connection string in workspace Vault under `metaldb/<resource>`. Use this when you want full DB lifecycle ownership instead of a managed RDS / Aurora.

1// Provision Postgres on an existing VM via SSH. Credentials are minted
2// by the platform and written to Vault — no plaintext password leaves
3// the call. Returns the connection string + Vault path.
4const result = await c.metaldb.provision({
5  resourceName: 'app-metaldb',
6  host: '203.0.113.24', sshUser: 'ubuntu',
7  keyPairName: 'AWSPRODKEY1',       // MUST be in Vault
8  dbName: 'app', dbUser: 'app',
9  pgVersion: '16',
10  port: 5432,
11  listenAddress: '0.0.0.0',
12});
13console.log(result.connectionString, '·', result.vaultPath);
14 
15// Verify connectivity from the same node (does not require client psql).
16const ok = await c.metaldb.testConnection({
17  host: '203.0.113.24',
18  port: 5432, dbName: 'app', dbUser: 'app',
19  vaultPath: result.vaultPath as string,    // password fetched from Vault
20});
21console.log('reachable:', ok.connected);

1 example

vxsdk

salesshift + leads (tracked email and the prospect pool)

Two namespaces, deliberately kept apart: `c.salesshift` is the send surface, `c.leads` is the pool — because a lead is not mailable until it becomes a Contact. 22 methods covering 20 of SalesShift’s 306 routes and none of its 57 messaging routes; deals, sequences, quotes, contracts, invoices, calendar and deliverability have no SDK method in any language. This is the most thoroughly typed of the five bindings — ~30 exported interfaces and unions, overloads that make `searchLeads({resultType:'company'})` return a company page, the server caps exported as constants, and named errors. Status: read in full, but not built or executed in the pass that produced this page — `getStats()` is also the one call with no result interface (it returns `Record<string, unknown>`).

1import { VxCloud } from '@vxcloud/sdk';
2 
3const c = await VxCloud.loadFromVxcli();
4 
5const stats = await c.salesshift.getStats();   // Record<string, unknown>
6 
7for (const m of await c.salesshift.listEmails('sent')) {
8  console.log(m.toEmail, m.status, m.openCount);
9}
10 
11const sent = await c.salesshift.sendEmail({
12  toEmail:  '[email protected]',
13  subject:  'Following up, {{first_name}}',
14  bodyHtml: '<p>Saw you shipped v2 — worth 15 minutes?</p>',
15});
16console.log(sent.trackingId, sent.provider);
17// provider ∈ node-smtp | smtp | sendgrid | mailgun | platform | sink
18 
19// The email worker lives on your tenant node, not the control plane.
20const health = await c.salesshift.getWorkerHealth();
21console.log(health.status, health.providers, health.redisConnected);

5 examples

vxsdk

networks (diagnostic scripts)

Catalog of DNS / bandwidth / port-check / security-audit scripts. Local execution is the caller’s job; remote ships through install.script.

1import { readFileSync } from 'node:fs';
2 
3for (const s of await c.networks.list()) {
4  console.log(s.name, s.description);
5}
6 
7await c.networks.runRemote({
8  script:     readFileSync('./port-check.sh', 'utf-8'),
9  scriptName: 'port-check.sh',
10  args:       ['443'],
11  host: 'h', sshUser: 'ubuntu', keyPairName: 'AWSPRODKEY1.PEM',
12});

1 example

vxsdk

agents (AI orchestration)

AI-agent surface mirroring `vxcli agent`. Coding / DevOps / Git / parallel + tool dispatch.

1const out = await c.agents.coding(
2  'Write a FastAPI route that validates a JWT bearer token',
3  'python',
4);
5console.log(out.output);
6 
7await c.agents.devops('deploy main of api/ to staging and roll forward');
8await c.agents.git('draft commit messages for the staged diff');

2 examples

vxsdk

chat (multi-provider AI)

Provider envelope normalizes Anthropic / OpenAI / Google / OpenClaw / Deepseek / Qwen / Groq / Mistral / Perplexity / Hugging Face / Ollama / Hermes / Cohere / Azure-OpenAI / Gemini / Llama.

1const out = await c.chat.send({
2  provider: 'anthropic',
3  model:    'claude-opus-4-7',
4  messages: [
5    { role: 'system', content: 'You are concise.' },
6    { role: 'user',   content: 'What is HCL terraform?' },
7  ],
8  maxTokens: 500,
9});
10console.log(out.completion);

2 examples

vxsdk

observability (backups / migrations / sync)

Snapshot backups, migration plans, batch resource discovery.

1const bk = await c.observability.backups.create({
2  resourceId: 'rds-abc', resourceType: 'database',
3  backupName: 'pre-migration',
4});
5console.log(bk.id, bk.status);
6 
7for (const b of await c.observability.backups.list()) console.log(b.id, b.sizeGb);
8 
9await c.observability.backups.restore({ backupId: bk.id, targetRegion: 'eu-west-1' });
10 
11const plan = await c.observability.migrations.plan({
12  sourceProvider: 'aws', targetProvider: 'gcp', resources: ['rds-abc'],
13});
14await c.observability.migrations.execute(plan.sessionId);

1 example

vxsdk

billing

Cost reporting + AI-powered optimization recommendations.

1const r = await c.billing.multicloud({
2  startDate: '2026-04-01', endDate: '2026-04-30',
3});
4console.log('Total:', r.totalUsd);
5for (const [cloud, usd] of Object.entries(r.breakdown)) console.log(cloud, usd);
6 
7const opt = await c.billing.optimization('aws');
8for (const rec of opt.recommendations) console.log(rec.action, rec.resource);

1 example

vxsdk

workspace setup (35 endpoints)

Workspace + organization lifecycle, cloud-provider creds (Alibaba/AWS/Azure/Google Cloud/Linode), AI-provider creds (16 providers), API tokens, Git/payment/SMTP/SSL/OAuth/OKTA/CyberArk credential storage.

1await c.workspace.createWorkspace('my-org', 'us-east-1');
2 
3await c.workspace.storeAWSCredentials({
4  accessKeyId:     'AKIA…',
5  secretAccessKey: '…',
6  region:          'us-east-1',
7});
8 
9// 16 AI providers — same shape, different path under /api/v2/setup/ai-*
10await c.workspace.storeAICredentials('anthropic', { apiKey: 'sk-ant-…' });
11await c.workspace.storeAICredentials('openai',     { apiKey: 'sk-…', orgId: 'org-…' });
12await c.workspace.storeAICredentials('ollama',     { endpoint: 'http://127.0.0.1:11434' });
13 
14console.log(await c.workspace.getAllAICredentials());

6 examples

vxsdk

errors

Typed error tree — discriminate failure modes via `instanceof`.

1import {
2  VxAuthError, VxValidationError, VxRateLimitError,
3  VxServerError, VxNetworkError, isRetryable,
4} from '@vxcloud/sdk';
5 
6try {
7  await c.deploy.container({ /* … */ });
8} catch (err) {
9  if (err instanceof VxAuthError)        { /* re-run vxcli auth login */ }
10  else if (err instanceof VxValidationError) throw err;
11  else if (isRetryable(err))             { /* back off + retry */ }
12  else                                    throw err;
13}

1 example

vxsdk

Production notes & known issues

Real failure modes you will hit at least once. Same content as the CLI "Operational gotchas" section, adapted to SDK usage.

1// c.deploy.fastapi / react / nextjs / ... server-side validates
2// 'key_pair_name' as required and ignores private_key_pem entirely.
3// Upload the key to Vault once:
4//
5//   vxcli configure setup vm --key-pair-name MYKEY --pem-file ./mykey.pem
6//
7// c.deploy.container() DOES accept a local PEM via privateKeyPem.

4 examples

vxsdk

← Previous SDK

Python SDK

Next SDK →

Go SDK

Back to all SDKs CLI reference

Was this page helpful?

Previous⌨️ CLI Reference Next 📖 Guides