Skip to main content
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.
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 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)
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.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.

​
Serve locally

You can serve the job locally in order to make the entrypoint function (by default: index.py / index.ts) available on a local endpoint. Run the following command to serve the job: 
bl serve
Calling the provided endpoint will execute the job locally. Add the flag --hotreload to get live changes. 
bl serve --hotreload

​
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

​
Run a job

You can run a job via API or using Blaxel CLI, or schedule it to run periodically via a cron. API Start a batch job execution by calling the inference API for your batch job.
Execute a job

curl -X POST "https://run.blaxel.ai/{your-workspace}/jobs/{your-job-name}/executions" \
-H "X-Blaxel-Authorization: Bearer <YOUR_API_KEY>" \
'{"tasks":[{"my_arg":"my_value"}]}’


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://run.blaxel.ai/${WORKSPACE}/jobs/${JOB_NAME}/executions`, {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      'X-Blaxel-Authorization': `Bearer ${process.env.BL_API_KEY}`, // You can go to ApiKey from UI to generate one
      '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);
CLI Start a batch job execution by running: 
# Run a job using Blaxel CLI with --data argument
bl run job <<JOB-NAME>> --data '{"tasks": [{"name": "John"}, {"name": "Jane"}]}'
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.

​
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.

​
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 of 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 be 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

This file is used to configure the deployment of the job on Blaxel. The only mandatory parameter is the type so Blaxel knows which kind of entity to deploy. Others are not mandatory but allow you to customize the 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 = "trigger-my-job"
  type = "http"
[triggers.configuration]
  path = "jobs/my-job/execute"
  retry = 1

[[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 fields is also optional. It allow 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 allows to 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 allows to specify
  • [[triggers]] and [triggers.configuration] sections defines ways to schedule job executions.
    • type = "http" lets you create an HTTP endpoint to execute the job
    • 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 occurence of the cron (default value is one task, without arguments) A private HTTP endpoint is always created by default, even if you don’t define any trigger here.
⌘I