# Core concepts

> The key terms, what you need to connect to the service, and the six steps every test follows.

East India runs Windows virtual machines the way Docker runs containers, for automated tests, development and build machines, and any other work that needs a clean Windows. One Windows PC with Hyper-V runs the East India service. You and your agent talk to the service with the `endia` command line, which takes Docker's commands and options wherever Docker has one.

## Key terms

- The **service** is the East India program on the Windows PC that hosts Hyper-V. It creates, starts and removes machines, and talks to the programs inside them.
- **`endia`** is the command line that asks the service for work. It runs on the PC or in a Docker sandbox on the same PC.
- An **image** is a Windows disk that machines start from. A **root image** is Windows prepared once from Microsoft's installation disc; a built image adds a recipe's steps on top of a parent image, as `docker build` does.
- A **layer** is a built image stored over its parent as a disk of differences. East India makes one layer for each stage of a recipe.
- An **Endiafile** is a recipe for an image, in Dockerfile syntax.
- A **machine** is a Hyper-V virtual machine, created from an image on a new disk of its own. Removing it deletes that disk and leaves the image unchanged.
- A **Compose file** describes machines in Docker's Compose format. East India has no `endia run`: every machine comes from a Compose file.
- A **fleet** is the set of machines, private networks and volumes that one Compose file describes. `endia compose up` launches it and `endia compose down` removes it.
- The **desktop** is the session of `testuser`, who is signed in automatically, so the screen is live as soon as the machine is ready. The `endia desktop` commands drive it.
- A **context** is a file, `<name>.eastindiacontext`, that holds the service's address and a client certificate. A sandbox connects with one.
- A **sandbox** is a Docker sandbox on the same PC, where an AI agent runs.
- **Evidence** is what a test collects before its machines are removed: screenshots, files, logs and event-log entries.

Commands reach into a machine through two programs that every image holds: a guest service, which runs programs and copies files, and a desktop helper, which controls the screen, keyboard and mouse in `testuser`'s session.

## Before you start

To connect to the service you need three things:

1. **A context file**, `<name>.eastindiacontext`, which holds the service's address and a client certificate.
2. **Network access to the service.** From a Docker sandbox on the PC, the service is at `host.docker.internal:7443`, and the sandbox's policy must allow `localhost:7443`.
3. **The `endia` command line** for your platform; for Linux, `endia-linux-x64`.

[Connecting an agent's sandbox](/docs/get-started/sandbox/) shows how to set up all three. Then, in your environment:

```sh
endia context import pc <name>.eastindiacontext
endia context use pc
endia version     # prints the command line's and the service's versions
endia images      # lists the images you can start machines from
```

## The six steps

A test follows the same steps every time:

1. **Build an image** with the application installed, or start from an image you built earlier, such as your [tools layer](/docs/testing/images/), and copy the application in later.
2. **Start the machines** with `endia compose up --wait`.
3. **Install or start** the parts that the image does not already run.
4. **Act and check**: call the application over the network, run programs in the machine, drive its desktop.
5. **Collect evidence**: screenshots, files, logs, event-log entries.
6. **Remove the machines** with `endia compose down -v`, whether the test passed or not.

A test can also tell the developer what its fleet is for, with a purpose, and how far its work has got, with counts it reports itself; the desktop app's Home page shows both. [Purpose and progress](/docs/testing/purpose-and-progress/) shows the commands.

Give each run a project name of its own, so that runs side by side never touch each other's machines, and remove the fleet from a shell trap:

```sh
set -euo pipefail
run="mytest-$(date -u +%Y%m%d-%H%M%S)"
trap 'endia compose -p "$run" down -v' EXIT
endia compose -p "$run" up --wait --wait-timeout 900
```

Machines are named `<project>-<service>-<n>`. In that run, the first machine of the `client` service is therefore `$run-client-1`. `up` builds a service's image from its `build` section when the image is missing. `--no-build` builds nothing, so a missing image fails with `NOT_FOUND`; `--build` builds every service that has `build`, even if its image exists.

## Exit codes and errors

Every command exits with 0 on success, 1 on a failure, 125 when the command line itself was wrong (nothing was sent) and 130 after Ctrl+C. On a failure, standard error says why:

- `Error response from EastIndia: <message> (<CODE>)` means the service refused the request.
- `Cannot connect to the EastIndia service at <address>. Is the service running?` means the command could not reach the service.

`--format json` turns any listing into JSON for a program to read.

## Python and Node clients

A test written in Python can call the service through the `endia` package instead of running the command line:

```sh
pip install endia
```

```python
from endia import EastIndiaClient

with EastIndiaClient.from_env() as client:
    for machine in client.machines.list():
        print(machine)
```

`EastIndiaClient.from_env()` connects as `endia` does, trying these in order:

1. `EASTINDIA_HOST` and `EASTINDIA_CERT_PATH`, when they are set;
2. the context that `EASTINDIA_CONTEXT` names;
3. the current context, from `EASTINDIA_CONFIG` or `~/.eastindia`.

The Python package needs Python 3.10 or later. For Node 20 and later, `npm install endia` gives the same client.
