> ## Documentation Index
> Fetch the complete documentation index at: https://docs.blaxel.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Quickstart: run an agent on Blaxel

> Deploy and run your existing code as a serverless auto-scalable API.

Blaxel Agents Hosting lets you bring your agent code **and deploys it as a serverless auto-scalable endpoint** — no matter your development framework.

Follow these steps to get your AI agent up and running on Blaxel.

## 1. Create configuration files

At the root of your project repository, create a `blaxel.toml` file for configuration, and a `.env` file for your sensitive [environment variables](/Agents/Variables-and-secrets).

**Example `blaxel.toml`:**

```toml theme={null}
type = "agent"

[runtime]
generation = "mk3"
memory = 4096

[env]
MY_NON_SENSITIVE_ENV = "MY_NON_SENSITIVE_ENV"
```

## 2. Update host and port in your code

Ensure your app listens on the host and port provided by Blaxel. Update your code accordingly:

<CodeGroup>
  ```tsx TypeScript theme={null}
  const host = process.env.HOST || "0.0.0.0";
  const port = parseInt(process.env.PORT || "80");
  ```

  ```python Python theme={null}
  import os

  host = os.getenv("HOST", "0.0.0.0")
  port = int(os.getenv("PORT", "80"))
  ```
</CodeGroup>

## 3. Authenticate via the CLI

[Install the Blaxel CLI](../cli-reference/introduction) and log in to Blaxel using this command:

```bash theme={null}
bl login
```

## 4. Deploy your agent

When deploying, there are two possible scenarios:

### Option A: You already have a `Dockerfile`

Blaxel will automatically use it to build your agent. Just run:

```bash theme={null}
bl deploy
```

### Option B: No `Dockerfile`

Blaxel will detect or read configuration to define an entrypoint when building the agent.

<Tabs>
  <Tab title="TypeScript">
    In TypeScript, entrypoints are managed in the `scripts` in the `package.json` file at the root of the directory.

    * `start` : start the agent locally through the TypeScript command, to avoid having to build the project when developing.
    * `build` : build the project. It is done automatically when deploying.
    * `prod` : start the agent remotely from the dist folder, the project needs to be have been built before.
    * `dev` : same as start, but with hotreload. It's useful when developing locally, each file change is reflected immediately.

    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.

    ```json theme={null}
    {
      "name": "name",
      "version": "1.0.0",
      "description": "<no value>",
      "keywords": [],
      "license": "MIT",
      "author": "cdrappier",
      "scripts": {
        "start": "tsx src/index.ts",
        "prod": "node dist/index.js",
        "dev": "tsx watch src/index.ts",
        "build": "tsc"
      },
      "dependencies": {
        "@ai-sdk/openai": "^1.2.5",
        "@blaxel/sdk": "0.1.1-preview.9",
        "ai": "^4.1.61",
        "fastify": "^5.2.1",
        "zod": "^3.24.2"
      },
      "devDependencies": {
        "@types/express": "^5.0.1",
        "@types/node": "^22.13.11",
        "tsx": "^4.19.3",
        "typescript": "^5.8.2"
      }
    }
    ```
  </Tab>

  <Tab title="Python">
    You can define an optional `[entrypoint]` section to specify how Blaxel will start your agent.

    ```toml theme={null}
    [entrypoint]
    prod = ".venv/bin/python3 src/agent.py"
    dev = "npx nodemon --exec uv run python src/agent.py"
    ```

    If not specified, Blaxel will auto-detect settings and configure your agent.
  </Tab>
</Tabs>

Then run:

```bash theme={null}
bl deploy
```

## 5. (Optional) Enable telemetry

Instrumentation happens automatically when workloads run on Blaxel. To enable telemetry, simply import the SDK in your project's entry point.

<CodeGroup>
  ```tsx TypeScript theme={null}
  import "@blaxel/telemetry";
  ```

  ```python Python theme={null}
  import blaxel.core
  ```
</CodeGroup>

## 6. (Optional) Run locally with Blaxel CLI

If you want to run your agent locally and start using the SDK, make sure the `start` and `dev` scripts are defined, then run:

```bash theme={null}
bl serve
# or
bl serve --hotreload
```

## 7. Test your agent

By default, agents deployed on Blaxel are not public. All agent requests must be authenticated via a [bearer token](../Security/Access-tokens). Requests are made to the agent's [inference endpoint](./Query-agents) via the Blaxel API or Blaxel CLI.

### Blaxel API

Make a POST request to the inference endpoint for your agent deployment:

```bash theme={null}
curl 'https://run.blaxel.ai/YOUR-WORKSPACE/agents/YOUR-AGENT' \
  -H 'Content-Type: application/json' \
  -H 'X-Blaxel-Authorization: Bearer YOUR-TOKEN' \
  -H 'X-Blaxel-Workspace: YOUR-WORKSPACE' \
  -d $'{"inputs":"Enter your input here."}'
```

### Blaxel CLI

Run the following command:

```shell theme={null}
bl run agent YOUR-AGENT --data '{"inputs":"Enter your input here."}'
```

<Tip>
  Althought deployed agents are private by default, it is possible to [make an agent publicly available](./Query-agents#make-an-agent-public).
</Tip>

That’s it! You’re ready to start integrating Blaxel features using the Blaxel SDK.

## Resources

Want the complete guide on developing and deploying agents on Blaxel? Check out the following resources:

<Card title="Develop and deploy an agent on Blaxel using Claude Agent SDK" icon="rocket" href="../Tutorials/Claude-Agent-SDK">
  See an example of building and deploying an agent on Blaxel with Claude Agent SDK.
</Card>

<Card title="Give compute to your agent with the TypeScript SDK " icon="square-js" href="/Agents/Develop-an-agent-ts">
  Complete guide for using the TypeScript SDK to develop an agent using Blaxel services.
</Card>

<Card title="Give compute to your agent with the Python SDK " icon="python" href="/Agents/Develop-an-agent-py">
  Complete guide for using the Python SDK to develop an agent using Blaxel services.
</Card>

<Card title="Deploy your agent code to Blaxel" icon="server" href="/Agents/Deploy-an-agent">
  Complete guide for deploying AI agents on Blaxel.
</Card>

<Card title="Manage environment variables" icon="lock" href="/Agents/Variables-and-secrets">
  Complete guide for managing variables and secrets when deploying on Blaxel.
</Card>