Deploy and monitor GPU workloads on the Nosana Network with @nosana/kit

GitHub stars
270

Install

/plugin install nosana@nosana

Run it inside Claude Code after adding the marketplace with /plugin marketplace add nosana-ci/nosana-kit.

Contents

Discovered from source

Skills 1

Nosana

Nosana runs containerized GPU workloads on a decentralized network. You describe the container as a job definition, say which GPU (and any other node requirements) it needs, and create a deployment that schedules it onto matching hosts.

Use deployments, not one-shot jobs. Deployments own the lifecycle: replicas, revisions, restarts, scheduling, streaming, and endpoint URLs. One-shot jobs are a lower-level path — see reference/one-shot-jobs.md.

Setup

npm install @nosana/kit   # Node >= 20.18.0
import { createNosanaClient, NosanaNetwork } from '@nosana/kit';
import type { NosanaClient } from '@nosana/kit'; // the client type is exported — don't re-derive it

const client: NosanaClient = createNosanaClient(NosanaNetwork.MAINNET, {
  api: { apiKey: process.env.NOSANA_API_KEY },
});

Networks: MAINNET (default), DEVNET, LOCALNET. @nosana/kit re-exports @nosana/api, @nosana/types, @nosana/ipfs and the Solana clients — install only @nosana/kit.

Two auth modes — this changes the API surface

ModeSetupPays withDeployments have
API key{ api: { apiKey } }account creditsno vault
Walletclient.wallet = await loadWalletFromFile(), no apiKeySOL/NOS in a vaultdeployment.vault

API keys come from deploy.nosana.com → Account → API Keys, and look like nos_…. Read from the environment, never commit.

With a wallet, cast to get the signer variant:

import type { NosanaApi } from '@nosana/kit';
const api = client.api as NosanaApi; // deployments carry a vault

See reference/funding.md for credits and vaults.

Deploy

const deployment = await client.api.deployments.create({
  name: 'my-service',
  requirements: { name: 'NVIDIA GeForce RTX 4090' }, // a GPU from reservations.listGpus()
  replicas: 1,
  timeout: 60,          // MINUTES (jobs API uses seconds — see Gotchas)
  strategy: 'SIMPLE',
  autostart: true,      // skip the DRAFT state
  job_definition: {
    version: '0.1',
    type: 'container',
    meta: { trigger: 'api' },
    ops: [
      {
        type: 'container/run',
        id: 'server',
        args: { image: 'nginx', expose: 80 },
      },
    ],
  },
});

console.log(deployment.id, deployment.status);

Without autostart, a deployment is created as DRAFT and does nothing until you call await deployment.start().

Pick a GPU

GPU names and the other requirements come from the host-manager's reservation lookups, not from memory:

const { gpus } = await client.api.reservations.listGpus();          // every model, VRAM, free hosts
const options  = await client.api.reservations.getRequirementOptions(); // settable metrics and their values
const free     = await client.api.reservations.findAvailable({        // who meets a set right now, and the price
  requirements: { name: ['NVIDIA GeForce RTX 4090', 'NVIDIA GeForce RTX 5090'], ram_gb: 32 },
});
console.log(gpus.length, options.metrics.length, free.total, free.price?.minUsdPerHour);

With no market, each job goes to the cheapest PREMIUM market with a free host that meets requirements. Pass a market to pin every job to one. See reference/requirements.md.

Create options

FieldNotes
name, replicasRequired
marketSolana address of the market to post every job in — see reference/markets.md. Omit it to post across markets: each job goes to the cheapest PREMIUM market with a node that meets requirements
requirementsNode requirements, e.g. { name: ['NVIDIA GeForce RTX 4090'], ram_gb: 64 }: a number is a minimum, a string or boolean an exact match, a list any of its values — see reference/requirements.md
timeoutMinutes. Schema min is 1, but credit-paid (API key) deployments require ≥ 60 — below that the create succeeds and every job listing fails. INFINITE requires ≥ 60 too
strategySIMPLE, SIMPLE-EXTEND, SCHEDULED (needs schedule cron), INFINITE (optional rotation_time seconds, ≥10 min under timeout)
job_definitionSee reference/job-definition.md
autostartStart immediately instead of DRAFT
confidentialConfidential compute
vault / new_vaultWallet auth: reuse a vault address, or force a fresh one. Default reuses your oldest shared vault

Strategies: SIMPLE runs replicas once. SIMPLE-EXTEND keeps extending them until funds run out. SCHEDULED runs them on a cron. INFINITE maintains replicas continuously, rotating jobs before timeout.

Validate the job definition before spending anything:

import { validateJobDefinition } from '@nosana/kit';

const result = validateJobDefinition(jobDefinitionJson);
if (!result.success) {
  throw new Error(result.errors.map((e) => `${e.path}: expected ${e.expected}`).join('\n'));
}

