Install es-python on a machine

How to get an es-python machine's install command, run it on the host, what it installs and where, and what to do when an install does not finish.

Before you start

You need an es-python machine on the Machines page with its OS set, and a terminal on the host itself. You do not need root or sudo: es-python installs into your home directory.

The host needs a downloader (curl, wget or python3), a way to unpack archives (tar and gunzip, or python3), a SHA-256 tool (sha256sum, shasum, openssl or python3), mktemp, and enough free disk space for the runtime. The installer checks all of these first and tells you exactly what is missing.

For es-chromium, see Install es-chromium instead.

Get the install command

The install command is a single line you paste into a terminal on the host. Click Install on the machine's row and an Install EyalSec panel opens under that row with the command already generated; click Copy to copy it.

The command looks like this (shortened here; always copy the real one from the panel):

printf '  preparing your build on the server (this can take up to a minute)...\n'; T="$(mktemp)" && chmod 600 "$T" && { if command -v curl >/dev/null 2>&1; then curl -sSL -d "secret=abcd*****wxyz" ... 'https://eyalsec.com/install.sh' -o "$T"; elif command -v wget ...; fi; } && . "$T"; ES_RC=$?; rm -f "$T"; (exit "$ES_RC")

It downloads the installer with curl (or wget when curl is missing) into a private temporary file, runs it in your current shell, deletes the file, and ends with the installer's own exit status. On Ubuntu and Debian hosts that have neither curl nor wget, the line first installs curl when it can, or prints the one command you need to run.

The one-time token

The secret= value in the command is a one-time install token. It works once, and it expires 10 minutes after it was issued. If it expires, or you need to run the install again, click Install on the row for a fresh command.

The panel shows the token partly masked (abcd*****wxyz) so a screenshot of the page does not leak it. The Copy button always copies the complete command.

The privacy notice

The panel starts with a privacy notice: es-python may capture values from your program's memory, including secrets and personal data, when untrusted data reaches a monitored operation. Only run it on systems and data you are authorized to monitor.

Authorization

The tick box in the panel is your statement that you own or are authorized to monitor this machine, that you will not use es-python to surveil third parties, and that you are not located in or a national of an embargoed destination and not on a denied-party list. It is ticked by default, and the install command is only issued while it is ticked.

If you untick it, the command is withdrawn and the box reads "Confirm authorization above to generate the install command...". Ticking it again generates a new command. Each command you generate is recorded in your activity log as "Attested authorized use; generated install token".

Run the installer

Paste the command into a terminal on the host and press Enter. It first prints "preparing your build on the server (this can take up to a minute)..." while the server prepares the runtime for this machine, then lists each step with a green tick as it completes.

The main steps are: checking that the host matches the selected build, checking the environment, checking required tools and free disk space, downloading the runtime, verifying its integrity, extracting it, installing the es-python launcher and the eyalsec helper, adding ~/.local/bin to your PATH, and finally verifying that the runtime starts on this host.

On the dashboard, the machine's status moves from created to pending install as soon as the install starts, and to installed once the final check passes. You do not need to reload the page.

When it finishes, the installer prints:

  Done. es-python is ready in this shell. Try: es-python

es-python works straight away in the same terminal. Other terminals that were already open pick it up after you run exec $SHELL or open a new one.

If you pipe it to bash instead

The command runs the installer inside your current shell (the . "$T" part), which is what lets it put es-python on your PATH immediately. If you download the installer and pipe it to bash instead, the install still works, but it runs in a child shell, so it ends with "Run exec $SHELL (or open a new terminal), then try: es-python".

Running it with sudo

You do not need sudo, and it is better not to use it. If you do run the command with sudo, es-python is installed into the home directory of the user who ran sudo, not into root's. In a root-only shell (a container or a single-user server), it installs into root's home.

What it installs

The installer puts everything under your home directory and changes nothing system-wide. For the default version, Python 3.13, it installs:

Other Python versions install side by side: Python 3.12, for example, goes into ~/opt/eyalsec3.12/ with the launcher es-python3.12. The plain es-python command always points at the version installed most recently, and every version stays reachable by its own es-python3.X name.

The installer also adds ~/.local/bin to your PATH, both in the current shell and for future ones: in ~/.bashrc, and also in ~/.zshrc and fish's configuration if you use those shells. Each line is marked # es-python PATH so it is easy to find, and a reinstall does not add it twice.

Next, switch on the taint sources you want watched (every source is off until you do) in Configure, then run your code with es-python instead of python. See Running es-python.

Retries and reinstalling

The runtime download is large, so the installer retries on its own and resumes an interrupted download where it stopped. If an install still does not finish, click Install on the row for a fresh command and run that; the old command's token is already spent.

Clicking Install on a machine that is already installed is how you reinstall or update it. It puts the machine back to created and issues a new command; the machine keeps its name, settings and events. See Reinstall.

Troubleshooting the install

When the install cannot go ahead, the installer prints a red ✗ line saying why, and usually what to do. The machine then shows failed or stays at pending install. After fixing the cause, click Install for a fresh command.

The messages you are most likely to see:

If the terminal shows es-python: command not found after a successful install, you are in a terminal that was open before the install: run exec $SHELL or open a new one. More help is in Troubleshooting.