​
Installation

npm install 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

​
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

  1. Resource Cleanup: Always clean up resources when they’re no longer needed:

    await machine.stop();
await machine.delete();

  2. Error Handling: Implement proper error handling for API calls to handle network issues and API errors gracefully.

  3. Configuration Management: Keep machine configurations in version control and use environment variables for dynamic values.

  4. 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";