Deploy jobs - Documentation

This guide assumes you have developed a job locally. The Blaxel SDK allows you to connect to and orchestrate other resources (such as model APIs, tool servers, multi-agents) during development, and ensures telemetry, secure connections to third-party systems or private networks, smart global placement of workflows, and much more when jobs are deployed.

Learn more about authentication on Blaxel

The Blaxel SDK requires two environment variables to authenticate:

Variable	Description
`BL_WORKSPACE`	Your Blaxel workspace name
`BL_API_KEY`	Your Blaxel API key

You can create an API key from the Blaxel console. Your workspace name is visible in the URL when you log in to the console (e.g. app.blaxel.ai/{workspace}).Set them as environment variables or add them to a .env file at the root of your project:

export BL_WORKSPACE=my-workspace
export BL_API_KEY=my-api-key

When developing locally, you can also log in to your workspace with Blaxel CLI (as shown above). This allows you to run Blaxel SDK functions that will automatically connect to your workspace without additional setup. When you deploy on Blaxel, authentication is handled automatically — no environment variables needed.

Deploy on production

You can deploy the job in order to make the entrypoint function (by default: index.ts / server.py) callable on a global endpoint. When deploying to Blaxel, you get a dedicated endpoint that enforces your deployment policies. Run the following command to build and deploy a local job on Blaxel:

bl deploy

You can alternatively use bl push to build and push the job container image to the Blaxel registry. bl push only publishes the image; it does not create a new sandbox deployment, update existing deployments, or restart running processes. This is useful for preparing images in advance.

Run a job

Each deployed job has an HTTP endpoint to trigger a batch execution. You can find this endpoint in the Blaxel console, on the detail page for your deployed job.

HTTP endpoints are only available for deployed jobs.

You can invoke a job in multiple ways:

using the Blaxel SDK, API, or language-native HTTP client (only for deployed jobs);
using the Blaxel CLI;
scheduling it to run periodically via a cron.

SDK

Start batch job execution using the SDK:

import { blJob } from "@blaxel/core";

const JOB_NAME = "YOUR_JOB_NAME"; // ex : my-job (not the display name)

async function execJob() {
  const job = blJob(JOB_NAME);
  let result = await job.run([{"name": "John"}, {"name": "Jane"}])
  console.log(result);
}

execJob().catch(console.error);

from blaxel.core.jobs import bl_job
import asyncio

async def exec_job():
    try:
      job = bl_job("YOUR_JOB_NAME");
      result = await job.arun([{"name": "John"}, {"name": "Jane"}])
      print(result)
    except Exception as e:
        print(f"Failed to execute job: {e}")

asyncio.run(exec_job())

from blaxel.core.jobs import bl_job

def exec_job():
    try:
      job = bl_job("YOUR-JOB-NAME");
      result = job.run([{"name": "John"}, {"name": "Jane"}])
      print(result)
    except Exception as e:
        print(f"Failed to execute job: {e}")

exec_job()

API

Start batch job execution by calling the inference API for your deployed batch job. Here is an example using curl:

Execute a job

curl -X POST "https://api.blaxel.ai/$(bl workspace --current)/jobs/{your-job-name}/executions" \
  -H "Content-Type: application/json" \
  -H "X-Blaxel-Workspace: $(bl workspace --current)" \
  -H "X-Blaxel-Authorization: Bearer $(bl token)" \
  -d '{"tasks":[{"name":"John"},{"name":"Jane"}]}'

Here is an example using a language-native HTTP client:

async function execJob() {
  console.log("Executing job");
  const WORKSPACE = "YOUR_WORKSPACE_NAME"; // ex : my-workspace (not the display name)
  const JOB_NAME = "YOUR_JOB_NAME"; // ex : my-job (not the display name)
  const response = await fetch(`https://api.blaxel.ai/${WORKSPACE}/jobs/${JOB_NAME}/executions`, {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      'X-Blaxel-Authorization': `Bearer ${process.env.BL_API_KEY}`,
      'X-Blaxel-Workspace': WORKSPACE
    },
    body: JSON.stringify({
      tasks: [
        { "name": "John" },
        { "name": "Jane" }
      ]
    })
  });
  if(response.status !== 200) {
    console.error(`Failed to execute job : ${response.statusText}`);
    return;
  }
  const result = await response.json();
  console.log(result);
}

