@blaxel/core 0.2.61 → 0.2.62-preview.65

package/README.md

@@ -1,116 +1,372 @@
-# Blaxel Typescript SDK
+# Blaxel TypeScript SDK
 
-<p align="center">
-  <img src="https://blaxel.ai/logo-bg.png" alt="Blaxel"/>
-</p>
+[Blaxel](https://blaxel.ai) is a perpetual sandbox platform that achieves near instant latency by keeping infinite secure sandboxes on automatic standby, while co-hosting your agent logic to cut network overhead.
 
-**Blaxel is a computing platform for AI agent builders, with all the services and infrastructure to build and deploy agents efficiently.** This repository contains the TypeScript SDK to create and manage resources on Blaxel.
+This repository contains Blaxel's TypeScript SDK, which lets you create and manage sandboxes and other resources on Blaxel.
 
-## Table of Contents
+## Installation
 
-- [Installation](#installation)
-  - [Optional libraries](#optional-libraries)
-  - [Authentication](#authentication)
-- [Features](#features)
-- [Quickstart](#quickstart)
-- [Contributing](#contributing)
-- [License](#license)
+```bash
+# npm
+npm install @blaxel/core
 
+# yarn
+yarn add @blaxel/core
 
+# bun
+bun add @blaxel/core
+```
 
-## Installation
+## Authentication
+
+The SDK authenticates with your Blaxel workspace using these sources (in priority order):
 
-Install Blaxel core SDK, which lets you manage Blaxel resources.
+1. Blaxel CLI, when logged in
+2. Environment variables in `.env` file (`BL_WORKSPACE`, `BL_API_KEY`)
+3. System environment variables
+4. Blaxel configuration file (`~/.blaxel/config.yaml`)
+
+When developing locally, the recommended method is to just log in to your workspace with the Blaxel CLI:
 
 ```bash
-## npm
-npm install @blaxel/core
+bl login YOUR-WORKSPACE
+```
 
-## pnpm
-pnpm i @blaxel/core
+This allows you to run Blaxel SDK functions that will automatically connect to your workspace without additional setup. When you deploy on Blaxel, this connection persists automatically.
 
-## yarn
-yarn add @blaxel/core
+When running Blaxel SDK from a remote server that is not Blaxel-hosted, we recommend using environment variables as described in the third option above.
+
+## Usage
+
+### Sandboxes
+
+Sandboxes are secure, instant-launching compute environments that scale to zero after inactivity and resume in under 25ms.
+
+```typescript
+import { SandboxInstance } from "@blaxel/core";
+
+// Create a new sandbox
+const sandbox = await SandboxInstance.createIfNotExists({
+  name: "my-sandbox",
+  image: "blaxel/base-image:latest",
+  memory: 4096,
+  region: "us-pdx-1",
+  ports: [{ target: 3000, protocol: "HTTP" }],
+  labels: { env: "dev", project: "my-project" },
+  ttl: "24h"
+});
+
+// Get existing sandbox
+const existing = await SandboxInstance.get("my-sandbox");
+
+// Delete sandbox (using class)
+await SandboxInstance.delete("my-sandbox");
+
+// Delete sandbox (using instance)
+await existing.delete();
 ```
 
+#### Preview URLs
 
-### Optional libraries
-Blaxel SDK is split between multiple packages. *core* is the minimal package to connect to Blaxel. You can find other packages to help you integrate with your favorite AI framework, or set up telemetry.
+Generate public preview URLs to access services running in your sandbox:
 
-- [@blaxel/telemetry](@blaxel/telemetry/README.md)
-- [@blaxel/vercel](@blaxel/vercel/README.md)
-- [@blaxel/llamaindex](@blaxel/llamaindex/README.md)
-- [@blaxel/langgraph](@blaxel/langgraph/README.md)
-- [@blaxel/mastra](@blaxel/mastra/README.md)
+```typescript
+import { SandboxInstance } from "@blaxel/core";
 
-Instrumentation happens automatically when workloads run on Blaxel. To enable telemetry, simply require the SDK in your project's entry point.
-```ts
-import "@blaxel/telemetry";
+// Get existing sandbox
+const sandbox = await SandboxInstance.get("my-sandbox");
+
+// Start a web server in the sandbox
+await sandbox.process.exec({
+  command: "npm run dev -- --port 3000",
+  workingDir: "/app",
+  waitForPorts: [3000]
+});
+
+// Create a public preview URL
+const preview = await sandbox.previews.createIfNotExists({
+  metadata: { name: "app-preview" },
+  spec: {
+    port: 3000,
+    public: true
+  }
+});
+
+console.log(preview.spec?.url); // https://xyz.preview.bl.run
+```
+
+Previews can also be private, with or without a custom prefix. When you create a private preview URL, a [token](https://docs.blaxel.ai/Sandboxes/Preview-url#private-preview-urls) is required to access the URL, passed as a request parameter or request header.
+
+```typescript
+// ...
+
+// Create a private preview URL
+const privatePreview = await sandbox.previews.createIfNotExists({
+  metadata: { name: "private-app-preview" },
+  spec: {
+    port: 3000,
+    public: false
+  }
+});
+
+// Create a public preview URL with a custom prefix
+const customPreview = await sandbox.previews.createIfNotExists({
+  metadata: { name: "custom-app-preview" },
+  spec: {
+    port: 3000,
+    prefixUrl: "my-app",
+    public: true
+  }
+});
 ```
 
+#### Process execution
 
-### Authentication
+Execute and manage processes in your sandbox:
 
-The Blaxel SDK authenticates with your workspace using credentials from these sources, in priority order:
-1. When running on Blaxel, authentication is handled automatically
-2. Variables in your .env file (`BL_WORKSPACE` and `BL_API_KEY`, or see [this page](https://docs.blaxel.ai/Agents/Variables-and-secrets) for other authentication options).
-3. Environment variables from your machine
-4. Configuration file created locally when you log in through Blaxel CLI (or deploy on Blaxel)
+```typescript
+import { SandboxInstance } from "@blaxel/core";
 
-When developing locally, the recommended method is to just log in to your workspace with Blaxel CLI. This allows you to run Blaxel SDK functions that will automatically connect to your workspace without additional setup. When you deploy on Blaxel, this connection persists automatically.
+// Get existing sandbox
+const sandbox = await SandboxInstance.get("my-sandbox");
 
-When running Blaxel SDK from a remote server that is not Blaxel-hosted, we recommend using environment variables as described in the third option above.
+// Execute a command
+const process = await sandbox.process.exec({
+  name: "build-process",
+  command: "npm run build",
+  workingDir: "/app",
+  waitForCompletion: true,
+  timeout: 60000 // 60 seconds
+});
 
+// Kill a running process
+await sandbox.process.kill("build-process");
+```
 
+Restart a process if it fails, up to a maximum number of restart attempts:
 
-## Features
-- Agents & MCP servers
-  - [Create MCP servers](https://docs.blaxel.ai/Functions/Create-MCP-server)
-  - [Connect to MCP servers and model APIs hosted on Blaxel](https://docs.blaxel.ai/Agents/Develop-an-agent-ts)
-  - [Call agents from another agent](https://docs.blaxel.ai/Agents/Develop-an-agent-ts#connect-to-another-agent-multi-agent-chaining)
-  - [Deploy on Blaxel](https://docs.blaxel.ai/Agents/Deploy-an-agent)
-- Sandboxes
-  - [Create and update sandboxes and sandbox previews](https://docs.blaxel.ai/Sandboxes/Overview)
-  - [Run filesystem operations and processes on a sandbox](https://docs.blaxel.ai/Sandboxes/Processes)
-- [Use environment variables or secrets](https://docs.blaxel.ai/Agents/Variables-and-secrets)
+```typescript
+// ...
 
+// Run with auto-restart on failure
+process = await sandbox.process.exec({
+  name: "web-server",
+  command: "npm run dev -- --host 0.0.0.0 --port 3000",
+  restartOnFailure: true,
+  maxRestarts: 5
+});
+```
 
+#### Filesystem operations
+
+Manage files and directories within your sandbox:
+
+```typescript
+import { SandboxInstance } from "@blaxel/core";
+import * as fs from "fs";
+
+// Get existing sandbox
+const sandbox = await SandboxInstance.get("my-sandbox");
+
+// Write and read text files
+await sandbox.fs.write("/app/config.json", '{"key": "value"}');
+const content = await sandbox.fs.read("/app/config.json");
+
+// Write and read binary files
+const binaryData = fs.readFileSync("./image.png");
+await sandbox.fs.writeBinary("/app/image.png", binaryData);
+const blob = await sandbox.fs.readBinary("/app/image.png");
+
+// Create directories
+await sandbox.fs.mkdir("/app/uploads");
+
+// List files
+const { subdirectories, files } = await sandbox.fs.ls("/app");
+
+// Search for text within files
+const matches = await sandbox.fs.grep("pattern", "/app", {
+  caseSensitive: true,
+  contextLines: 2,
+  maxResults: 5,
+  filePattern: "*.ts",
+  excludeDirs: ["node_modules"]
+});
+
+// Find files and directories matching specified patterns:
+const results = await sandbox.fs.find("/app", {
+  type: "file",
+  patterns: ["*.md", "*.html"],
+  maxResults: 1000
+});
+
+// Watch for file changes
+const handle = sandbox.fs.watch("/app", (event) => {
+  console.log(event.op, event.path);
+}, {
+  withContent: true,
+  ignore: ["node_modules", ".git"]
+});
+
+// Close watcher
+handle.close();
+```
 
-## Quickstart
+#### Volumes
 
-Blaxel CLI gives you a quick way to create new applications: agents, MCP servers, jobs, etc - and deploy them to Blaxel.
+Persist data by attaching and using volumes:
 
-**Prerequisites**:
-- **Node.js:** v18 or later.
-- **Blaxel CLI:** Make sure you have Blaxel CLI installed. If not, [install it](https://docs.blaxel.ai/cli-reference/introduction):
-  ```bash
-  curl -fsSL \
-  https://raw.githubusercontent.com/blaxel-ai/toolkit/main/install.sh \
-  | BINDIR=/usr/local/bin sudo -E sh
-  ```
-- **Blaxel login:** Login to Blaxel:
-  ```bash
-    bl login YOUR-WORKSPACE
-  ```
+```typescript
+import { VolumeInstance, SandboxInstance } from "@blaxel/core";
 
-```bash
-bl create-agent-app myfolder
-cd myfolder
-bl deploy
+// Create a volume
+const volume = await VolumeInstance.createIfNotExists({
+  name: "my-volume",
+  size: 1024, // MB
+  region: "us-pdx-1",
+  labels: {  env: "test", project: "12345"  }
+});
+
+// Attach volume to sandbox
+const sandbox = await SandboxInstance.createIfNotExists({
+  name: "my-sandbox",
+  image: "blaxel/base-image:latest",
+  volumes: [
+    { name: "my-volume", mountPath: "/data", readOnly: false }
+  ]
+});
+
+// List volumes
+const volumes = await VolumeInstance.list();
+
+// Delete volume (using class)
+await VolumeInstance.delete("my-volume");
+
+// Delete volume (using instance)
+await volume.delete();
 ```
 
-Also available:
--  `bl create-mcp-server`
--  `bl create-job`
+### Batch jobs
 
+Blaxel lets you support agentic workflows by offloading asynchronous batch processing tasks to its scalable infrastructure, where they can run in parallel. Jobs can run multiple times within a single execution and accept optional input parameters.
 
+```typescript
+import { blJob } from "@blaxel/core";
 
-## Contributing
+// Create and run a job execution
+const job = blJob("job-name");
 
-Contributions are welcome! Please feel free to submit a Pull Request.
+const executionId = await job.createExecution({
+  tasks: [
+    { name: "John" },
+    { name: "Jane" },
+    { name: "Bob" }
+  ]
+});
 
+// Get execution status
+// Returns: "pending" | "running" | "completed" | "failed"
+const status = await job.getExecutionStatus(executionId);
+
+// Get execution details
+const execution = await job.getExecution(executionId);
+console.log(execution.status, execution.metadata);
+
+// Wait for completion
+try {
+  const result = await job.waitForExecution(executionId, {
+    maxWait: 300000,  // 5 minutes (milliseconds)
+    interval: 2000,   // Poll every 2 seconds (milliseconds)
+  });
+  console.log(`Completed: ${result.status}`);
+} catch (error) {
+  console.log(`Timeout: ${error.message}`);
+}
+
+// List all executions
+const executions = await job.listExecutions();
+
+// Delete an execution
+await job.deleteExecution(executionId);
+```
+
+### Framework integrations
+
+Blaxel provides additional packages for framework-specific integrations and telemetry:
+
+- [`@blaxel/telemetry`](./@blaxel/telemetry/README.md) - OpenTelemetry instrumentation
+- [`@blaxel/vercel`](./@blaxel/vercel/README.md) - Vercel AI SDK integration
+- [`@blaxel/llamaindex`](./@blaxel/llamaindex/README.md) - LlamaIndex integration
+- [`@blaxel/langgraph`](./@blaxel/langgraph/README.md) - LangGraph integration
+- [`@blaxel/mastra`](./@blaxel/mastra/README.md) - Mastra integration
+
+#### Model use
+
+Blaxel acts as a unified gateway for model APIs, centralizing access credentials, tracing and telemetry. You can integrate with any model API provider, or deploy your own custom model. When a model is deployed on Blaxel, a global API endpoint is also created to call it.
+
+The SDK includes a helper function that creates a reference to a model deployed on Blaxel and returns a framework-specific model client that routes API calls through Blaxel's unified gateway.
+
+```typescript
+import { blModel } from "@blaxel/core";
+
+// With Vercel AI SDK
+import { blModel } from "@blaxel/vercel";
+const model = await blModel("gpt-4o-mini");
+
+// With LangChain
+import { blModel } from "@blaxel/langgraph";
+const model = await blModel("claude-3-5-sonnet");
+
+// With LlamaIndex
+import { blModel } from "@blaxel/llamaindex";
+const model = await blModel("gpt-4o");
+
+// With Mastra
+import { blModel } from "@blaxel/mastra";
+const model = await blModel("gpt-4o-mini");
+```
+
+#### MCP tool use
+
+Blaxel lets you deploy and host Model Context Protocol (MCP) servers, accessible at a global endpoint over streamable HTTP.
+
+The SDK includes a helper function that retrieves and returns tool definitions from a Blaxel-hosted MCP server in the format required by specific frameworks.
+
+```typescript
+// With Vercel AI SDK
+import { blTools } from "@blaxel/vercel";
+const tools = await blTools(['blaxel-search'])
+
+// With Mastra
+import { blTools } from "@blaxel/mastra";
+const tools = await blTools(['blaxel-search'])
+
+// With LlamaIndex
+import { blTools } from "@blaxel/llamaindex";
+const tools = await blTools(['blaxel-search'])
+
+// With LangChain
+import { blTools } from "@blaxel/langgraph";
+const tools = await blTools(['blaxel-search'])
+```
+
+### Telemetry
+
+Instrumentation happens automatically when workloads run on Blaxel.
+
+Enable automatic telemetry by importing the `@blaxel/telemetry` package:
+
+```typescript
+import "@blaxel/telemetry";
+```
+
+## Requirements
+
+- Node.js v18 or later
+
+## Contributing
 
+Contributions are welcome! Please feel free to [submit a pull request](https://github.com/blaxel-ai/sdk-typescript/pulls).
 
 ## License
 
-This project is licensed under the MIT License - see the LICENSE file for details.
+This project is licensed under the MIT License. See the [LICENSE](LICENSE) file for details.

package/dist/cjs/common/settings.js

@@ -9,8 +9,8 @@ const index_js_1 = require("../authentication/index.js");
 const env_js_1 = require("../common/env.js");
 const node_js_1 = require("../common/node.js");
 // Build info - these placeholders are replaced at build time by build:replace-imports
-const BUILD_VERSION = "0.2.61";
-const BUILD_COMMIT = "8c2f991632d65ec7b5b36da932c4e60ab2476662";
+const BUILD_VERSION = "0.2.62-preview.65";
+const BUILD_COMMIT = "2658def5b7af94a41f1c1c03f3776f2c20ed5187";
 const BUILD_SENTRY_DSN = "https://fd5e60e1c9820e1eef5ccebb84a07127@o4508714045276160.ingest.us.sentry.io/4510465864564736";
 // Cache for config.yaml tracking value
 let configTrackingValue = null;

package/dist/cjs-browser/common/settings.js

@@ -9,8 +9,8 @@ const index_js_1 = require("../authentication/index.js");
 const env_js_1 = require("../common/env.js");
 const node_js_1 = require("../common/node.js");
 // Build info - these placeholders are replaced at build time by build:replace-imports
-const BUILD_VERSION = "0.2.61";
-const BUILD_COMMIT = "8c2f991632d65ec7b5b36da932c4e60ab2476662";
+const BUILD_VERSION = "0.2.62-preview.65";
+const BUILD_COMMIT = "2658def5b7af94a41f1c1c03f3776f2c20ed5187";
 const BUILD_SENTRY_DSN = "https://fd5e60e1c9820e1eef5ccebb84a07127@o4508714045276160.ingest.us.sentry.io/4510465864564736";
 // Cache for config.yaml tracking value
 let configTrackingValue = null;

package/dist/esm/common/settings.js

@@ -3,8 +3,8 @@ import { authentication } from "../authentication/index.js";
 import { env } from "../common/env.js";
 import { fs, os, path } from "../common/node.js";
 // Build info - these placeholders are replaced at build time by build:replace-imports
-const BUILD_VERSION = "0.2.61";
-const BUILD_COMMIT = "8c2f991632d65ec7b5b36da932c4e60ab2476662";
+const BUILD_VERSION = "0.2.62-preview.65";
+const BUILD_COMMIT = "2658def5b7af94a41f1c1c03f3776f2c20ed5187";
 const BUILD_SENTRY_DSN = "https://fd5e60e1c9820e1eef5ccebb84a07127@o4508714045276160.ingest.us.sentry.io/4510465864564736";
 // Cache for config.yaml tracking value
 let configTrackingValue = null;

package/dist/esm-browser/common/settings.js

@@ -3,8 +3,8 @@ import { authentication } from "../authentication/index.js";
 import { env } from "../common/env.js";
 import { fs, os, path } from "../common/node.js";
 // Build info - these placeholders are replaced at build time by build:replace-imports
-const BUILD_VERSION = "0.2.61";
-const BUILD_COMMIT = "8c2f991632d65ec7b5b36da932c4e60ab2476662";
+const BUILD_VERSION = "0.2.62-preview.65";
+const BUILD_COMMIT = "2658def5b7af94a41f1c1c03f3776f2c20ed5187";
 const BUILD_SENTRY_DSN = "https://fd5e60e1c9820e1eef5ccebb84a07127@o4508714045276160.ingest.us.sentry.io/4510465864564736";
 // Cache for config.yaml tracking value
 let configTrackingValue = null;

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@blaxel/core",
-	"version": "0.2.61",
+	"version": "0.2.62-preview.65",
 	"description": "Blaxel Core SDK for TypeScript",
 	"license": "MIT",
 	"author": "Blaxel, INC (https://blaxel.ai)",