Javascript Sdk

JavaScript/TypeScript SDK for inference.sh - run AI apps, build agents, integrate 150+ models. Package: @inferencesh/sdk (npm install). Full TypeScript suppo...

Security Scan

This is documentation for an inference.sh JavaScript/TypeScript SDK and the instructions, examples, and referenced env usage are coherent with that purpose, but the docs include powerful patterns (file access, code execution, delete tools) that you should review before enabling in an autonomous agent or production environment.

Purpose & Capability

The name/description (JavaScript/TypeScript SDK for inference.sh) matches the included SKILL.md and reference files: install and usage examples, agent/tool builder patterns, file upload, streaming, proxy setup, sessions, and React/Next.js integration. Nothing requested (no env vars, no binaries, no installs) is out of scope for a client SDK README.

Instruction Scope

The SKILL.md contains many runnable examples that legitimately show reading files (fs.readFileSync, createReadStream), using environment variables (process.env.INFERENCE_API_KEY), uploading local file paths, and building agents that can call tools or execute code. Those are expected for an SDK, but they do instruct operations that access local files, environment secrets, and potentially execute code (internalTools().codeExecution(true) and a delete_file tool example). If an agent were to run these examples verbatim with broad privileges, that could enable sensitive operations — but the examples themselves are consistent with an SDK that exposes these capabilities.

Install Mechanism

No install spec or downloads are present; it's instruction-only documentation recommending 'npm install @inferencesh/sdk' which is expected. No external or unusual URLs for installing code are used within the skill bundle itself.

Credentials

The skill metadata declares no required env vars; the docs repeatedly show use of an API key (INFERENCE_API_KEY, inf_... placeholders) and recommend using a server proxy to avoid exposing keys in the browser. That is appropriate for an SDK. There are no unrelated credentials requested. Users should however take care to keep API keys server-side and not embed them into client code.

Persistence & Privilege

always is false and the skill is user-invocable; it does not request persistent platform privileges or attempt to modify other skills or system settings. The SDK examples show persistent session management (session IDs) but that is a service-level feature, not a skill-level privilege escalation.

Assessment

This bundle is documentation for a JS/TS SDK and is internally consistent. Before installing or using it: 1) Never hard-code your INFERENCE_API_KEY into frontend code — follow the proxy examples to keep keys on the server. 2) Review any code that reads local files or enables 'code execution' or tools that delete files before running them under an agent, and require explicit human approval for destructive actions. 3) Be cautious if you allow an autonomous agent to use the SDK with file-system access or code-execution internal tools — those features are powerful and could be abused if misconfigured. If you need stronger assurance, ask the publisher for a canonical homepage/repository and a verified npm package link before installing in production.

Build AI applications with the inference.sh JavaScript/TypeScript SDK.

Quick Start

npm install @inferencesh/sdk

import { inference } from '@inferencesh/sdk';

const client = inference({ apiKey: 'inf_your_key' });

// Run an AI app
const result = await client.run({
  app: 'infsh/flux-schnell',
  input: { prompt: 'A sunset over mountains' }
});
console.log(result.output);

Installation

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

Requirements: Node.js 18.0.0+ (or modern browser with fetch)

Authentication

import { inference } from '@inferencesh/sdk';

// Direct API key
const client = inference({ apiKey: 'inf_your_key' });

// From environment variable (recommended)
const client = inference({ apiKey: process.env.INFERENCE_API_KEY });

// For frontend apps (use proxy)
const client = inference({ proxyUrl: '/api/inference/proxy' });

Get your API key: Settings → API Keys → Create API Key

Running Apps

Basic Execution

const result = await client.run({
  app: 'infsh/flux-schnell',
  input: { prompt: 'A cat astronaut' }
});

console.log(result.status);  // "completed"
console.log(result.output);  // Output data

Fire and Forget

const task = await client.run({
  app: 'google/veo-3-1-fast',
  input: { prompt: 'Drone flying over mountains' }
}, { wait: false });

console.log(`Task ID: ${task.id}`);
// Check later with client.getTask(task.id)

Streaming Progress

const stream = await client.run({
  app: 'google/veo-3-1-fast',
  input: { prompt: 'Ocean waves at sunset' }
}, { stream: true });

for await (const update of stream) {
  console.log(`Status: ${update.status}`);
  if (update.logs?.length) {
    console.log(update.logs.at(-1));
  }
}

Run Parameters

Parameter	Type	Description
app	string	App ID (namespace/name@version)
input	object	Input matching app schema
setup	object	Hidden setup configuration
infra	string	'cloud' or 'private'
session	string	Session ID for stateful execution
session_timeout	number	Idle timeout (1-3600 seconds)