Lifecycle

await deployment.start();
await deployment.stop();
await deployment.archive();          // hide, keep history
await deployment.delete();           // permanent; must be STOPPED first

await deployment.updateReplicaCount(3);
await deployment.updateTimeout(120); // minutes
await deployment.updateSchedule('0 0 * * *');
await deployment.updateName('new-name');
await deployment.updateRequirements({ name: ['NVIDIA GeForce RTX 5090'], ram_gb: 64 }); // new jobs only; add a market as 2nd arg to pin one
await deployment.updateMarket('MARKET_ADDRESS'); // running jobs are relisted on the new market
await deployment.createRevision(newJobDefinition);
await deployment.updateActiveRevision(2);

// Copy a deployment (same vault, market, strategy, active revision); source is untouched.
// The copy is a full deployment object, so drive it like any other:
const copy = await deployment.duplicate({ name: 'my-copy' });
await copy.start(); // or pass { autostart: true } to skip this

delete() leaves the vault intact and makes the deployment object unusable.

Monitor

The main event. Ordered by usefulness.

1. Endpoint URLs — the API gives them to you

const d = await client.api.deployments.get(id);
for (const { opId, port, url, online } of d.endpoints) {
  console.log(opId, port, url, online); // https://<hash>.node.k8s.prd.nos.ci
}

Do not derive these by hashing, and do not poll the URL to find out whether it is up — online already says so.

The URL is populated at create time, before anything is scheduled, so its presence means nothing. online is the readiness signal: it is true once the node's tunnel is registered, and when the op declares an http health check the tunnel only registers after that check passes — so it means the service answered, not merely that a port opened.

Three states, from one response — active_jobs is on the same deployment:

active_jobsonlineMeans
> 0falsestarting — scheduled, not serving yet
anytrueup — the URL serves
0falsenot running

online is per opId: every port an op exposes shares one tunnel and reports together. See reference/endpoints.md.

2. Stream — live changes over SSE

const sub = deployment.stream({
  onDeployment: (e) => console.log('status', e.status, 'replicas', e.replicas),
  onJob:        (e) => console.log('job', e.job, e.state, 'node', e.node),
  onEvent:      (e) => console.log('[event]', e.event, e.message),
  onTask:       (e) => console.log('task', e.task, e.status),
  onEndpoint:   (e) => console.log('endpoint', e.opId, e.port, 'online=' + e.online),
  onOpen:       () => console.log('resync'),
  onError:      (err) => console.error(err),
});

// later
sub.close();

onEndpoint is how you wait for a service without polling it: every endpoint is stated once when the stream opens, then again whenever its reachability changes.

Four semantics that will bite you if you assume otherwise:

  • onOpen means "resynchronise from here", not "started". EventSource reconnects on its own and the server replays the opening snapshot each time, so onOpen fires again after any drop. Rebuild state on every onOpen; don't append.
  • Errors are reported, never thrown. The stream keeps retrying. Logging and bailing on the first onError loses the signal permanently.
  • Malformed frames are silently dropped, as is anything a handler throws. Don't rely on a handler's exception surfacing.
  • A frame per endpoint, not per change. An op exposing several ports emits one frame per entry, all carrying the same online, because they share a tunnel. Key your state on opId + port.

3. Status — the state machine

StatusMeaning
DRAFTCreated, never started
STARTINGScheduling jobs onto hosts
RUNNINGThe deployment is trying to keep jobs listed — not proof any job runs. Check active_jobs and getEvents()
STOPPING → STOPPEDWinding down / done
ERRORFailed
INSUFFICIENT_FUNDSOut of credits or vault balance — top up, then start
ARCHIVEDHidden from the active list

STARTING → RUNNING is not instant, and RUNNING does not mean the service answers: the host still pulls the image and boots the container. Measured on a bare nginx, that took 21s, 35s, 80s and 216s across four runs of the same job definition — budget minutes, not seconds. Watch endpoints[].online rather than timing it, and declare a health check on the exposed port so the tunnel only registers once the service replies.

But a deployment can also sit in RUNNING forever with zero jobs, endpoint 503-ing, while job listing fails on a loop. Status never changes; the only signal is in the event log. So when an endpoint doesn't come up, check getEvents() before you wait — a JOB_LIST_ERROR there is the real answer.

4. Logs — the answer to "why did it die"

Container output lives on the job, not the deployment:

const { jobs } = await deployment.getJobs();

for (const j of jobs) {
  const job = await deployment.getJob(j.job);
  for (const op of job.jobResult?.opStates ?? []) {
    console.log(op.operationId, 'exit', op.exitCode);
    for (const line of op.logs ?? []) {
      console.log(`[${line.type}]`, line.log); // stdout | stderr | stdin | nodeerr
    }
  }
}

