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

# Get started

> Step-by-step quickstart guide to install the Blaxel CLI, create a cloud sandbox, run processes, manage files, and deploy your first AI agent.

Blaxel is a **perpetual sandbox platform built for AI agents**. Our computing platform lets you keep infinite, secure sandboxes on automatic standby while co-hosting your agents for near instant latency.

<Callout icon="lightbulb" color="#a3e0c5" iconType="solid">
  **Using Cursor, Claude Code, Codex, Goose, or another AI coding agent?**

  Install the [Blaxel Skill](./skills-mcp) to give your agent the ability to deploy AI agents, create sandboxes for code execution, host MCP servers, run batch jobs, and more...all using simple prompts, zero code required!

  ```shell theme={null}
  npx skills add blaxel-ai/agent-skills
  ```
</Callout>

## Quickstart

Welcome there! 👋 Make sure you have created an account on Blaxel (here → [https://app.blaxel.ai](https://app.blaxel.ai)), and created a first [workspace](Security/Workspace-access-control) (you’ll need the workspace ID).

<Steps>
  <Step title="Install Blaxel CLI">
    <AccordionGroup>
      <Accordion title="Install on Mac" icon="apple">
        <Warning>To install Blaxel CLI, you must use [Homebrew](https://brew.sh/): make sure it is installed on your machine. We are currently in the process of supporting additional installers. Check out the cURL method down below for general installation.</Warning>

        Install Blaxel CLI by running the two following commands successively in a terminal:

        ```shell theme={null}

        brew tap blaxel-ai/blaxel

        ```

        ```shell theme={null}

        brew install blaxel

        ```
      </Accordion>

      <Accordion title="Install on Linux" icon="linux">
        Install Blaxel CLI by running the following command in a terminal (non-sudo alternatives below):

        ```shell theme={null}
        curl -fsSL \
        https://raw.githubusercontent.com/blaxel-ai/toolkit/main/install.sh \
        | BINDIR=/usr/local/bin sudo -E sh
        ```

        If you need a non-sudo alternative (**it will ask you questions to configure**):

        ```shell theme={null}
        curl -fsSL \
        https://raw.githubusercontent.com/blaxel-ai/toolkit/main/install.sh \
        | sh
        ```

        If you need to install a specific version (e.g. v0.1.21):

        ```shell theme={null}
        curl -fsSL \
        https://raw.githubusercontent.com/blaxel-ai/toolkit/main/install.sh \
        | VERSION=v0.1.21 sh
        ```
      </Accordion>

      <Accordion title="Install with cURL" icon="code">
        Install Blaxel CLI by running the following command in a terminal (non-sudo alternatives below):

        ```shell theme={null}
        curl -fsSL \
        https://raw.githubusercontent.com/blaxel-ai/toolkit/main/install.sh \
        | BINDIR=/usr/local/bin sudo -E sh
        ```

        If you need a non-sudo alternative (**it will ask you questions to configure**):

        ```shell theme={null}
        curl -fsSL \
        https://raw.githubusercontent.com/blaxel-ai/toolkit/main/install.sh \
        | sh
        ```

        If you need to install a specific version (e.g. v0.1.21):

        ```shell theme={null}
        curl -fsSL \
        https://raw.githubusercontent.com/blaxel-ai/toolkit/main/install.sh \
        | VERSION=v0.1.21 sh
        ```
      </Accordion>

      <Accordion title="Install on Windows" icon="windows">
        Run the following command in PowerShell:

        ```powershell theme={null}
        powershell -Command "irm https://raw.githubusercontent.com/blaxel-ai/toolkit/main/install.ps1 | iex"
        ```

        Alternatively, you can use Windows Subsystem for Linux (WSL) and follow the Linux installation instructions.
      </Accordion>
    </AccordionGroup>
  </Step>

  <Step title="Login">
    <Accordion title="Login to Blaxel via the CLI.">
      Open a terminal and login to Blaxel using this command:

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

      <Accordion title="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](https://app.blaxel.ai/profile/security). 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:

        ```bash theme={null}
        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.
      </Accordion>
    </Accordion>
  </Step>

  <Step title="Create your first resource">
    Blaxel is the ultimate toolkit for AI agent builders. Our flagship product is the **sandbox**, although we also offer other services for the rest of your agentic workloads on our infrastructure.

    Sandboxes are secure, instant-launching compute environments that you can use for running AI code. Blaxel lets you keeps sandboxes on automatic standby with optimized agent hosting for near instant latency.

    With Blaxel sandboxes, you get:

    * Automatic scale-to-zero after 5s inactivity, resume from standby under 25ms even after weeks.
    * Micro-VMs with full access to file system, processes and logs — and native support for Zero Data Retention (ZDR).
    * Preview URLs with your own custom domain.

    <Accordion title="Create a sandbox" icon="box">
      Sandboxes can be created programmatically using Blaxel SDK. Install the SDK:

      <CodeGroup>
        ```shell Python (pip) theme={null}

        pip install blaxel

        ```

        ```shell Python (uv) theme={null}

        uv pip install blaxel

        ```

        ```shell TypeScript (pnpm) theme={null}

        pnpm install @blaxel/core

        ```

        ```shell TypeScript (npm) theme={null}

        npm install @blaxel/core

        ```

        ```shell TypeScript (yarn) theme={null}

        yarn add @blaxel/core

        ```

        ```shell TypeScript (bun) theme={null}

        bun add @blaxel/core

        ```
      </CodeGroup>

      Create your first sandbox:

      <CodeGroup>
        ```typescript TypeScript theme={null}
        import { SandboxInstance } from "@blaxel/core";

        async function main() {
          // Create a new sandbox
          const sandbox = await SandboxInstance.createIfNotExists({
            name: "my-sandbox",
            image: "blaxel/base-image:latest",   // public or custom image
            memory: 4096,   // in MB
            ports: [{ target: 3000, protocol: "HTTP" }],   // ports to expose
            labels: { env: "dev", project: "my-project" }, // labels
            region: "us-pdx-1"   // deployment region
          });
          console.log("Sandbox created: ", {sandbox});
        }

        main().catch(console.error);
        ```

        ```python Python theme={null}
        import asyncio
        from blaxel.core import SandboxInstance

        async def main():
            # Create a new sandbox
            sandbox = await SandboxInstance.create_if_not_exists({
              "name": "my-sandbox",
              "image": "blaxel/base-image:latest",   # public or custom image
              "memory": 4096,   # in MB
              "ports": [{ "target": 3000 }],   # ports to expose
              "labels": {"env": "dev", "project": "my-project"},  # labels
              "region": "us-pdx-1"   # deployment region
            })
            print(f"Sandbox created: {sandbox}")

        if __name__ == "__main__":
            asyncio.run(main())
        ```
      </CodeGroup>

      <Card title="Learn how to manage sandboxes" icon="box" href="/Sandboxes/Overview">
        Read the complete guide for creating & connecting to sandboxes using Blaxel SDK.
      </Card>
    </Accordion>

    Or deploy another type of resource:

    <Accordion title="Deploy an agent, batch job or MCP server">
      Deploy your agent’s components on a purpose-built computing infrastructure for agentics.

      <Steps>
        <Step title="Create the resource">
          <AccordionGroup>
            <Accordion title="Create an agent app" icon="robot">
              <Warning>In Python, you will need to [have pip installed](https://pip.pypa.io/en/stable/installation/); in TypeScript, you will need to [have npm installed](https://docs.npmjs.com/downloading-and-installing-node-js-and-npm) for this.</Warning>

              Let’s initialize a first app. The following command initializes a new **pre-scaffolded local repository** ready for developing and deploying your agent on Blaxel.

              ```bash theme={null}
              bl new agent
              ```

              You can now develop your agent application using any framework you want (or none), and use the [Blaxel](sdk-reference/introduction) [SDK](sdk-reference) to [leverage other Blaxel deployments](Agents/Develop-an-agent). A placeholder HTTP API server is already preconfigured in `/src/main.py` or `/src/main.ts`.
            </Accordion>

            <Accordion title="Create a batch job" icon="list-check">
              <Warning>In Python, you will need to [have pip installed](https://pip.pypa.io/en/stable/installation/); in TypeScript, you will need to [have npm installed](https://docs.npmjs.com/downloading-and-installing-node-js-and-npm) for this.</Warning>

              Let’s initialize a first batch job definition. The following command initializes a new **pre-scaffolded local repository** ready for developing and deploying your job on Blaxel.

              ```bash theme={null}
              bl new job
              ```

              You can now develop your job and use the [Blaxel](sdk-reference/introduction) [SDK](sdk-reference) to leverage other Blaxel deployments in `/src/index.py` or `/src/index.ts`.
            </Accordion>

            <Accordion title="Create an MCP server" icon="screwdriver-wrench">
              <Warning>In Python, you will need to [have pip installed](https://pip.pypa.io/en/stable/installation/); in TypeScript, you will need to [have npm installed](https://docs.npmjs.com/downloading-and-installing-node-js-and-npm) for this.</Warning>

              You can quickly **initialize a new MCP server from scratch** by using CLI command `bl new`. This initializes a new pre-scaffolded local repo where your entire code can be added.

              ```bash theme={null}
              bl new mcp
              ```

              You can now [develop your MCP server](Functions/Create-MCP-server) using the [Blaxel](sdk-reference/introduction) [SDK](sdk-reference) in `/src/server.py` or `/src/server.ts`.
            </Accordion>
          </AccordionGroup>
        </Step>

        <Step title="Test and deploy your workload">
          Run the following command to serve your workload locally, replacing `<<DIRECTORY-NAME>>` with the name of the workload's root directory:

          ```bash theme={null}
          cd <<DIRECTORY-NAME>>;
          bl serve;
          ```

          <AccordionGroup>
            <Accordion title="Agent: send a test invocation" icon="robot">
              Query your agent locally by making a **POST** request to this endpoint: [`http://localhost:1338`](http://localhost:1338) with the following payload format: `{"inputs": "Hello world!"}`:

              ```bash theme={null}
              curl -X POST -H "Content-Type: application/json" -d '{"inputs": "Hello world!"}' http://localhost:1338
              ```
            </Accordion>

            <Accordion title="Job: execute the job locally" icon="list-check">
              Execute your job locally by making a **POST** request to this endpoint: [`http://localhost:1338`](http://localhost:1338) with the following payload format: `{"tasks": [{"param1": "value1"}]}`

              ```bash theme={null}
              curl -X POST -H "Content-Type: application/json" -d '{"tasks": [{"name": "John"}, {"name": "Jane"}]}' http://localhost:1338
              ```
            </Accordion>

            <Accordion title="MCP server: test the server" icon="screwdriver-wrench">
              You can test it by running the following command which launches **both** the MCP server and a web application to query it ([MCP Inspector](https://github.com/modelcontextprotocol/inspector), managed by MCP) locally.

              <CodeGroup>
                ```shell TypeScript theme={null}

                pnpm inspect

                ```

                ```shell Python theme={null}

                BL_DEBUG=true uv run mcp dev src/server.py

                ```
              </CodeGroup>

              The web application is accessible at: [http://127.0.0.1:6274](http://127.0.0.1:6274/). Alternatively, you can just simply [serve the server](Functions/Deploy-a-function) locally by running `bl serve --hotreload`.
            </Accordion>
          </AccordionGroup>

          To **push to Blaxel**, run the following command. Blaxel will handle the build and deployment:

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

          Your workload is made available as a **serverless auto scalable** **global endpoint** 🌎.
        </Step>

        <Step title="Query your deployment">
          <AccordionGroup>
            <Accordion title="Agent: send an invocation request" icon="robot">
              Run an inference from a terminal with the following command:

              ```bash theme={null}
              bl chat <<AGENT-NAME>>
              ```

              This gives you a chat-like interface where you can interact with your agent. To use this when serving locally, just add option `--local` .

              Alternatively, **just call the** [global endpoint](Agents/Query-agents).
            </Accordion>

            <Accordion title="Job: execute the job" icon="list-check">
              Trigger an execution of your batch job from a terminal by running:

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

              Alternatively, **just call the** [global endpoint](Jobs/Overview).
            </Accordion>

            <Accordion title="MCP server: test the server" icon="screwdriver-wrench">
              When you deploy an MCP server on Blaxel, an **HTTP endpoint** is generated on Global Agentics Network to connect to the server.

              The server endpoint looks like this:

              ```http Connect to an MCP server theme={null}

              https://run.blaxel.ai/{YOUR-WORKSPACE}/functions/{YOUR-SERVER-NAME}/mcp

              ```

              Read more about [how to connect to the server here](Functions/Invoke-functions).
            </Accordion>
          </AccordionGroup>
        </Step>
      </Steps>
    </Accordion>
  </Step>
</Steps>

## Next steps

You are ready to run AI with Blaxel! Here’s a curated list of guides which may be helpful for you to make the most of Blaxel, but feel free to explore the product on your own!

<Card title="Connect your coding agent to Blaxel" icon="robot" href="/skills-mcp">
  Let your AI coding assistant (Cursor, Claude Code, Windsurf…) create and manage Blaxel resources using natural language.
</Card>

<Card title="Create agentic code sandboxes" icon="box" href="/Sandboxes/Overview">
  Complete guide for spawning sandboxed VMs for your agents to access.
</Card>

<Card title="Schedule and execute batch tasks" icon="list-check" href="/Jobs/Overview">
  Complete guide for creating and running batch jobs from your agents.
</Card>

<Card title="Host serverless agents" icon="earth-americas" href="/Agents/Overview">
  Complete guide for deploying AI agents on Blaxel.
</Card>

<Card title="Enforce policies" icon="server" href="/Model-Governance/Policies">
  Complete guide for managing deployment and routing policies on the Global Agentics Network.
</Card>

## Any question?

Although we designed this documentation to be as comprehensive as possible, you are welcome to contact [support@blaxel.ai](mailto:support@blaxel.ai) or the community on [Discord](https://discord.gg/zFcGj77VQx) with any questions or feedback you have.