File Handling

Automatic Upload

const result = await client.run({
  app: 'image-processor',
  input: {
    image: '/path/to/image.png'  // Auto-uploaded
  }
});

Manual Upload

// Basic upload
const file = await client.uploadFile('/path/to/image.png');

// With options
const file = await client.uploadFile('/path/to/image.png', {
  filename: 'custom_name.png',
  contentType: 'image/png',
  public: true
});

const result = await client.run({
  app: 'image-processor',
  input: { image: file.uri }
});

Browser File Upload

const input = document.querySelector('input[type="file"]');
const file = await client.uploadFile(input.files[0]);

Sessions (Stateful Execution)

Keep workers warm across multiple calls:

// Start new session
const result = await client.run({
  app: 'my-app',
  input: { action: 'init' },
  session: 'new',
  session_timeout: 300  // 5 minutes
});
const sessionId = result.session_id;

// Continue in same session
const result2 = await client.run({
  app: 'my-app',
  input: { action: 'process' },
  session: sessionId
});

Agent SDK

Template Agents

Use pre-built agents from your workspace:

const agent = client.agent('my-team/support-agent@latest');

// Send message
const response = await agent.sendMessage('Hello!');
console.log(response.text);

// Multi-turn conversation
const response2 = await agent.sendMessage('Tell me more');

// Reset conversation
agent.reset();

// Get chat history
const chat = await agent.getChat();

Ad-hoc Agents

Create custom agents programmatically:

import { tool, string, number, appTool } from '@inferencesh/sdk';

// Define tools
const calculator = tool('calculate')
  .describe('Perform a calculation')
  .param('expression', string('Math expression'))
  .build();

const imageGen = appTool('generate_image', 'infsh/flux-schnell@latest')
  .describe('Generate an image')
  .param('prompt', string('Image description'))
  .build();

// Create agent
const agent = client.agent({
  core_app: { ref: 'infsh/claude-sonnet-4@latest' },
  system_prompt: 'You are a helpful assistant.',
  tools: [calculator, imageGen],
  temperature: 0.7,
  max_tokens: 4096
});

const response = await agent.sendMessage('What is 25 * 4?');

Available Core Apps

Model	App Reference
Claude Sonnet 4	infsh/claude-sonnet-4@latest
Claude 3.5 Haiku	infsh/claude-haiku-35@latest
GPT-4o	infsh/gpt-4o@latest
GPT-4o Mini	infsh/gpt-4o-mini@latest

Tool Builder API

Parameter Types

import {
  string, number, integer, boolean,
  enumOf, array, obj, optional
} from '@inferencesh/sdk';

const name = string('User\'s name');
const age = integer('Age in years');
const score = number('Score 0-1');
const active = boolean('Is active');
const priority = enumOf(['low', 'medium', 'high'], 'Priority');
const tags = array(string('Tag'), 'List of tags');
const address = obj({
  street: string('Street'),
  city: string('City'),
  zip: optional(string('ZIP'))
}, 'Address');

Client Tools (Run in Your Code)

const greet = tool('greet')
  .display('Greet User')
  .describe('Greets a user by name')
  .param('name', string('Name to greet'))
  .requireApproval()
  .build();

App Tools (Call AI Apps)

const generate = appTool('generate_image', 'infsh/flux-schnell@latest')
  .describe('Generate an image from text')
  .param('prompt', string('Image description'))
  .setup({ model: 'schnell' })
  .input({ steps: 20 })
  .requireApproval()
  .build();

Agent Tools (Delegate to Sub-agents)

import { agentTool } from '@inferencesh/sdk';

const researcher = agentTool('research', 'my-org/researcher@v1')
  .describe('Research a topic')
  .param('topic', string('Topic to research'))
  .build();

Webhook Tools (Call External APIs)

import { webhookTool } from '@inferencesh/sdk';

const notify = webhookTool('slack', 'https://hooks.slack.com/...')
  .describe('Send Slack notification')
  .secret('SLACK_SECRET')
  .param('channel', string('Channel'))
  .param('message', string('Message'))
  .build();

Internal Tools (Built-in Capabilities)

import { internalTools } from '@inferencesh/sdk';

const config = internalTools()
  .plan()
  .memory()
  .webSearch(true)
  .codeExecution(true)
  .imageGeneration({
    enabled: true,
    appRef: 'infsh/flux@latest'
  })
  .build();

const agent = client.agent({
  core_app: { ref: 'infsh/claude-sonnet-4@latest' },
  internal_tools: config
});

Streaming Agent Responses

