Skip to main content
This guide explains how to run an Astro application inside a Blaxel Sandbox and expose it securely using Blaxel previews.

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 Astro inside a Blaxel Sandbox requires a few adjustments:
  • Astro normally binds to localhost
  • Blaxel exposes services through preview URLs
  • Astro must accept external connections and all hosts
Configure astro.config.mjs with host: "0.0.0.0" and allowedHosts: true, then expose the Astro development server through a Blaxel preview URL.

2. Build the sandbox image

Create a Dockerfile:

3. Configure Astro

Create astro.config.mjs to allow external connections:

4. Create the entrypoint

Create entrypoint.sh to start the sandbox API and Astro development server:

5. Configure and deploy the image

Create blaxel.toml beside the Dockerfile:
Deploy the image:

6. Create or reuse a sandbox

7. Configure preview response headers

Astro development servers work well with permissive CORS headers when accessed through a preview URL:
Alternatively, use custom domains to expose previews on your own domain.

8. Create the preview and token

Astro runs on port 4321. Create a private preview for that port:
Generate a token that expires after one day:

9. Start and monitor the development server

If you do not use the entrypoint script, start Astro programmatically:
Stream its logs:

10. Access the Astro application

Once the server is running, open:

11. Run the complete example

This setup runs Astro fully inside a Blaxel Sandbox, securely exposes the development server, supports hot module replacement, and uses Bun for fast dependency installation and development server performance. It is suitable for static sites, blogs, documentation, preview environments, internal demos, and AI-powered coding workflows.

Resources

Real-time previews

Configure public and private preview URLs for sandbox services.

Sandbox images

Build and manage reusable Blaxel Sandbox images.
Last modified on October 5, 2026