TypeScript SDK

Installation

npm
yarn
pnpm
bun

npm install valyent.ts

yarn add valyent.ts

pnpm add valyent.ts

bun add valyent.ts

Quick Start

import { Client } from "valyent.ts";

// Initialize the client
const client = new Client("your-api-token");

// Create a new fleet
const fleet = await client.fleets.create({ name: "my-fleet" });

// Deploy a machine in your fleet
const machine = await client.machines.create(fleet.id, {
  region: "gra-1",
  config: {
    image: "nginx:latest",
    guest: {
      cpu_kind: "shared",
      memory_mb: 512,
      cpus: 1,
    },
    workload: {
      env: ["PORT=8080"],
    },
  },
});

Core Concepts

Client

The Client class is the main entry point for interacting with the Valyent Cloud API. It provides access to all available resources through dedicated sub-clients.

const client = new Client(
  apiToken: string,
  namespace?: string,
  endpoint: string = 'https://console.valyent.cloud'
);

Fleets

Fleets are logical groupings of machines. They help organize your resources and manage them collectively.

// List all fleets
const fleets = await client.fleets.list();

// Create a new fleet
const fleet = await client.fleets.create({
  name: "production-fleet",
});

// Get fleet details
const fleet = await client.fleets.get("fleet-id");

// Delete a fleet
await client.fleets.delete("fleet-id");

Machines

Machines are the compute instances running your workloads. Each machine runs in a microVM with its own resources and configuration.

// Create a new machine
const machine = await client.machines.create("fleet-id", {
  region: "us-east-1",
  config: {
    image: "my-image:latest",
    guest: {
      cpu_kind: "shared",
      memory_mb: 1024,
      cpus: 2,
    },
    workload: {
      env: ["KEY=value"],
      restart: {
        policy: "always",
        max_retries: 3,
      },
    },
  },
});

// List machines in a fleet
const machines = await client.machines.list("fleet-id");

// Get machine details
const machine = await client.machines.get("fleet-id", "machine-id");

// Start a machine
await machine.start();

// Stop a machine
await machine.stop({
  timeout: 30,
  signal: "SIGTERM",
});

// Delete a machine
await machine.delete();

Machine Configuration

MachineConfig

object

Show Properties

image

string

required

Docker image to run in the machine

guest

object

required

Show GuestConfig

cpu_kind

string

required

Type of CPU allocation

memory_mb

number

required

Memory allocation in MB (minimum: 1)

cpus

number

required

Number of CPU cores (minimum: 1)

workload

object

required

Show Workload

env

string[]

Environment variables

restart

object

Show RestartPolicyConfig

policy

string

One of: ‘always’, ‘on-failure’, ‘never’

max_retries

number

Maximum number of restart attempts

init

object

Show InitConfig

cmd

string[]

Command to run

entrypoint

string[]

Container entrypoint

user

string

User to run as

stop_config

object

Show StopConfig

timeout

number

Stop timeout in seconds

signal

string

Signal to send (e.g., ‘SIGTERM’)

auto_destroy

boolean

Whether to automatically destroy the machine when stopped

Gateways

Gateways provide network access to your machines. They can be used to expose services running in your machines.

// Create a gateway
const gateway = await client.gateways.create("fleet-id", {
  name: "web-gateway",
  target_port: 8080,
});

// List gateways
const gateways = await client.gateways.list("fleet-id");

// Get gateway details
const gateway = await client.gateways.get("fleet-id", "gateway-id");

// Delete a gateway
await client.gateways.delete("fleet-id", "gateway-id");

Filesystem Operations

The SDK provides access to the machine’s filesystem through the fs property on machine instances.

// List directory contents
const entries = await machine.fs.ls("/app");

// Create a directory
await machine.fs.mkdir("/app/data");

// Read file contents
const content = await machine.fs.readFile("/app/config.json");

// Remove a file or directory
await machine.fs.rm("/app/temp");

// Get file/directory information
await machine.fs.stat("/app/logs");

Logs and Events

You can access machine logs and events for monitoring and debugging:

// Get machine logs
const logs = await machine.getLogs();

// Stream logs in real-time
for await (const log of client.machines.getLogsStream(
  "fleet-id",
  "machine-id"
)) {
  console.log(log.message);
}

// List machine events
const events = await machine.listEvents();

Machine States

Machines can be in the following states:

MachineStatus

enum

created: Initial state after creation - preparing: Machine is being prepared - starting: Machine is starting up - running: Machine is running
stopping: Machine is being stopped - stopped: Machine has stopped - destroying: Machine is being destroyed - destroyed: Machine has been destroyed

You can wait for a specific machine state:

// Wait for machine to be in running state
await machine.wait("running", 60); // timeout in seconds

Error Handling

The SDK throws FetchErrorWithPayload for API errors, which includes both the error message and the response payload:

try {
  await client.machines.create(/* ... */);
} catch (error) {
  if (error instanceof FetchErrorWithPayload) {
    console.error("API Error:", error.message);
    console.error("Error Details:", error.payload);
  }
}

Best Practices

Resource Cleanup: Always clean up resources when they’re no longer needed:
await machine.stop(); await machine.delete();
Error Handling: Implement proper error handling for API calls to handle network issues and API errors gracefully.
Configuration Management: Keep machine configurations in version control and use environment variables for dynamic values.
Monitoring: Use the logs and events APIs to monitor your machines’ health and troubleshoot issues.

TypeScript Support

The SDK is written in TypeScript and provides full type definitions for all APIs. You can import types directly:

import type {
  MachineConfig,
  GuestConfig,
  Workload,
  MachineStatus,
} from "valyent.ts";

Get Started

Deployments

Infrastructure-as-Code

Installation

Quick Start

Core Concepts

Client

Fleets

Machines

Machine Configuration

Gateways

Filesystem Operations

Logs and Events

Machine States

Error Handling

Best Practices

TypeScript Support

​Installation

​Quick Start

​Core Concepts

​Client

​Fleets

​Machines

​Machine Configuration

​Gateways

​Filesystem Operations

​Logs and Events

​Machine States

​Error Handling

​Best Practices

​TypeScript Support

Installation

Quick Start

Core Concepts

Client

Fleets

Machines

Machine Configuration

Gateways

Filesystem Operations

Logs and Events

Machine States

Error Handling

Best Practices

TypeScript Support