Core concepts
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.
endiais 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 builddoes. - 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 uplaunches it andendia compose downremoves 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. Theendia desktopcommands 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:
- A context file,
<name>.eastindiacontext, which holds the service's address and a client certificate. - 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 allowlocalhost:7443. - The
endiacommand line for your platform; for Linux,endia-linux-x64.
Connecting an agent's sandbox shows how to set up all three. Then, in your environment:
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:
- Build an image with the application installed, or start from an image you built earlier, such as your tools layer, and copy the application in later.
- Start the machines with
endia compose up --wait. - Install or start the parts that the image does not already run.
- Act and check: call the application over the network, run programs in the machine, drive its desktop.
- Collect evidence: screenshots, files, logs, event-log entries.
- 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 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:
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:
pip install endia
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:
EASTINDIA_HOSTandEASTINDIA_CERT_PATH, when they are set;- the context that
EASTINDIA_CONTEXTnames; - the current context, from
EASTINDIA_CONFIGor~/.eastindia.
The Python package needs Python 3.10 or later. For Node 20 and later, npm install endia gives the same client.