Endpoints

All workloads running inside a sandbox are connected to a private network and can communicate with each other directly using hostnames or IP addresses on any port. To make services accessible from outside the sandbox, listening ports must be explicitly declared and exposed using Endpoints.

An endpoint defined in a sandbox is assigned an external-facing DNS name. Depending on the endpoint type, it can be accessed via HTTPS or TCP over TLS.

HTTP Endpoint

An HTTP endpoint supports simple path-based routing to one or more backends. For example:

endpoints:
- name: app
  http:
    routes:
    - path_prefix: /api
      backend:
        target: backend
        port: api
    - path_prefix: /
      backend:
        target: frontend
        port: http
workspaces:
- name: frontend
  ports:
  - name: http
    port: 8000
    protocol: HTTP/TCP
  ...
- name: backend
  ports:
  - name: api
    port: 9000
    protocol: HTTP/TCP

With this definition (sandbox named foo in org org), the endpoint is accessible at https://app--foo-org.APP-DOMAIN. For Crafting SaaS, APP-DOMAIN is sandboxes.run. For self-hosted deployments, contact your org admin.

Authentication

HTTP endpoints enforce authentication by default (secure by default). Visitors must log in to the Crafting system before accessing the endpoint, and must be valid members of the org.

To allow external users (non-org members) to access the endpoint, add rules under auth_proxy:

endpoints:
- name: app
  http:
    routes:
    - path_prefix: /
      backend:
        target: frontend
        port: http
    auth_proxy:
      rules:
      - action: ACCEPT
        pattern: '*@vendor.com'
      - action: REJECT
        pattern: 'blocked@foo.com'
      - action: REJECT
        regexp: '^[0-9]+.*$'

To restrict access to only a specific list of users (excluding even org members), add disable_defaults: true:

    auth_proxy:
      disable_defaults: true
      rules:
      - action: ACCEPT
        pattern: 'foo@example.com'
      - action: ACCEPT
        regexp: '^bot-.+@example.com$'

To completely disable authentication (use with caution — the endpoint becomes publicly accessible), add disabled: true:

    auth_proxy:
      disabled: true

Routing

HTTP endpoints support path-based routing. Multiple routes entries can be defined using path_prefix. The system uses longest matching first policy to select the best matching rule.

Default Path

When a user clicks an endpoint in the Web UI, it opens the endpoint URL in a browser. For applications that expect a non-root starting path, specify path:

endpoints:
- name: app
  http:
    routes:
    - path_prefix: /
      backend:
        target: frontend
        port: http
    path: /dashboard

This is informational for the Web UI only — clicking the endpoint launches https://DNS/dashboard. The endpoint itself still accepts requests at all paths.

Header Injection

Additional headers can be injected into requests and responses:

endpoints:
- name: app
  http:
    routes:
    - path_prefix: /
      backend:
        target: frontend
        port: http
    request_headers:
      X-Foo: Bar
    response_headers:
      X-Extra: Something

TCP Endpoint

A TCP endpoint exposes a port from a workload to the external network under a DNS name, accessed over TLS:

endpoints:
- name: app
  tcp:
    backend:
      target: foo
      port: app

The endpoint is accessible at app--SANDBOX-ORG.APP-DOMAIN via TLS.

Self-hosting note: TCP endpoints require the load balancer to forward the SNI (Server Name Indicator) from the TLS handshake. They cannot be supported if the load balancer does not pass SNI.

TLS Passthrough

By default, the TCP endpoint terminates TLS. To allow the workload to handle TLS certificates directly, enable TLS passthrough:

endpoints:
- name: app
  tcp:
    backend:
      target: foo
      port: tls
    tls_passthrough: true

Internal Endpoints

An Internal Endpoint is only accessible from within workloads of running sandboxes in the same org — not from external clients. Add type: INTERNAL:

endpoints:
- name: app
  type: INTERNAL
  http:
    routes:
    - path_prefix: /
      backend:
        target: frontend
        port: http

The endpoint is assigned a special internal-only DNS name such as app--SANDBOX-ORG.internal.sandbox, which resolves only from within sandbox workloads in the org. It must be accessed via TLS with a certificate signed by the Crafting system's internal CA.

Both HTTP and TCP endpoints can be defined as INTERNAL. For internal HTTP endpoints, auth_proxy configuration applies in the same way as for regular endpoints.

Advanced HTTP Configurations (Passthrough Mode)

These are advanced auth_proxy configurations for special situations. Enabling Passthrough Mode changes how the endpoint handles requests.

Header Matching

Require specific headers in the request before passing it to the backend:

    auth_proxy:
      mode: PASSTHROUGH
      passthrough:
        required_headers:
        - header: X-Api-Key
          regexp: '^123456$'

If the headers do not match, the endpoint returns 401. To fall back to the standard login flow instead of a 401:

    auth_proxy:
      mode: PASSTHROUGH
      passthrough:
        required_headers:
        - header: X-Api-Key
          regexp: '^123456$'
        fallback_to_login: true

OAuth Callback Dispatching

Some OAuth providers (e.g. Google) require precise callback URLs, which is problematic when multiple ephemeral sandboxes each have unique endpoint DNS names.

To solve this, register a single callback URL with the OAuth provider: https://login.SYS-DOMAIN/oauth/callback (where SYS-DOMAIN is sandboxes.cloud for Crafting SaaS users).

Then configure the endpoint:

endpoints:
- name: callback
  http:
    routes:
    - path_prefix: /
      backend:
        target: workload
        port: http
    auth_proxy:
      mode: PASSTHROUGH
      passthrough:
        oauth_callback_path: /some-callback-path

The Crafting Login Service will dispatch the OAuth callback to the correct sandbox endpoint automatically.