@harchos/sdk

The Official TypeScript/JavaScript SDK for HarchOS — Carbon-Aware GPU Orchestration Platform

HarchOS is the Operating System for Sovereign AI Infrastructure. This SDK provides typed access to the HarchOS API with sovereign defaults: region="morocco", sovereignty="strict", carbon_aware=true.

Install

npm install @harchos/sdk
# or
yarn add @harchos/sdk
# or
pnpm add @harchos/sdk

Quick Start

import { HarchOS } from "@harchos/sdk";

const client = new HarchOS({ apiKey: "hsk_..." });

// Carbon-aware scheduling — HarchOS's key differentiator
const carbon = await client.carbon.intensity("MA");
console.log(`Morocco: ${carbon.carbon_intensity_gco2_kwh} gCO2/kWh`);
console.log(`Renewable: ${carbon.renewable_percentage}%`);

// Find the greenest hub for your workload
const optimal = await client.carbon.optimalHub({
  region: "morocco",
  gpu_count: 4,
  gpu_type: "a100",
});
console.log(`Best hub: ${optimal.recommended_hub_name}`);
console.log(`Action: ${optimal.action}`);

// Optimize workload scheduling
const result = await client.carbon.optimize({
  workload_name: "training-job",
  gpu_count: 4,
  gpu_type: "a100",
  carbon_aware: true,
  carbon_max_gco2: 100,
});
console.log(`Action: ${result.action}, CO2 saved: ${result.carbon_saved_kg} kg`);

// List all hubs
const hubs = await client.hubs.list();
console.log(`${hubs.total} hubs, ${hubs.items.length} visible`);

// Create a carbon-aware workload
const workload = await client.workloads.create({
  name: "llama-training",
  workload_type: "training",
  compute: { gpu_count: 8, gpu_type: "a100" },
  carbon_aware: true,
});

Configuration

Environment Variables

export HARCHOS_API_KEY="hsk_..."
export HARCHOS_BASE_URL="https://api.harchos.ai/v1"
export HARCHOS_REGION="morocco"
export HARCHOS_SOVEREIGNTY="strict"
export HARCHOS_TIMEOUT="30"
export HARCHOS_MAX_RETRIES="3"

Then create a client with no arguments:

const client = HarchOS.fromEnv();

Programmatic Configuration

const client = new HarchOS({
  apiKey: "hsk_test_development_key_12345",
  baseURL: "https://api.harchos.ai/v1",
  region: "morocco",
  sovereignty: "strict",
  carbonAware: true,
  timeout: 30,
  maxRetries: 3,
});

API Reference

client.carbon — Carbon-Aware Scheduling

HarchOS is the only GPU orchestration platform with a native Carbon API.

Method	Description
carbon.intensity(zone)	Get real-time carbon intensity for a zone
carbon.listIntensities()	Get carbon intensity for all zones
carbon.optimalHub(params)	Find the greenest hub for a workload
carbon.optimize(params)	Optimize workload scheduling by carbon intensity
carbon.forecast(zone, hours?)	Get carbon intensity forecast
carbon.metrics(periodDays?)	Get aggregate carbon metrics
carbon.dashboard()	Get full carbon dashboard data

client.hubs — Sovereign Compute Hubs

Method	Description
hubs.list(params?)	List hubs with optional filtering
hubs.get(hubId)	Retrieve a hub by ID
hubs.create(spec)	Create a new hub
hubs.update(hubId, spec)	Update a hub
hubs.capacity(hubId)	Get hub capacity
hubs.scale(hubId, targetGpuCount)	Scale a hub
hubs.drain(hubId)	Drain a hub
hubs.delete(hubId)	Delete a hub

client.workloads — Workload Management

Method	Description
workloads.list(params?)	List workloads with filtering
workloads.get(workloadId)	Retrieve a workload
workloads.create(spec)	Create a new workload
workloads.update(workloadId, spec)	Update a workload
workloads.cancel(workloadId)	Cancel a running workload
workloads.pause(workloadId)	Pause a workload
workloads.resume(workloadId)	Resume a paused workload
workloads.delete(workloadId)	Delete a workload

Other Resources

• client.energy — Energy consumption and reporting
• client.models — Available AI models
• client.pricing — Pricing plans and cost estimation
• client.regions — Region information
• client.monitoring — Platform monitoring and health
• client.health() — API health check

Error Handling

import { HarchOSError, RateLimitError, NotFoundError } from "@harchos/sdk";

try {
  const hub = await client.hubs.get("non-existent-id");
} catch (error) {
  if (error instanceof NotFoundError) {
    console.log("Hub not found");
  } else if (error instanceof RateLimitError) {
    console.log(`Rate limited. Retry after: ${error.retryAfter}s`);
  } else if (error instanceof HarchOSError) {
    console.log(`HarchOS error: ${error.message} (code: ${error.code})`);
  }
}

Competitor Comparison

Feature	HarchOS	Modal	Replicate	Together
Carbon API	✅	❌	❌	❌
Sovereignty Controls	✅	❌	❌	❌
Data Residency	✅	❌	❌	❌
Carbon-Aware Scheduling	✅	❌	❌	❌
Python SDK	✅	✅	✅	✅
TypeScript/JS SDK	✅	✅	❌	❌
CLI	✅	❌	❌	❌
African Hubs	✅	❌	❌	❌

Python SDK

Also available on PyPI:

pip install harchos

License

MIT © HarchCorp