execJob().catch(console.error);

import os
import aiohttp
import asyncio

async def exec_job():
    workspace = "YOUR_WORKSPACE_NAME" # ex : my-workspace (not the display name)
    job_name = "YOUR_JOB_NAME" #  ex : my-job (not the display name)
    api_key = os.environ.get("BL_API_KEY")
    try:
        async with aiohttp.ClientSession() as session:
            print("Executing job")
            resp = await session.post(
                f"https://api.blaxel.ai/{workspace}/jobs/{job_name}/executions",
                json={
                    "tasks": [
                        { "name": "John" },
                        { "name": "Jane" }
                    ]
                },
                headers={
                    "Content-Type": "application/json",
                    "X-Blaxel-Authorization": f"Bearer {api_key}",
                    "X-Blaxel-Workspace": workspace
                }
            )
            data = await resp.text()
            print(data)
    except Exception as e:
        print(f"Failed to execute job: {e}")

asyncio.run(exec_job())

CLI

For deployed jobs, you can start a batch job execution by running:

# Run a deployed job using Blaxel CLI with --data argument
bl run job <<JOB-NAME>> --data '{"tasks": [{"name": "John"}, {"name": "Jane"}]}'

# Run a deployed job using Blaxel CLI with --file argument
bl run job <<JOB-NAME>> --file batches/sample-batch.json

When running a job locally, only JSON file input is currently supported, and you must include the --local argument:

# Run a job locally using Blaxel CLI with --local and --file argument
bl run job <<JOB-NAME>> --local --file batches/sample-batch.json

You can cancel a job execution from the Blaxel Console or via API.

Cron schedule

Set a job on a cron schedule by adding the following to the blaxel.toml configuration file (read full reference on blaxel.toml down below):

[[triggers]]
id = "cron-trigger"
type = "cron"

[triggers.configuration]
schedule = "0 * * * *"

Retries

You can set a maximum number of retries per task in the job definition. Check out the reference for blaxel.toml configuration file down below.

Metrics

The Blaxel Console > Dashboard displays detailed job metrics, including the number of active jobs, failures, and requests (both count and requests per second (RPS)) across all deployments.

List jobs

To retrieve all jobs in your workspace, use the Management API list endpoint with pagination.

Pagination is recommended for list operations because retrieving all available resources in a single request is slow and resource-intensive, and therefore does not scale well.

Request the first page:

curl 'https://api.blaxel.ai/v0/jobs?limit=50' \
  -H 'X-Blaxel-Authorization: Bearer YOUR-API-KEY' \
  -H 'Blaxel-Version: 2026-04-28'

The response includes a data array and a meta object:

{
  "data": [ ... ],
  "meta": {
    "hasMore": true,
    "nextCursor": "...",
    "total": 47
  }
}

Pass meta.nextCursor as cursor on the next request and repeat until meta.hasMore is false:

curl 'https://api.blaxel.ai/v0/jobs?limit=50&cursor=NEXT_CURSOR' \
  -H 'X-Blaxel-Authorization: Bearer YOUR-API-KEY' \
  -H 'Blaxel-Version: 2026-04-28'

For accounts with multiple workspaces, specify the workspace as an additional request parameter, such as ?workspace=WORKSPACE_NAME&..., or via an additional X-Blaxel-Workspace: WORKSPACE_NAME header in the request.

For more information, refer to the API reference documentation.

Deploy with a Dockerfile

While Blaxel uses predefined, optimized container images to build and deploy your code, you can also deploy your workload using your own Dockerfile.

Deploy using Dockerfile

Deploy resources using a custom Dockerfile.

Deploy multiple jobs at once

Using a custom Dockerfile allows for deploying multiple jobs from the same repository with shared dependencies.

Deploy multiple resources with shared files

Deploy multiple jobs with shared context from a single repository.

Deploy multiple jobs from a single image

Reuse a job image across multiple job definitions.

Template directory reference

Overview