jobResult is null until the job produces results. op.error holds the failure reason, op.results holds values extracted by the job definition's results regexes.

Events, tasks, revisions

const { events }    = await deployment.getEvents();    // audit log: what happened, with tx
const { tasks }     = await deployment.getTasks();     // scheduled LIST/EXTEND/STOP work
const { revisions } = await deployment.getRevisions(); // job definition history

All four listings (getJobs, getEvents, getTasks, getRevisions) are cursor-paginated and return nextPage() / previousPage() — null at the end:

let page = await deployment.getEvents({ limit: 50 });
while (page.nextPage) page = await page.nextPage();

Full frame and status tables: reference/monitoring.md.

Troubleshooting

SymptomLook here
Stuck in STARTINGImage pull / model download. getEvents(), then host logs via getJob(). active_jobs: 0 for long: no free host meets requirements — reservations.findAvailable()
INSUFFICIENT_FUNDSreference/funding.md
Endpoint 404s/503sgetEvents() first — a repeating JOB_LIST_ERROR means nothing was ever scheduled. Otherwise still booting, or expose missing. reference/endpoints.md
RUNNING but active_jobs: 0Job listing is failing. getEvents()
Container exits immediatelygetJob().jobResult.opStates[].exitCode and logs
Create rejectedRun validateJobDefinition — the API's error is terser
state is a number, not a stringSee Gotchas
Retrying a write safelyreference/errors.md

Gotchas

Things that will trip you up. Several of these contradict the published docs; where they do, these were checked against the shipped types and the live API.

  1. timeout units differ. Deployments: minutes. Jobs API and on-chain post: seconds. Nothing warns you; a 60 becomes an hour or a minute.
  2. Job state has three encodings. Blockchain indexer returns 0|1|2|3 (QUEUED|RUNNING|COMPLETED|STOPPED, exported as JobState). The deployment stream returns the string union. deployment.getJob() is typed string | number. Normalise on read.
  3. Two ways in over HTTP. Calling directly, use the gateway at https://api.nosana.com — one host, every route, and a merged OpenAPI spec (see below). The SDK instead calls the four services behind it directly — client-manager (auth, credits, templates, job writes), blockchain-indexer (job reads, stats), deployment-manager (deployments, vaults), host-manager (markets, hosts, GPU and requirement lookups) — because its types are generated per service. Both work; the gateway is the simpler target for anything that isn't the SDK.
  4. Live market fields are usd_reward_per_hour, nos_job_price_per_second, slug, type. There is no vram or price_per_hour_usd despite the docs.
  5. INFINITE is live, not "coming soon".
  6. Curated methods throw; raw clients don't. client.api.* throws on failure. client.api.clients.* returns { data, error }.
  7. Health checks require continuous. Every entry in health_checks needs a continuous boolean; the docs omit it. See reference/endpoints.md.
  8. meta resource hints are advisory. Whether you write system_resources (the declared field) or system_requirements (what the docs and examples use, accepted via an index signature), it only indicates what a workload needs — nothing enforces it. Pick a market whose GPU actually fits.
  9. Credit-paid deployments need timeout ≥ 60 minutes. Anything less is accepted at create, then fails on every job listing with Credit-paid jobs must have a timeout of at least 3600 seconds, while the deployment happily reports RUNNING.

Reference

Load only what the task needs.

FileContents
reference/monitoring.mdStream frames, status transitions, logs, events, tasks, pagination
reference/job-definition.mdFull schema, ops, cmd forms, global defaults, literal interpolation
reference/requirements.mdGPU catalogue, settable requirements, who is free now and the price, changing them on a deployment
reference/markets.mdPinning a market, live field names, current market addresses
reference/endpoints.mdExposing ports, health checks, service URLs, multi-service containers
reference/resources.mdHuggingFace and S3 resources, caching, private registries
reference/funding.mdCredits (API key) and vaults (wallet)
reference/errors.mdError types, idempotency keys, retry policy
reference/one-shot-jobs.mdJobs API, batch operations, and when to prefer it

The HTTP API

Every route across all four services is published as one merged OpenAPI 3.1 spec, so you don't need to know which service owns what:

Spechttps://api.nosana.com/openapi.json
Browsablehttps://api.nosana.com/docs

Read the spec when you need a route this skill doesn't cover, an exact request or response shape, or a query parameter — it is generated from the running services, so it is more current than any prose, including this file. It regenerates on a short interval, so a route added minutes ago may not be in it yet.

From TypeScript, prefer the SDK. Anything without a curated method is still reachable and typed via client.api.clients.{clientManager,hostManager,blockchainIndexer,deploymentManager} — see reference/errors.md for how those differ from curated methods.

Sponsors

Details

Marketplace
nosana-ci/nosana-kit
Source
packages/skills
Author
Nosana
Category
Deployment