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

# Ports

> Expose specific TCP ports on a Blaxel sandbox so external clients can connect to web servers, dev servers, or other services running inside it.

Your sandbox, just like any virtual machine, can **expose ports**. These ports let you connect to a process or app running in the sandbox.

## Reserved ports

The following ports are reserved by Blaxel's system:

* **443**: This port hosts the main [sandbox API](https://docs.blaxel.ai/api-reference/filesystem/get-file-or-directory-information) and is exposed via HTTPS
* **80**: Reserved for system operations
* **8080**: Reserved for sandbox API functionality

You can expose and use any other port on your sandbox.

## Expose a port

<Note>
  To whitelist sandbox traffic in your network, you can [retrieve the public IP addresses](/Infrastructure/Regions#public-ip-addresses) used by Blaxel.
</Note>

You can expose specific non-reserved ports [**when creating a new sandbox**](/Sandboxes/Overview) by using the `ports` parameter. This allows you to access these ports from outside the sandbox via the sandbox API.

<Note>
  You only need to expose ports at sandbox creation time if you plan to access the port via the sandbox API. For access via [preview URL](./Preview-url), ports are dynamically opened as needed.
</Note>

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

  // Create a new sandbox
  const sandbox = await SandboxInstance.create({
    name: "my-sandbox",
    image: "blaxel/base-image:latest",
    memory: 4096,
    region: "us-pdx-1",
    ports: [{ target: 3000 }]
  });
  ```

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

  # Create a new sandbox
  sandbox = await SandboxInstance.create({
    "name": "my-sandbox",
    "image": "blaxel/base-image:latest",
    "memory": 4096,
    "region": "us-pdx-1",
    "ports": [{ "target": 3000 }]
  })
  ```
</CodeGroup>

## Access the sandbox on a specific port

### Via the sandbox API

This option requires your request to be [authenticated](../Security/Access-tokens). You can access your sandbox on a specific port through the sandbox API using the following URL format:

```text theme={null}
https://sbx-{resource_name}-{workspace_id}.{region_id}.bl.run/port/{port_number}
```

For example to connect to port 3000 on `my-sandbox` in workspace `abc123`: `https://sbx-my-sandbox-abc123.us-pdx-1.bl.run/port/3000`

Request paths, if any, can be specified after the port number. For example: `https://sbx-my-sandbox-abc123.us-pdx-1.bl.run/port/3000/my/api/endpoint`

### Via a preview URL

[Preview URLs](/Sandboxes/Preview-url) provide a simple URL that maps to an internal port of your sandbox. You can either make this URL fully public or secure it with token-based authentication.

Generally speaking:

* for file and process management in your sandbox, use the sandbox API or SDK.
* to access running applications within the sandbox *(such as a NextJS preview server on port 3000)*, use a preview URL instead.

### Via SDK

<Tabs>
  <Tab title="sandbox.fetch() (recommended)">
    <Note>
      Available in `@blaxel/core` >= 0.2.79 (Node.js) and `blaxel` >= 0.2.49 (Python).
    </Note>

    The SDK provides a built-in `fetch` method that handles authentication and proxies requests through the sandbox's `/port/{port}` endpoint.

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

      const sandbox = await SandboxInstance.get("my-sandbox");

      // Fetch a resource on port 3000
      const response = await sandbox.fetch(3000);
      console.log(await response.text());

      // Fetch with a specific path
      const apiResponse = await sandbox.fetch(3000, "/api/health");
      console.log(await apiResponse.json());
      ```

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

      sandbox = await SandboxInstance.get("my-sandbox")

      # Fetch a resource on port 3000
      response = await sandbox.fetch(3000)
      print(response.text)

      # Fetch with a specific path
      api_response = await sandbox.fetch(3000, "/api/health")
      print(api_response.json())

      # Fetch with a custom HTTP method
      post_response = await sandbox.fetch(3000, "/api/data", method="POST", json={"key": "value"})
      print(post_response.json())
      ```
    </CodeGroup>
  </Tab>

  <Tab title="Manual URL (older SDKs)">
    For older SDK versions, you can construct the port URL manually. This requires your request to be [authenticated](../Security/Access-tokens).

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

      // Connect to existing sandbox
      const sandbox = await SandboxInstance.get("my-sandbox")

      // Get URL for port access
      const url = `${sandbox.metadata.url}/port/3000`

      // Use the URL with authenticated requests
      const response = await fetch(url, {
        headers: { 'Authorization': 'Bearer YOUR_TOKEN' }
      })
      ```

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

      # Connect to existing sandbox
      sandbox = await SandboxInstance.get("my-sandbox")

      # Get URL for port access
      url = f"{sandbox.metadata.url}/port/3000"

      # Use the URL with authenticated requests
      response = requests.get(url, headers={ "Authorization": f"Bearer YOUR_TOKEN" })
      ```
    </CodeGroup>
  </Tab>
</Tabs>

<Card title="Create preview URLs" icon="eye" href="/Sandboxes/Preview-url">
  Expose applications running within the sandbox via a direct preview URL.
</Card>