TypeScript SDK

import { Idyl } from "@idyl-labs/sdk";

import { credentialSourceFunc, staticToken } from "@idyl-labs/sdk";

staticToken("<token>");
credentialSourceFunc(async ({ signal }) => await exchangeToken({ signal }));

import { Idyl, onSubnet, staticToken } from "@idyl-labs/sdk";

const idyl = new Idyl({
  network: "idyl.network",
  accountId: "<account-id>",
  namespace: "<namespace>",
  placement: onSubnet("<subnet>"),
  credential: staticToken("<token>"),
});

const sandbox = await idyl.sandboxes.createAndWait({
  image: "ubuntu:24.04",
  ttlMs: 30 * 60_000,
});
await sandbox.delete();

import { onFleet } from "@idyl-labs/sdk";

const namespaced = idyl.forNamespace("<namespace>");
const onFleetClient = namespaced.withPlacement(onFleet("<fleet-id>"));

namespaced.scope;
// { accountId, namespace: "<namespace>", placement }

import { onFleet, onNode, onNodeInSubnet, onSubnet } from "@idyl-labs/sdk";

onSubnet("<subnet>");
onFleet("<fleet-id>");
onNode("<node-id>");
onNodeInSubnet("<node-id>", "<subnet>");

const bound = idyl.withSubnetEndpoint(
  "<subnet>",
  "https://subnet-api.example.com",
);

const sandbox = await idyl.sandboxes.get("dev");
const current = await sandbox.refresh();
current.phase; // the phase observed by refresh
sandbox.phase; // the phase observed when this handle was built

const deployment = await idyl.deployments.createAndWait(
  {
    name: "web",
    replicas: 3,
    container: { image: "nginx:1.27", cpu: "500m", memory: "512Mi" },
  },
  { timeoutMs: 5 * 60_000 },
);

const scaled = await deployment.scale(5);
const job = await idyl.cronJobs.trigger("nightly");
await job.waitUntilComplete();

import { Identity } from "@idyl-labs/sdk";

const identity = new Identity({ network: "idyl.network" });
await identity.startAuth({ email: "<email>" });
const verified = await identity.verifyAuth({ email: "<email>", code: "<code>" });
const token = await identity.getProfileAccessToken(verified.refreshToken, {
  account: "<organization>/<account>",
  profile: "<profile>",
});

import { Discovery } from "@idyl-labs/sdk";

const discovery = new Discovery({ network: "idyl.network" });
const regions = await discovery.regions.list();
const subnets = await discovery.subnets.list();

await idyl.workloadSessions.logs(
  { target: { kind: "Sandbox", name: "dev" }, request: { follow: true } },
  (chunk) => {
    process.stdout.write(chunk);
  },
  (chunk) => {
    process.stderr.write(chunk);
  },
);

const shell = await idyl.workloadSessions.openShellTransport({
  target: { kind: "Sandbox", name: "dev" },
  publicKey: sessionPublicKey,
});
try {
  // shell.ssh names the username, the one-use certificate bound to the
  // key, and the host CAs a host key may be accepted from; shell.transport
  // is the readable and writable byte pair an SSH client speaks over.
  await runSshClient(shell.ssh, shell.transport);
} finally {
  await shell.transport.close();
}

const snapshot = await idyl.workloads.list({ kind: "Deployment" });
const watch = await idyl.watchWorkloads({
  kinds: ["Deployment"],
  cursor: snapshot.snapshotCursor,
});
try {
  for await (const event of watch) {
    handle(event); // a LiveEnvelope; decodeObserved(event.object) types it
  }
} finally {
  await watch.close();
}

import {
  ERROR_CODE_NAMESPACE_TERMINATING,
  PlacementUnavailableError,
  isApiCode,
  isApiStatus,
  isNotFound,
} from "@idyl-labs/sdk";

try {
  await idyl.sandboxes.delete("dev");
} catch (error) {
  if (isNotFound(error)) {
    // The Sandbox is already gone.
  } else if (isApiStatus(error, 429)) {
    await new Promise((resolve) => {
      setTimeout(resolve, error.retryAfterMs ?? 1_000);
    });
  } else if (isApiCode(error, ERROR_CODE_NAMESPACE_TERMINATING)) {
    // The Namespace is being deleted and accepts no further writes.
  } else if (error instanceof PlacementUnavailableError) {
    // error.reason names why the Subnet cannot accept the request.
    throw error;
  } else {
    throw error;
  }
}

import { WorkloadTerminalError } from "@idyl-labs/sdk";

try {
  const job = await idyl.jobs.createAndWait({
    name: "migrate",
    container: { image: "<image>" },
  });
  await job.waitUntilComplete();
} catch (error) {
  if (error instanceof WorkloadTerminalError) {
    // error.kind, error.workloadName, error.condition, and error.detail
    // say which wait can no longer be satisfied and why.
  }
  throw error;
}

const page = await idyl.pods.list(
  { limit: 20 },
  { signal: AbortSignal.timeout(10_000) },
);

import {
  StrictDecodeError,
  decodeSubmission,
  validateSandbox,
} from "@idyl-labs/sdk";

try {
  const sandbox = decodeSubmission(manifestJson, "Sandbox");
  validateSandbox(sandbox);
  await idyl.sandboxes.createManifest(sandbox);
} catch (error) {
  if (error instanceof StrictDecodeError) {
    // error.reason and error.path name the field that was refused,
    // such as "unknown_field" at "spec.template.spec.hostPath".
  }
  throw error;
}