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 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. When you add a machine, an Install EyalSec panel opens under its row with the command already generated; later, click Install on the row to open it again. Click Copy to copy the command.

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

curl -sSL -d "secret=abcd*****wxyz" https://eyalsec.com/install.sh | bash

It tells the server which C library and architecture the host has, so the server can pick a runtime build that will load there. It then downloads the installer into a private temporary file, runs it, deletes the file, and ends with the installer's own exit status. The host needs curl to run the command.

What the command reports about the host

Along with the token, the command sends a few facts about the host: its processor (uname -m), its C library version (ldd --version), the ID, VERSION_ID and ID_LIKE lines of /etc/os-release, and the output of python3 -V. Nothing else is read. Any of them can be missing; the command still runs.

For a machine added with the build left to detection, these facts decide which build and Python version are installed (see The build is detected at install), and the machine's row shows the result as soon as the install starts. For a machine whose build you chose, they are only used to serve a compatible build when the host's C library is older than the chosen one needs.

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. The panel shows the time it stops working, and while the panel stays open it replaces the command with a fresh one shortly before then; if you click Copy on a command that has expired, it is replaced first and then copied. Once the install has started on the host, the panel stops replacing it. If you need to run the install again later, 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. How the download and the install token are protected is described on the security page.

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. Run exec $SHELL (or open a new terminal), then try: es-python

Why exec $SHELL

The command pipes the installer to bash, so it runs in a child shell, and a child shell cannot change your current terminal's PATH. The installer adds ~/.local/bin to your shell's startup files, so run exec $SHELL or open a new terminal and es-python is there.

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 for new shells: 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.

A new machine already watches network input (socket) and file reads (file); change those or switch on others in Configure (see Sources watched from the start). 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.