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

# Expose a port on a public URL

> Give a port inside a sandbox a stable HTTPS URL on on.boat.dev, private with a token or public. Same as boat host.



## OpenAPI

````yaml openapi/boat-v1.yaml POST /sandboxes/{sandboxId}/host
openapi: 3.1.0
info:
  title: Boat Public API v1
  version: 1.0.0
  description: >
    Public JSON API for creating, operating, prompting, observing, and exposing
    sandboxes from backend services, CI jobs, hosted workers, and Boat
    automation products.


    The v1 reference intentionally documents the developer integration surface
    only. Dashboard billing actions are not part of v1.
servers:
  - url: https://boat.dev/api/v1
security:
  - BoatBearerAuth: []
tags:
  - name: Boat
    description: >-
      Unified Boat account, setup, lifecycle, prompting, event history, desktop
      access, and SSH operations.
paths:
  /sandboxes/{sandboxId}/host:
    post:
      tags:
        - Boat
      summary: Expose a sandbox port on a public HTTPS URL
      description: >-
        Registers a stable `https://<sandbox-subdomain>-<port>.on.boat.dev`
        route for a port inside the sandbox and opens the sandbox firewall for
        it. Idempotent: calling it again for the same sandbox and port returns
        the same URL and token.
      operationId: hostPort
      parameters:
        - $ref: '#/components/parameters/SandboxId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/HostPortRequest'
      responses:
        '200':
          description: The public HTTPS URL for the port.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HostPortResponse'
              examples:
                hosted:
                  value:
                    ok: true
                    type: port.hosted
                    success: true
                    port: 3000
                    url: https://swift-otter-9021-3000.on.boat.dev?_token=redacted
                    isProtected: true
                    access: private
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '402':
          $ref: '#/components/responses/PaymentRequired'
        '404':
          $ref: '#/components/responses/NotFound'
components:
  parameters:
    SandboxId:
      name: sandboxId
      in: path
      required: true
      schema:
        type: string
        pattern: ^bx_[23456789abcdefghjkmnpqrstuvwxyz]{8}$
      description: Public Sandbox id returned by create/list/get sandbox calls.
  schemas:
    HostPortRequest:
      type: object
      required:
        - port
      properties:
        port:
          type: integer
          minimum: 1
          maximum: 65535
          description: Port the service listens on inside the sandbox.
        public:
          type: boolean
          default: false
          description: >-
            Return an ungated URL instead of one that requires the `_token`
            query parameter.
        localhost:
          type: boolean
          default: false
          description: >-
            Set when the service listens on localhost (`127.0.0.1` or `::1`)
            only. The sandbox relays the URL to it. Leave unset for a service
            bound to `0.0.0.0`. Each call sets the value again.
        title:
          type: string
          description: Display title for the hosted port.
    HostPortResponse:
      allOf:
        - $ref: '#/components/schemas/SuccessBase'
        - type: object
          additionalProperties: true
          properties:
            type:
              type: string
              examples:
                - port.hosted
            success:
              type: boolean
            port:
              type: integer
            url:
              type: string
              format: uri
              description: >-
                Public HTTPS URL. Carries the `_token` query parameter unless
                the port is public; redact from logs.
            isProtected:
              type: boolean
            access:
              type: string
              enum:
                - private
                - public
            localhost:
              type: boolean
              description: >-
                The sandbox relays the URL to a service that listens on
                localhost only.
    SuccessBase:
      type: object
      required:
        - ok
        - type
      properties:
        ok:
          type: boolean
          examples:
            - true
        type:
          type: string
          description: Stable success envelope discriminator added by v1.
    ErrorEnvelope:
      type: object
      required:
        - ok
        - type
        - status
        - code
        - message
        - error
        - requestId
      properties:
        ok:
          type: boolean
          examples:
            - false
        type:
          type: string
          examples:
            - sandbox.error
        status:
          type: integer
          examples:
            - 409
        code:
          type: string
          examples:
            - provider_not_configured
        message:
          type: string
          examples:
            - Prompting is locked until Codex is configured on the Agents page.
        requestId:
          type: string
          examples:
            - req_01HX...
        error:
          type: object
          required:
            - code
            - message
            - status
          properties:
            code:
              type: string
            message:
              type: string
            status:
              type: integer
            details:
              type: object
              additionalProperties: true
  responses:
    BadRequest:
      description: Invalid request body or parameters.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorEnvelope'
          examples:
            invalid:
              value:
                ok: false
                type: sandbox.error
                status: 400
                code: invalid_json
                message: Request body must be valid JSON.
                error:
                  code: invalid_json
                  message: Request body must be valid JSON.
                  status: 400
                requestId: req_01HX...
    Unauthorized:
      description: Missing or invalid bearer token.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorEnvelope'
          examples:
            unauthorized:
              value:
                ok: false
                type: sandbox.error
                status: 401
                code: unauthorized
                message: Unauthorized
                error:
                  code: unauthorized
                  message: Unauthorized
                  status: 401
                requestId: req_01HX...
    PaymentRequired:
      description: >-
        Account cannot currently create or operate sandboxes. The error body may
        include a dashboard billing URL, but billing actions are not part of the
        v1 API.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorEnvelope'
    NotFound:
      description: Resource not found.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorEnvelope'
  securitySchemes:
    BoatBearerAuth:
      type: http
      scheme: bearer
      bearerFormat: sandbox_api_key
      description: >-
        Boat bearer token in the form `boat_...`. Service API keys authenticate
        sandbox operations.

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.