start action
This action can be used to start a container. At least one Exegol image is required to create and start a container and enjoy Exegol. Installing an image can be done with exegol install documentation here.
When this action is used, the following process is applied:
- if no Exegol image is installed, the user is asked to specify which one to install of build, and the process continues
- then, if the container to start doesn't already exist, it is created based on an Exegol image and a few settings to specify, and the process continues
- then, the container is started and a shell is opened
Options
A single option exist to target an Exegol container. If this container exists, it will be started if it is not already the case and a shell will be spawned to offer an interactive console to the user
| Option | Description |
|---|---|
CONTAINER | Tag used to target an Exegol container |
Many options exist to customize the creation of exegol container.
The default options of some parameters can be changed in the exegol configuration file.
Ten of the options below are switches with two spellings, a positive one and a --no- one. What you type decides one of three things:
| You type | Result |
|---|---|
--log | Forced on, whatever the profile or the config file say. |
--no-log | Forced off, whatever the profile or the config file say. |
| neither | No opinion. The value comes from the profile, then from the config file if that option has a setting there, then from Exegol's default. |
Five of the ten have no configuration-file setting at all: --gui, --my-resources, --exegol-resources, --share-timezone and --privileged. For those the profile is the only tier below the command line, and an option you do not type falls straight from the profile to Exegol's default.
That is how one container refuses a setting a shared profile turns on, without editing the profile.
Global options
| Option | Description |
|---|---|
IMAGE | Tag of the exegol image to use to create a new exegol container |
-w WORKSPACE_PATH, --workspace WORKSPACE_PATH | The specified host folder will be linked to the /workspace folder in the container. |
-cwd, --cwd-mount | This option is a shortcut to set the /workspace folder to the user's current working directory (pwd). |
-fs, --update-fs, --no-update-fs | Modifies the permissions of folders and sub-folders shared in your workspace to access the files created within the container using your host user account. (default: Disabled) |
-V VOLUMES, --volume VOLUMES | Share a new volume between host and exegol (format: --volume /path/on/host/:/path/in/container/[:ro|rw]). |
-p PORTS, --port PORTS | Share a network port between host and exegol (format: --port [<host_ipv4>:]<host_port>[-<end_host_port>][:<container_port>[-<end_container_port>]][:<protocol>]. This configuration will disable the shared network with the host. |
--hostname HOSTNAME | Set a custom hostname to the exegol container (default: exegol-<name>) |
--hosts-file HOSTS_FILE | Import custom host entries from a file (format: IP HOSTNAME) |
--gui, --no-gui | Share the host GUI (X11 or Wayland) so graphical applications can display (default: Enabled) |
--my-resources, --no-my-resources | Mount the shared resources (/opt/my-resources) from the host (~/.exegol/my-resources) (default: Enabled) |
--exegol-resources, --no-exegol-resources | Mount the exegol resources (/opt/resources) from the host (~/.exegol/exegol-resources) (default: Enabled) |
--network NETWORK | Configure the container's network mode (default: host). See Network Modes for details. |
--share-timezone, --no-share-timezone | Share the host's time and timezone configuration with exegol (default: Enabled) |
--comment | The specified comment will be added to the container info |
Privileges
By default, the Exegol container will receive the minimum permissions required by the enabled features.
Permissions will be added automatically if required. For example, when the --vpn parameter is used, devices and capabilities are automatically added to enable the VPN to operate with the least privileges possible.
| Option | Description |
|---|---|
-d DEVICES, --device DEVICES | Add host device(s) at the container creation (example: -d /dev/ttyACM0 -d /dev/bus/usb/). |
--cap CAPABILITIES | (dangerous) Capabilities allow to add specific privileges to the container (e.g. need to mount volumes, perform low-level operations on the network, etc). |
--privileged, --no-privileged | (dangerous) Give extended privileges at the container creation (e.g. needed to mount things, to use Wi-Fi or Bluetooth). --no-privileged refuses the privilege even when a container profile asks for it, a strict reduction in what a shared profile can impose (default: Disabled) |
This flag grants the container nearly unrestricted access to the host, effectively breaking most security boundaries Docker puts in place (all Linux kernel capabilities are enabled; seccomp, AppArmor and SELinux protections are disabled; the container can access all host devices; and major mounts become read-write).
New container
When a new container is created, it is possible to:
- Add the specific capabilities needed with
--cap, among the following list:NET_ADMIN,NET_BROADCAST,SYS_MODULE,SYS_PTRACE,SYS_RAWIO,SYS_ADMIN,LINUX_IMMUTABLE,MAC_ADMIN,SYSLOG.ALLis a special value that sets them all (all capabilities supported by Docker, read more). - Identify which devices are required and add specific devices with
-d/--device. - If you need "root access" (i.e., all capabilities, and access to all devices, hardware and kernel of the host) the
--privilegedoption can be used.
The privileges configured when creating the container will be given to all processes in that container for the entirety of its lifetime.
Existing container
When the container already exists, you cannot change the default privileges mode, capabilities or share new devices. However, it is possible to spawn a single shell session with all capabilities with --cap ALL. The capabilities won't be added to the container itself and will only be valid for the specific shell the flag was enabled for.
Network modes
Exegol supports different network modes to suit various use cases:
| Mode | Description | Use Case |
|---|---|---|
host (default) | Container shares the host's network interfaces (IP and MAC addresses of every interface of your host). | - When you need to use the host's network interfaces directly - For low-level network operations - When you need to share the host's IP and MAC address |
docker | Container uses Docker's default bridge network. All containers (not just Exegol) share this network and can communicate with each other. | - When you need basic network isolation - When you want to publish specific ports - For most standard use cases - When you want to allow communication between containers |
nat | ProTeamEnterprise Creates a dedicated isolated network for the container with its own subnet. Each container gets a unique network namespace with a /28 subnet (16 IP addresses), providing complete isolation from other containers. Requires Pro, Team or Enterprise license. | - When you need complete network isolation - For sensitive operations requiring dedicated network resources - When you need to control all network traffic - When you want automatic network cleanup on container removal |
disable | Disables all network connectivity for the container. | - When you need maximum isolation - For offline operations - When network access is not required |
OrbStack currently has a known limitation where containers connected to different user-defined networks can communicate with each other, bypassing expected network isolation obtained with the nat option. See the issue for more information orbstack/orbstack#1944, as of 21/05/2025, it's considered as intended and "won't fix".
There are some limitations and considerations that users should be aware of:
- Port Publishing: When using host mode, the
--portoption is not possible, and unnecessary since the container already has direct access to all host network interfaces and ports. Any service running in the container will be automatically accessible on the host's network. - Docker Desktop: On Windows and macOS systems using Docker Desktop, host mode has reduced functionality:
- Limited access to host network interfaces
- Potential performance impact
- May not work as expected with certain network tools
The network behavior can be configured in your Exegol configuration file (~/.exegol/config.yml). See the network configuration section in the configuration documentation for details about network settings.
Graphical desktop
As an alternative to sharing the host GUI with --gui, Exegol provides a complete graphical desktop environment within the container. This environment can be accessed through multiple protocols, with a web-based interface being the default method. This gives users a full-featured desktop experience directly from their browser.
| Option | Description |
|---|---|
--desktop, --no-desktop | Enable the Exegol desktop feature (default: Disabled) |
--desktop-config | Configure the desktop protocol (vnc/http) and network settings (format: protocol[:ip[:port]]) (default: http:127.0.0.1:<random>) |
VPN
An additional feature of Exegol is the managed VPN tunnel. Compatible with OpenVPN and WireGuard since Exegol image version 3.1.8.
- To configure an OpenVPN tunnel, your configuration file must have the
.ovpnextension or the directory must contain an.ovpnfile. - To configure a WireGuard VPN, your configuration file must have the
.confextension.
The container will take care of starting the tunnel at each startup.
When using the --vpn feature, network mode defaults to docker, or nat if the user has a valid Pro, Team or Enterprise subscription. This isolates the container. The VPN connection is not opened directly on the host's network interface. It protects the host.
| Option | Description |
|---|---|
--vpn VPN | Setup an OpenVPN or WireGuard connection at the container creation (examples: --vpn /home/user/openvpn/conf.ovpn, --vpn /home/user/wireguard.conf) |
--vpn-auth VPN_AUTH | Enter the credentials with a file (first line: username, second line: password) to establish the VPN connection automatically (example: --vpn-auth /home/user/openvpn/auth.txt) |
All the options seen previously are taken into account only for the creation of a new container. It is not possible to modify the configuration of an existing container. These options will be ignored if a container with the same name already exists.
Shell logging
One of the functions of exegol very useful in a professional context is the shell logging. This feature allows the user to record everything that happens in the exegol container (commands typed and responses).
| Option | Description |
|---|---|
-l, --log, --no-log | Enable shell logging (commands and outputs) on exegol to /workspace/logs/ (default: Disabled) |
--log-method | Select a shell logging method used to record the session (default: asciinema) |
--log-compress, --no-log-compress | Enable the automatic compression of log files at the end of the session (default: Enabled) |
When the -l/--log option is enabled during the creation of a new container, all future shells will be automatically logged for this container.
-l/--log is a session recorder: it captures the terminal stream of a shell, everything displayed and everything typed, and stores the recording with the container's workspace.
Exegol Sentinel is a separate Enterprise add-on that writes one structured audit event per executed command to the host for SIEM ingestion, and can additionally collect artifacts alongside those events. It journalizes the commands an operator runs interactively, and is not a process audit of the container, see Command coverage for the published boundary.
The two features are independent, and can be enabled together on the same container.
Sentinel
Exegol Sentinel is an Enterprise add-on that writes a structured audit record for every command an operator runs interactively in the container. Those records are written to a per-container directory on the Docker host, where an enterprise log agent can ingest them, which is what makes it worth enabling at the creation of a container used for an engagement. See Getting started to enable Sentinel and locate its output, and Sentinel configuration for the configuration file keys behind the three options below.
The three options below are taken into account only at the creation of a new container, and are ignored if a container with the same name already exists. -S/--sentinel turns the feature on for the container being created and --no-sentinel refuses it, in both cases whatever a container profile or the configuration file say. When neither is typed, a container profile's sentinel.enabled decides if it declares one, and the configuration file's enabled_by_default key decides otherwise. Naming an audit profile enables the feature by doing so, whatever enabled_by_default is set to, on both surfaces: -SP/--sentinel-profile on the command line, and a container profile writing sentinel.profile with sentinel.enabled omitted. The two keys can disagree inside one container profile, and there the answer is that sentinel.enabled: false beside a sentinel.profile is disabled, silently. Typed on the command line the answer is the other way round: -SP out-ranks a container profile's sentinel.enabled: false and enables the feature with no warning, and only --no-sentinel refuses it, warning when both are typed that the audit profile named with -SP is not applied.
| Option | Description |
|---|---|
-S, --sentinel, --no-sentinel | Enable Sentinel audit logging on the container being created; --no-sentinel refuses it (default: Disabled) |
-SP SENTINEL_PROFILE, --sentinel-profile SENTINEL_PROFILE | Name the Sentinel audit profile to deploy in the container; supplying it also enables Sentinel. When no profile is named, a container profile's sentinel.profile supplies one if it declares it, and the configuration file's default_profile supplies it otherwise (default: no profile is applied) |
--sentinel-strategy STRATEGY | Set the Sentinel profile update strategy for this container: on_restart regenerates the configuration from the host sources at every restart, disabled freezes it until a refresh is forced (default: on_restart) |
Container profile
Container profiles are a Pro feature and require a Professional licence or above. On a session without one, -P / --profile is refused and the command exits rather than creating the container without the requested shape.
A container profile is a named set of container-shape defaults (which image the container starts from, how it is attached to the network, what is mounted into it, which shell opens, and so on) applied to the container being created. Its declared options are applied at creation only, and anything typed on the command line wins over them. A container profile is not a Docker build profile, the kind exegol build consumes to describe how an image is built, and it is not a Sentinel audit profile, selected with -SP / --sentinel-profile above, which describes what a container's audit logging records. See Container profiles for what a profile can declare and where profiles come from.
Profile options are taken into account only at the creation of a new container. When a container with the same name already exists the profile is ignored entirely rather than partially applied, and a warning naming the profile and the container states that rule. That warning is not a prompt and it does not block: the session continues into the existing container exactly as if the option had never been typed.
| Option | Description |
|---|---|
-P CONTAINER_PROFILE, --profile CONTAINER_PROFILE | Apply a named container configuration profile to the container being created. At an interactive terminal, an empty or unknown name opens the picker listing the available profiles (default: no profile is applied) |
Session specific
The options specific to the start of the interactive session.
| Option | Description |
|---|---|
-e ENVS, --env ENVS | And an environment variable on Exegol (format: --env KEY=value). The variables configured during the creation of the container will be persistent in all shells. If the container already exists, the variable will be present only in the current shell. |
-s SHELL, --shell SHELL | Select a shell environment to launch at startup (default: zsh) |
The environment variables configured with --env ENVS during the creation of a new container will be available to all processes of the container during the entire life cycle of the container.
Command examples
# Start interactively a container
exegol start
# Create a demo container using full image
exegol start demo full
# Spawn a shell from demo container
exegol start demo
# Create a container test with a custom shared workspace
exegol start test full -w "./project/pentest/"
# Create a container test sharing the current working directory
exegol start test full -cwd
# Create a container htb with a VPN
exegol start htb full --vpn "~/vpn/lab_Dramelac.ovpn"
# Create a container app with custom volume
exegol start app full -V "/var/app/:/app/"
# Get a shell based on tmux
exegol start --shell tmux
# Share a specific hardware device (like Proxmark)
exegol start -d "/dev/ttyACM0"
# Share every USB device connected to the host
exegol start -d "/dev/bus/usb/"
# Create the htb container from the redteam profile
exegol start htb full --profile redteam
# Create a container from a profile, overriding its shell
exegol start htb full --profile redteam --shell tmux
# Refuse a setting the profile turns on
exegol start htb full --profile redteam --no-gui