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

# Open a credential relay tunnel

> An HTTP Upgrade to an idle reverse tunnel for the sandbox's outbound connections: the sandbox's proxy requests are paired with it, so your side answers them and the box only passes bytes. `coreload agent run` uses it. The 101 answer names the proxy address the sandbox uses (`x-coreload-relay-proxy`).

Needs the `use` scope.



## OpenAPI

````yaml /openapi.json post /v1/sandboxes/{id}/relay
openapi: 3.1.0
info:
  title: Coreload sandbox API
  version: '1'
  description: >-
    Create short-lived sandboxes, run commands in them and move files in and
    out. The API is in beta and not offered to outside callers yet: there are no
    API keys for outside callers. A call gets a ticket for a box from the edge
    with an API key, then calls the box at the ticket's URL with the ticket's
    `authorization` header. Answers are JSON, except a file download (its bytes)
    and a tunnel (a 101 upgrade); a JSON error is `{ok: false, error: {code,
    message}}`.
servers:
  - url: '{box}'
    description: The box URL from your ticket (`url`).
    variables:
      box:
        default: https://box.coreload.example
        description: The ticket's url.
security:
  - ticket: []
  - apiKey: []
tags:
  - name: Access
    description: 'Tickets: how a key reaches a box.'
  - name: Sandboxes
    description: Create, list, get and destroy sandboxes.
  - name: Runs
    description: Run commands in a sandbox and read their results and output.
  - name: Files
    description: Move files in and out of a sandbox.
  - name: Tunnels
    description: >-
      Byte tunnels over an HTTP upgrade: to a sandbox's SSH server or desktop,
      and the relay that answers a sandbox's outbound connections from your
      side.
paths:
  /v1/sandboxes/{id}/relay:
    post:
      tags:
        - Tunnels
      summary: Open a credential relay tunnel
      description: >-
        An HTTP Upgrade to an idle reverse tunnel for the sandbox's outbound
        connections: the sandbox's proxy requests are paired with it, so your
        side answers them and the box only passes bytes. `coreload agent run`
        uses it. The 101 answer names the proxy address the sandbox uses
        (`x-coreload-relay-proxy`).


        Needs the `use` scope.
      operationId: relayTunnel
      parameters:
        - name: id
          in: path
          required: true
          description: The sandbox id (`sbx_` and 12 hex).
          schema:
            type: string
            pattern: ^sbx_[0-9a-f]{12}$
        - name: Connection
          in: header
          required: true
          description: The upgrade handshake.
          schema:
            const: Upgrade
        - name: Upgrade
          in: header
          required: true
          description: The tunnel protocol.
          schema:
            const: coreload-relay
        - name: x-coreload-relay-token-sha256
          in: header
          required: true
          description: >-
            The SHA-256 (64 lowercase hex) of the relay token the sandbox's
            proxy settings carry.
          schema:
            type: string
            pattern: ^[0-9a-f]{64}$
      responses:
        '101':
          description: 'Switching protocols: the connection is the tunnel.'
        '400':
          description: Not a POST with this Upgrade, or no valid token hash. (empty body)
        '401':
          description: >-
            Missing or wrong credentials, or a key without the use scope here.
            (empty body)
        '404':
          description: No such sandbox of yours. (empty body)
        '409':
          description: The sandbox is bound to another relay token or caller. (empty body)
        '429':
          description: Too many relay tunnels or bindings. (empty body)
        default:
          description: An error, with an empty body.
components:
  securitySchemes:
    ticket:
      type: apiKey
      in: header
      name: Authorization
      description: >-
        The ticket's `authorization` value, sent as it is (its own scheme, not
        Bearer), until the ticket's `expiresAt`.
    apiKey:
      type: http
      scheme: bearer
      description: >-
        An API key: `Authorization: Bearer <key>`. The edge takes it for a
        ticket; a box takes a key issued for that box. Keys are not issued to
        outside callers yet.

````

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