package.json            # Mandatory. This file is the standard package.json file, it defines the entrypoint of the project and dependencies.
blaxel.toml             # This file lists configurations dedicated to Blaxel to customize the deployment.
tsconfig.json           # This file is the standard tsconfig.json file, only needed if you use TypeScript.
src/
└── index.ts            # This file is the standard entrypoint of the project. It is where the core logic of the job is implemented.
└── steps               # This is an example of organization for your sub steps, feel free to change it.

package.json

Here the most notable imports are the scripts. They are used for the bl serve and bl deploy commands.

{
  "name": "job-ts",
  "version": "1.0.0",
  "description": "Job using Blaxel Platform",
  "main": "src/index.ts",
  "keywords": [],
  "license": "MIT",
  "author": "Blaxel",
  "scripts": {
    "start": "tsx src/index.ts",
    "prod": "node dist/index.js",
    "build": "tsc"
  },
  "dependencies": {
    "@blaxel/core": "0.2.5",
    "@blaxel/telemetry": "0.2.5"
  },
  "devDependencies": {
    "@types/express": "^5.0.1",
    "@types/node": "^22.13.11",
    "tsx": "^4.19.3",
    "typescript": "^5.8.2"
  }
}

Depending on what you do, all of the scripts are not required. With TypeScript, all 4 of them are used.

start : start the job locally through the TypeScript command, to avoid having to build the project when developing.
prod : start the job remotely from the dist folder, the project needs to have been built before.
build : build the project. It is done automatically when deploying.

The remaining fields in package.json follow standard JavaScript/TypeScript project conventions. Feel free to add any dependencies you need, but keep in mind that devDependencies are only used during the build process and are removed afterwards.

blaxel.toml

The deployment can be configured via the blaxel.toml file in your agent directory. This file is not mandatory; if the file is not found or a required option is not set, you will be prompted for the information during deployment.

type = "job"
name = "my-job"
workspace = "my-workspace"

policies = ["na"]

[env]
DEFAULT_CITY = "San Francisco"

[runtime]
memory = 1024
maxConcurrentTasks = 10
timeout = 900
maxRetries=0

[[triggers]]
id = "cron-trigger"
type = "cron"

[triggers.configuration]
schedule = "0 * * * *"
tasks = [
  { p_id = "1234", arg2 = "foo" },
  { p_id = "5678", arg2 = "bar" }
]

name, workspace, and type fields are optional and serve as default values. Any bl command run in the folder will use these defaults rather than prompting you for input.
policies field is also optional. It allows you to specify a Blaxel policy to customize the deployment. For example, deploy it only in a specific region of the world.
[env] section defines environment variables that the job can access via the SDK. Note that these are NOT secrets.
[runtime] section lets you override job execution parameters: maximum number of concurrent tasks, maximum number of retries for each task, timeout (in s), or memory (in MB) to allocate.
[tasks] sections let you specify
[[triggers]] and [triggers.configuration] sections define ways to schedule job executions.
- type = "cron" lets you create a cron schedule for the job to run periodically. The job will be executed without any argument by default. You can override this by passing:
  - tasks = [{my_arg="my_value"}] containing a list of task to execute at each occurrence of the cron (default value is one task, without arguments)

A private HTTP endpoint to launch job executions is always available by default, even if you don’t define a trigger in this file. You can launch a job execution by sending a POST request with the correct job and workspace arguments to https://api.blaxel.ai/v0/jobs/my-job/executions?workspace=my-workspace.

Ephemeral volumes

Ephemeral volumes are temporary disk-backed storage attached to a job at startup and automatically destroyed when the job completes. Ephemeral volumes have separate quotas from persistent volumes. Limits depend on your plan.

Ephemeral volumes are only available for jobs. Sandboxes and agents should use persistent volumes instead.

​Deploy on production

​Run a job

​SDK

​API

​CLI

​Cron schedule

​Retries

​Metrics

​List jobs

​Deploy with a Dockerfile

Deploy using Dockerfile

​Deploy multiple jobs at once

Deploy multiple resources with shared files

Deploy multiple jobs from a single image

​Template directory reference

​Overview

​package.json

​blaxel.toml

​Ephemeral volumes

Deploy on production

Run a job

SDK

API

CLI

Cron schedule

Retries

Metrics

List jobs

Deploy with a Dockerfile

Deploy multiple jobs at once

Template directory reference

Overview

package.json

blaxel.toml

Ephemeral volumes