Connecting an agent's sandbox

A client in a Docker sandbox on the PC connects to the East India service over HTTPS and authenticates with a client certificate. You generate the certificate and can revoke it at any time.

How the connection works

The service's HTTPS address is the PC's own loopback address, 127.0.0.1:7443. A sandbox cannot use that address, because inside the sandbox it means the sandbox itself. Instead, the sandbox's proxy forwards host.docker.internal to the PC's loopback address for each port that the sandbox's policy allows, and passes the encrypted connection through untouched.

Connect a sandbox

  1. Allow the port, once per sandbox, on the PC. sbx is the Docker Sandboxes command that runs on the PC; <sandbox> is the sandbox's name, which hostname prints inside it:

    On the PC
    sbx policy allow network --sandbox <sandbox> localhost:7443
    
  2. Export a context for the sandbox, on the PC:

    On the PC
    endia context export sandbox-1
    

    The East India service issues a new client certificate named sandbox-1, valid for 365 days. The command writes sandbox-1.eastindiacontext, which holds the address the sandbox connects to and the certificate files, in the layout that docker context export uses. --eastindia-host changes the address, which is tcp://host.docker.internal:7443 by default. You can also create the certificate on the desktop app's Connections page.

  3. Copy the file into the sandbox as a file.

    Do not store it as a sandbox secret

    With sbx secret, the sandbox's proxy opens the encrypted connection itself, and the service never sees the client certificate.

  4. Get the Linux command line. The MSI holds only the Windows command line. Download endia-linux-x64 from the Releases page, make it executable with chmod +x endia-linux-x64, and put it on the sandbox's PATH as endia.

  5. Import the context and use it, in the sandbox, then delete the file:

    In the sandbox
    endia context import pc sandbox-1.eastindiacontext
    endia context use pc
    endia version
    

    endia version prints the versions of both the command line and the service. When the service refuses the certificate or cannot be reached, the command exits with 1 and names the cause.

The file holds a private key

The context file holds the certificate's private key unencrypted, so keep it where only you can read it. The service issues certificates only to callers on the PC's named pipe, so a sandbox cannot give itself more.

Renew or end access

A certificate lasts 365 days. After that the service refuses it, and the sandbox needs a new one: revoke the old certificate with endia cert rm sandbox-1, then run endia context export again.

On the PC, endia cert rm sandbox-1 ends a certificate at once and closes its open connections, and endia cert ls lists every certificate with its state. Both work only on the PC, through the named pipe, so a sandbox cannot list or end another's access.

Environment variables

Two environment variables can name the address and a folder that holds ca.pem, cert.pem and key.pem, as DOCKER_HOST and DOCKER_CERT_PATH do:

In the sandbox
export EASTINDIA_HOST=tcp://host.docker.internal:7443
export EASTINDIA_CERT_PATH=<folder>

Published ports

A machine's published port works the same way. From a sandbox, connect to host.docker.internal:<port> after allowing localhost:<port> in the sandbox's policy, as step 1 does for port 7443.