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

# Create a local tunnel

<Info>
  Tunnels are not available to customers yet. The production service is disabled
  pending browser-domain isolation, and the planned signed CLI 0.13.1 release is not
  yet published. This page documents the prepared API contract; it does not enable
  the service. See [local tunnels](/guides/local-tunnels) for planned use and risks.
</Info>

Requires an enabled tunnel capability and an account eligible to use tunnels. A new tunnel is private and points to one fixed literal loopback target. Its assigned website URL uses HTTPS; the local server can use HTTP or verified HTTPS.

Creation returns the tunnel record and separate connector and lease credentials. Keep both credentials secret and out of logs. Creating the record does not connect your laptop or deploy an application. The foreground [tunnel command](/guides/local-tunnels#start-privately-when-available) creates a record and runs its connector together, managing the lease for you.

See [local tunnels](/guides/local-tunnels) for access modes, local HTTPS setup, and operating limits.


## OpenAPI

````yaml openapi/tunnels-api.json POST /api/v1/tunnels
openapi: 3.1.0
info:
  title: Rigbox Public API
  description: >-
    Gateway-owned public API for Rigbox. The gateway composes its local
    lifecycle API with service-owned exported specs.
  contact:
    name: Rigbox
    url: https://rigbox.dev
  license:
    name: ''
  version: 1.0.0
servers:
  - url: https://api.rigbox.dev
    description: Production gateway
security: []
tags:
  - name: Tunnels
paths:
  /api/v1/tunnels:
    post:
      tags:
        - Tunnels
      operationId: create
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateTunnelRequest'
        required: true
      responses:
        '201':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CreateTunnelResponse'
        '429':
          description: ''
        '503':
          description: ''
      security:
        - bearer: []
components:
  schemas:
    CreateTunnelRequest:
      type: object
      required:
        - target
      properties:
        target:
          $ref: '#/components/schemas/TunnelTarget'
      additionalProperties: false
    CreateTunnelResponse:
      type: object
      required:
        - tunnel
        - connector_token
        - lease_token
        - connect_url
        - lease_url
        - lease_ttl_seconds
        - max_slots
      properties:
        connect_url:
          type: string
        connector_token:
          type: string
        lease_token:
          type: string
        lease_ttl_seconds:
          type: integer
          format: int64
          minimum: 0
        lease_url:
          type: string
        max_slots:
          type: integer
          format: int32
          minimum: 0
        tunnel:
          $ref: '#/components/schemas/Tunnel'
    TunnelTarget:
      type: object
      required:
        - local_ip
        - port
        - scheme
      properties:
        http_host:
          type:
            - string
            - 'null'
        local_ip:
          type: string
        port:
          type: integer
          format: int32
        scheme:
          type: string
        tls_server_name:
          type:
            - string
            - 'null'
      additionalProperties: false
    Tunnel:
      type: object
      required:
        - id
        - user_id
        - hostname
        - target
        - target_fingerprint
        - visibility
        - status
        - policy_epoch
        - connection_generation
        - expires_at
        - created_at
        - updated_at
      properties:
        connection_generation:
          type: integer
          format: int64
        created_at:
          type: string
          format: date-time
        expires_at:
          type: string
          format: date-time
        hostname:
          type: string
        id:
          type: string
        lease_expires_at:
          type:
            - string
            - 'null'
          format: date-time
        policy_epoch:
          type: integer
          format: int64
        status:
          type: string
        target:
          $ref: '#/components/schemas/TunnelTarget'
        target_fingerprint:
          type: string
        updated_at:
          type: string
          format: date-time
        user_id:
          type: string
        visibility:
          type: string
  securitySchemes:
    bearer:
      type: http
      scheme: bearer

````

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