const response = await agent.sendMessage('Explain quantum computing', {
  onMessage: (msg) => {
    if (msg.content) {
      process.stdout.write(msg.content);
    }
  },
  onToolCall: async (call) => {
    console.log(`\n[Tool: ${call.name}]`);
    const result = await executeTool(call.name, call.args);
    agent.submitToolResult(call.id, result);
  }
});

File Attachments

// From file path (Node.js)
import { readFileSync } from 'fs';
const response = await agent.sendMessage('What\'s in this image?', {
  files: [readFileSync('image.png')]
});

// From base64
const response = await agent.sendMessage('Analyze this', {
  files: ['data:image/png;base64,iVBORw0KGgo...']
});

// From browser File object
const input = document.querySelector('input[type="file"]');
const response = await agent.sendMessage('Describe this', {
  files: [input.files[0]]
});

Skills (Reusable Context)

const agent = client.agent({
  core_app: { ref: 'infsh/claude-sonnet-4@latest' },
  skills: [
    {
      name: 'code-review',
      description: 'Code review guidelines',
      content: '# Code Review\n\n1. Check security\n2. Check performance...'
    },
    {
      name: 'api-docs',
      description: 'API documentation',
      url: 'https://example.com/skills/api-docs.md'
    }
  ]
});

Server Proxy (Frontend Apps)

For browser apps, proxy through your backend to keep API keys secure:

Client Setup

const client = inference({
  proxyUrl: '/api/inference/proxy'
  // No apiKey needed on frontend
});

Next.js Proxy (App Router)

// app/api/inference/proxy/route.ts
import { createRouteHandler } from '@inferencesh/sdk/proxy/nextjs';

const route = createRouteHandler({
  apiKey: process.env.INFERENCE_API_KEY
});

export const POST = route.POST;

Express Proxy

import express from 'express';
import { createProxyMiddleware } from '@inferencesh/sdk/proxy/express';

const app = express();
app.use('/api/inference/proxy', createProxyMiddleware({
  apiKey: process.env.INFERENCE_API_KEY
}));

Supported Frameworks

• Next.js (App Router & Pages Router)
• Express
• Hono
• Remix
• SvelteKit

TypeScript Support

Full type definitions included:

import type {
  TaskDTO,
  ChatDTO,
  ChatMessageDTO,
  AgentTool,
  TaskStatusCompleted,
  TaskStatusFailed
} from '@inferencesh/sdk';

if (result.status === TaskStatusCompleted) {
  console.log('Done!');
} else if (result.status === TaskStatusFailed) {
  console.log('Failed:', result.error);
}

Error Handling

import { RequirementsNotMetException, InferenceError } from '@inferencesh/sdk';

try {
  const result = await client.run({ app: 'my-app', input: {...} });
} catch (e) {
  if (e instanceof RequirementsNotMetException) {
    console.log('Missing requirements:');
    for (const err of e.errors) {
      console.log(`  - ${err.type}: ${err.key}`);
    }
  } else if (e instanceof InferenceError) {
    console.log('API error:', e.message);
  }
}

Human Approval Workflows

const response = await agent.sendMessage('Delete all temp files', {
  onToolCall: async (call) => {
    if (call.requiresApproval) {
      const approved = await promptUser(`Allow ${call.name}?`);
      if (approved) {
        const result = await executeTool(call.name, call.args);
        agent.submitToolResult(call.id, result);
      } else {
        agent.submitToolResult(call.id, { error: 'Denied by user' });
      }
    }
  }
});

CommonJS Support

const { inference, tool, string } = require('@inferencesh/sdk');

const client = inference({ apiKey: 'inf_...' });
const result = await client.run({...});

Reference Files

• Agent Patterns - Multi-agent, RAG, batch processing patterns
• Tool Builder - Complete tool builder API reference
• Server Proxy - Next.js, Express, Hono, Remix, SvelteKit setup
• Streaming - Real-time progress updates and SSE handling
• File Handling - Upload, download, and manage files
• Sessions - Stateful execution with warm workers
• TypeScript - Type definitions and type-safe patterns
• React Integration - Hooks, components, and patterns

Related Skills

# Python SDK
npx skills add inference-sh/skills@python-sdk

# Full platform skill (all 150+ apps via CLI)
npx skills add inference-sh/skills@inference-sh

# LLM models
npx skills add inference-sh/skills@llm-models

# Image generation
npx skills add inference-sh/skills@ai-image-generation

Documentation

• JavaScript SDK Reference - Full API documentation
• Agent SDK Overview - Building agents
• Tool Builder Reference - Creating tools
• Server Proxy Setup - Frontend integration
• Authentication - API key setup
• Streaming - Real-time updates
• File Uploads - File handling