# Connecting an agent's sandbox

> Authorise a client in a Docker sandbox to use the East India service, with a client certificate that you generate and can revoke.

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:

   ```sh title="On the PC"
   sbx policy allow network --sandbox <sandbox> localhost:7443
   ```

2. **Export a context for the sandbox**, on the PC:

   ```sh title="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.**

   ::: warning 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](https://github.com/teaToolkit/EastIndia/releases), 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:

   ```sh title="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:

```sh title="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.
