{"id":28310912,"url":"https://github.com/valyentdev/valyent.ts","last_synced_at":"2026-02-07T06:32:36.295Z","repository":{"id":268754906,"uuid":"900681230","full_name":"valyentdev/valyent.ts","owner":"valyentdev","description":" A TypeScript SDK to get stuff done with Valyent's API.","archived":false,"fork":false,"pushed_at":"2025-01-29T13:43:13.000Z","size":412,"stargazers_count":3,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-05-31T23:17:51.187Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/valyentdev.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2024-12-09T09:21:23.000Z","updated_at":"2025-03-09T19:28:33.000Z","dependencies_parsed_at":"2025-01-09T10:42:52.740Z","dependency_job_id":"e995202f-ca5b-4f98-9cd9-863be19da5ca","html_url":"https://github.com/valyentdev/valyent.ts","commit_stats":null,"previous_names":["valyentdev/valyent.ts"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/valyentdev/valyent.ts","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/valyentdev%2Fvalyent.ts","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/valyentdev%2Fvalyent.ts/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/valyentdev%2Fvalyent.ts/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/valyentdev%2Fvalyent.ts/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/valyentdev","download_url":"https://codeload.github.com/valyentdev/valyent.ts/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/valyentdev%2Fvalyent.ts/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":29188226,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-02-07T05:07:31.176Z","status":"ssl_error","status_checked_at":"2026-02-07T05:06:15.227Z","response_time":63,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.6:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2025-05-24T12:10:10.320Z","updated_at":"2026-02-07T06:32:36.289Z","avatar_url":"https://github.com/valyentdev.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Valyent TypeScript SDK\n\nOfficial TypeScript SDK for interacting with the Valyent Cloud platform.\n\n## Installation\n\n```bash\n# npm\nnpm install valyent.ts\n\n# yarn\nyarn add valyent.ts\n\n# pnpm\npnpm add valyent.ts\n\n# bun\nbun add valyent.ts\n```\n\n## Quick Start\n\n```typescript\nimport { Client } from 'valyent.ts';\n\n// Initialize the client\nconst client = new Client('your-api-token');\n\n// Create a new fleet\nconst fleet = await client.fleets.create({ name: 'my-fleet' });\n\n// Deploy a machine in your fleet\nconst machine = await client.machines.create(fleet.id, {\n  region: 'gra-1',\n  config: {\n    image: 'nginx:latest',\n    guest: {\n      cpu_kind: 'shared',\n      memory_mb: 512,\n      cpus: 1,\n    },\n    workload: {\n      env: ['PORT=8080'],\n    },\n  },\n});\n```\n\n## Core Concepts\n\n### Client\n\nThe 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.\n\n```typescript\nconst client = new Client(\n  apiToken: string,\n  namespace?: string,\n  endpoint: string = 'https://console.valyent.cloud'\n);\n```\n\n### Fleets\n\nFleets are logical groupings of machines. They help organize your resources and manage them collectively.\n\n```typescript\n// List all fleets\nconst fleets = await client.fleets.list();\n\n// Create a new fleet\nconst fleet = await client.fleets.create({\n  name: 'production-fleet',\n});\n\n// Get fleet details\nconst fleet = await client.fleets.get('fleet-id');\n\n// Delete a fleet\nawait client.fleets.delete('fleet-id');\n```\n\n### Machines\n\nMachines are the compute instances running your workloads. Each machine runs in a microVM with its own resources and configuration.\n\n```typescript\n// Create a new machine\nconst machine = await client.machines.create('fleet-id', {\n  region: 'us-east-1',\n  config: {\n    image: 'my-image:latest',\n    guest: {\n      cpu_kind: 'shared',\n      memory_mb: 1024,\n      cpus: 2,\n    },\n    workload: {\n      env: ['KEY=value'],\n      restart: {\n        policy: 'always',\n        max_retries: 3,\n      },\n    },\n  },\n});\n\n// List machines in a fleet\nconst machines = await client.machines.list('fleet-id');\n\n// Get machine details\nconst machine = await client.machines.get('fleet-id', 'machine-id');\n\n// Start a machine\nawait machine.start();\n\n// Stop a machine\nawait machine.stop({\n  timeout: 30,\n  signal: 'SIGTERM',\n});\n\n// Delete a machine\nawait machine.delete();\n```\n\n### Machine Configuration\n\nThe machine configuration consists of several key components:\n\n- **image** (string, required): Docker image to run in the machine\n\n- **guest** (object, required):\n\n  - cpu_kind (string, required): Type of CPU allocation\n  - memory_mb (number, required): Memory allocation in MB (minimum: 1)\n  - cpus (number, required): Number of CPU cores (minimum: 1)\n\n- **workload** (object, required):\n\n  - env (string[]): Environment variables\n  - restart:\n    - policy (string): One of: 'always', 'on-failure', 'never'\n    - max_retries (number): Maximum number of restart attempts\n  - init:\n    - cmd (string[]): Command to run\n    - entrypoint (string[]): Container entrypoint\n    - user (string): User to run as\n\n- **stop_config**:\n\n  - timeout (number): Stop timeout in seconds\n  - signal (string): Signal to send (e.g., 'SIGTERM')\n\n- **auto_destroy** (boolean): Whether to automatically destroy the machine when stopped\n\n### Gateways\n\nGateways provide network access to your machines. They can be used to expose services running in your machines.\n\n```typescript\n// Create a gateway\nconst gateway = await client.gateways.create('fleet-id', {\n  name: 'web-gateway',\n  target_port: 8080,\n});\n\n// List gateways\nconst gateways = await client.gateways.list('fleet-id');\n\n// Get gateway details\nconst gateway = await client.gateways.get('fleet-id', 'gateway-id');\n\n// Delete a gateway\nawait client.gateways.delete('fleet-id', 'gateway-id');\n```\n\n### Filesystem Operations\n\nThe SDK provides access to the machine's filesystem through the fs property on machine instances.\n\n```typescript\n// List directory contents\nconst entries = await machine.fs.ls('/app');\n\n// Create a directory\nawait machine.fs.mkdir('/app/data');\n\n// Read file contents\nconst content = await machine.fs.readFile('/app/config.json');\n\n// Remove a file or directory\nawait machine.fs.rm('/app/temp');\n\n// Get file/directory information\nawait machine.fs.stat('/app/logs');\n```\n\n### Logs and Events\n\nYou can access machine logs and events for monitoring and debugging:\n\n```typescript\n// Get machine logs\nconst logs = await machine.getLogs();\n\n// Stream logs in real-time\nfor await (const log of client.machines.getLogsStream(\n  'fleet-id',\n  'machine-id'\n)) {\n  console.log(log.message);\n}\n\n// List machine events\nconst events = await machine.listEvents();\n```\n\n### Machine States\n\nMachines can be in the following states:\n\n- created: Initial state after creation\n- preparing: Machine is being prepared\n- starting: Machine is starting up\n- running: Machine is running\n- stopping: Machine is being stopped\n- stopped: Machine has stopped\n- destroying: Machine is being destroyed\n- destroyed: Machine has been destroyed\n\nYou can wait for a specific machine state:\n\n```typescript\n// Wait for machine to be in running state\nawait machine.wait('running', 60); // timeout in seconds\n```\n\n## Error Handling\n\nThe SDK throws FetchErrorWithPayload for API errors, which includes both the error message and the response payload:\n\n```typescript\ntry {\n  await client.machines.create(/* ... */);\n} catch (error) {\n  if (error instanceof FetchErrorWithPayload) {\n    console.error('API Error:', error.message);\n    console.error('Error Details:', error.payload);\n  }\n}\n```\n\n## Best Practices\n\n1. **Resource Cleanup**: Always clean up resources when they're no longer needed:\n\n```typescript\nawait machine.stop();\nawait machine.delete();\n```\n\n2. **Error Handling**: Implement proper error handling for API calls to handle network issues and API errors gracefully.\n\n3. **Configuration Management**: Keep machine configurations in version control and use environment variables for dynamic values.\n\n4. **Monitoring**: Use the logs and events APIs to monitor your machines' health and troubleshoot issues.\n\n## TypeScript Support\n\nThe SDK is written in TypeScript and provides full type definitions for all APIs. You can import types directly:\n\n```typescript\nimport type {\n  MachineConfig,\n  GuestConfig,\n  Workload,\n  MachineStatus,\n} from \"valyent.ts\";\n```\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fvalyentdev%2Fvalyent.ts","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fvalyentdev%2Fvalyent.ts","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fvalyentdev%2Fvalyent.ts/lists"}