Installation
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
Docker image to run in the machine
Memory allocation in MB (minimum: 1)
Number of CPU cores (minimum: 1)
One of: ‘always’, ‘on-failure’, ‘never’
Maximum number of restart attempts
Signal to send (e.g., ‘SIGTERM’)
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:
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" ;