Set up Expo with Blaxel Sandboxes

This guide explains how to run an Expo React Native and web application inside a Blaxel Sandbox, expose it securely using Blaxel previews, and access it on a mobile device.

Prerequisites

Blaxel CLI installed and authenticated with bl login
Node.js 18 or later
@blaxel/core installed in your project with npm install @blaxel/core

1. Understand the architecture

Running Expo inside a Blaxel Sandbox requires a few adjustments:

Expo normally binds to local or internal URLs
Blaxel exposes services through preview URLs
Expo must use those preview URLs explicitly

Inject the preview URL into app.json, set EXPO_PACKAGER_PROXY_URL, restart the development server after configuration changes, and expose the Expo server through a Blaxel preview URL.

2. Build the sandbox image

Create a Dockerfile:

FROM node:22-alpine

RUN apk update && apk add --no-cache \
  git \
  curl \
  netcat-openbsd \
  && rm -rf /var/cache/apk/*

WORKDIR /app

COPY --from=ghcr.io/blaxel-ai/sandbox:latest /sandbox-api /usr/local/bin/sandbox-api

# Create an Expo project with the default template
RUN npx create-expo-app@latest .

# Install the dependencies required for Expo web support
RUN npx expo install react-dom react-native-web

# Pre-warm the Metro bundler cache using the development server
RUN timeout 120 npx expo start --web --port 8081 --no-dev-client 2>/dev/null || true

ENV PATH="/usr/local/bin:$PATH"

ENTRYPOINT ["/usr/local/bin/sandbox-api"]

3. Configure and deploy the image

Create blaxel.toml beside the Dockerfile:

type = "sandbox"
name = "expo-template"

[runtime]
memory = 8192

[[runtime.ports]]
name = "expo-web"
target = 8081

Deploy the image:

bl deploy

4. Create or reuse a sandbox

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

const sandboxName = "my-expo-sandbox";

const sandbox = await SandboxInstance.createIfNotExists({
  name: sandboxName,
  labels: {
    framework: "expo",
  },
  image: "expo-template:latest",
  memory: 8192,
  ports: [
    { name: "preview", target: 8081, protocol: "HTTP" },
  ],
});

5. Configure preview response headers

Expo development servers require permissive CORS headers when accessed through a preview URL:

const responseHeaders = {
  "Access-Control-Allow-Origin": "*",
  "Access-Control-Allow-Methods": "GET, POST, PUT, DELETE, OPTIONS, PATCH",
  "Access-Control-Allow-Headers":
    "Content-Type, Authorization, X-Requested-With, X-Blaxel-Workspace, X-Blaxel-Preview-Token, X-Blaxel-Authorization",
  "Access-Control-Allow-Credentials": "true",
  "Access-Control-Expose-Headers": "Content-Length, X-Request-Id",
  "Access-Control-Max-Age": "86400",
  Vary: "Origin",
};

Alternatively, use custom domains to expose previews on your own domain.

6. Create the preview and token

Expo runs on port 8081. Create a private preview for that port:

const preview = await sandbox.previews.createIfNotExists({
  metadata: { name: "dev-server-preview" },
  spec: {
    responseHeaders,
    public: false,
    port: 8081,
  },
});

Generate a token that expires after one day:

const expiresAt = new Date(Date.now() + 1000 * 60 * 60 * 24);
const token = await preview.tokens.create(expiresAt);

7. Inject the preview URL into Expo

Expo Router requires the correct origin when it runs behind a proxy. Update app.json in the sandbox:

async function addRouterOriginToAppJson(
  sandbox: SandboxInstance,
  previewUrl: string
) {
  const appJsonPath = "/app/app.json";
  const appJsonContent = await sandbox.fs.read(appJsonPath);
  const appJson = JSON.parse(appJsonContent);

  appJson.expo = {
    ...appJson.expo,
    extra: {
      ...(appJson.expo.extra || {}),
      router: {
        ...(appJson.expo.extra?.router || {}),
        origin: previewUrl,
      },
    },
  };

  await sandbox.fs.write(appJsonPath, JSON.stringify(appJson, null, 2));
}

8. Configure the proxy URL

Expo must serve assets through the preview URL. The following function updates .env only when the expected value is missing:

async function configureExpoProxyUrl(
  sandbox: SandboxInstance,
  previewUrl: string
): Promise<boolean> {
  const baseUrl = previewUrl.replace(/\/$/, "");

  let envContent = "";
  try {
    envContent = await sandbox.fs.read("/app/.env");
  } catch {
    // The file does not exist yet
  }

  const expectedEnvLine = `EXPO_PACKAGER_PROXY_URL=${baseUrl}`;

  if (envContent.includes(expectedEnvLine)) {
    console.log("Expo proxy URL already configured correctly");
    return false;
  }

  const lines = envContent
    .split("\n")
    .filter((line) => !line.startsWith("EXPO_PACKAGER_PROXY_URL="));
  lines.push(expectedEnvLine);

  await sandbox.fs.write("/app/.env", lines.join("\n"));
  console.log(`Configured Expo to use proxy URL: ${baseUrl}`);
  return true;
}

9. Start and monitor the development server

After setting the proxy URL, start the development server:

async function startDevServer(sandbox: SandboxInstance) {
  console.log("Starting dev server with updated configuration...");
  await sandbox.process.exec({
    name: "dev-server",
    command: "npx expo start --web --port 8081 --scheme exp",
    workingDir: "/app",
    waitForPorts: [8081],
    restartOnFailure: true,
    maxRestarts: 25,
  });
}

Stream its logs:

const logStream = sandbox.process.streamLogs("dev-server", {
  onLog(log) {
    console.log(log);
  },
});

logStream.close();

10. Access the Expo application

Open the web application at:

${preview.spec?.url}?bl_preview_token=${token.value}

To access the application on a mobile device, build an Expo URL from the authenticated preview URL:

const previewUrl = `${preview.spec?.url}?bl_preview_token=${token.value}`;
const expoUrl = previewUrl.replace("https://", "exp://");

Encode the exp:// URL in a QR code:

exp://your-sandbox.preview.blaxel.ai/?bl_preview_token=your-token

Scan the QR code with your device’s camera or the Expo Go application.

11. Run the complete example

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

const sandboxName = "my-expo-sandbox";

const responseHeaders = {
  "Access-Control-Allow-Origin": "*",
  "Access-Control-Allow-Methods": "GET, POST, PUT, DELETE, OPTIONS, PATCH",
  "Access-Control-Allow-Headers":
    "Content-Type, Authorization, X-Requested-With, X-Blaxel-Workspace, X-Blaxel-Preview-Token, X-Blaxel-Authorization",
  "Access-Control-Allow-Credentials": "true",
  "Access-Control-Expose-Headers": "Content-Length, X-Request-Id",
  "Access-Control-Max-Age": "86400",
  Vary: "Origin",
};

async function addRouterOriginToAppJson(
  sandbox: SandboxInstance,
  previewUrl: string
) {
  const appJsonPath = "/app/app.json";
  const appJsonContent = await sandbox.fs.read(appJsonPath);
  const appJson = JSON.parse(appJsonContent);

  appJson.expo = {
    ...appJson.expo,
    extra: {
      ...(appJson.expo.extra || {}),
      router: {
        ...(appJson.expo.extra?.router || {}),
        origin: previewUrl,
      },
    },
  };

  await sandbox.fs.write(appJsonPath, JSON.stringify(appJson, null, 2));
}

async function configureExpoProxyUrl(
  sandbox: SandboxInstance,
  previewUrl: string
): Promise<boolean> {
  const baseUrl = previewUrl.replace(/\/$/, "");

  let envContent = "";
  try {
    envContent = await sandbox.fs.read("/app/.env");
  } catch {
    // The file does not exist
  }

  const expectedEnvLine = `EXPO_PACKAGER_PROXY_URL=${baseUrl}`;
  if (envContent.includes(expectedEnvLine)) {
    return false;
  }

  const lines = envContent
    .split("\n")
    .filter((line) => !line.startsWith("EXPO_PACKAGER_PROXY_URL="));
  lines.push(expectedEnvLine);

  await sandbox.fs.write("/app/.env", lines.join("\n"));
  return true;
}

async function startDevServer(sandbox: SandboxInstance) {
  await sandbox.process.exec({
    name: "dev-server",
    command: "npx expo start --web --port 8081 --scheme exp",
    workingDir: "/app",
    waitForPorts: [8081],
    restartOnFailure: true,
    maxRestarts: 25,
  });
}

async function configureExpo(
  sandbox: SandboxInstance,
  previewUrl: string
) {
  await addRouterOriginToAppJson(sandbox, previewUrl);
  await configureExpoProxyUrl(sandbox, previewUrl);
  await startDevServer(sandbox);
}

async function main() {
  try {
    const sandbox = await SandboxInstance.createIfNotExists({
      name: sandboxName,
      labels: {
        framework: "expo",
      },
      image: "expo-template:latest",
      memory: 8192,
      ports: [
        { name: "preview", target: 8081, protocol: "HTTP" },
      ],
    });

    const preview = await sandbox.previews.createIfNotExists({
      metadata: { name: "preview" },
      spec: {
        responseHeaders,
        public: false,
        port: 8081,
      },
    });

    const expiresAt = new Date(Date.now() + 1000 * 60 * 60 * 24);
    const token = await preview.tokens.create(expiresAt);

    await configureExpo(sandbox, preview.spec?.url!);

    const processes = await sandbox.process.list();
    if (!processes.find((process) => process.name === "dev-server")) {
      await startDevServer(sandbox);
    }

    const webUrl = `${preview.spec?.url}?bl_preview_token=${token.value}`;
    const expoUrl = webUrl.replace("https://", "exp://");
    console.log(`Web Preview URL: ${webUrl}`);
    console.log(`Expo Mobile URL: ${expoUrl}`);

    const logStream = sandbox.process.streamLogs("dev-server", {
      onLog(log) {
        console.log(log);
      },
    });

    process.on("SIGINT", () => {
      logStream.close();
      process.exit(0);
    });
  } catch (error) {
    console.error("Error:", error);
    process.exit(1);
  }
}

main();

This setup runs Expo fully inside a Blaxel Sandbox, securely exposes the development server, supports Expo Router and asset loading, provides mobile access through the exp:// protocol, and starts the server after configuration changes. It is suitable for preview environments, internal demos, and AI-powered coding workflows.

Get Started

Sandboxes

Agent Drive

Volumes

Batch Jobs

Applications

MCP Servers Hosting

Model Gateway

Observability

Integrations

Administration & security

Troubleshooting

Set up Expo with Blaxel Sandboxes

Prerequisites

1. Understand the architecture

2. Build the sandbox image

3. Configure and deploy the image

4. Create or reuse a sandbox

5. Configure preview response headers

6. Create the preview and token

7. Inject the preview URL into Expo

8. Configure the proxy URL

9. Start and monitor the development server

10. Access the Expo application

11. Run the complete example

Resources

Real-time previews

Sandbox images

​Prerequisites

​1. Understand the architecture

​2. Build the sandbox image

​3. Configure and deploy the image

​4. Create or reuse a sandbox

​5. Configure preview response headers

​6. Create the preview and token

​7. Inject the preview URL into Expo

​8. Configure the proxy URL

​9. Start and monitor the development server

​10. Access the Expo application

​11. Run the complete example

​Resources

Real-time previews

Sandbox images

Prerequisites

1. Understand the architecture

2. Build the sandbox image

3. Configure and deploy the image

4. Create or reuse a sandbox

5. Configure preview response headers

6. Create the preview and token

7. Inject the preview URL into Expo

8. Configure the proxy URL

9. Start and monitor the development server

10. Access the Expo application

11. Run the complete example

Resources