turbo run

Create a new session from one or more images or start the most recent session that used the same parameters.

Usage

turbo run [options] [<image>[,<image>...]] [-- <parameters>...]

Use -- to pass parameters directly to the startup process so they are not interpreted as run flags.

Description

• You can layer images; when files, registry entries, or environment variables conflict, values from the last image win. Virtual machine settings also come from the last image.
• Modifier layers (images without startup files or auto-start services) do not serve as the entry point.
• Turbo uses cmd.exe /k when no startup file is set in the base image.
• Attach standard streams to the current shell with --attach or send them to the background with --detach.
• Your session working directory matches the host working directory unless you override it with -w or the image workdir instruction.
• Host environment variables stay visible unless isolated by the image; use -e or --env-file to add or override values for the session.

Options

Access And Identity

• --api-key=VALUE — Log in with the specified API key.
• --ad-domain-allow=VALUE / --ad-domain-deny=VALUE — Allow or deny execution from the Active Directory domain.
• --ad-group-allow=VALUE / --ad-group-deny=VALUE — Allow or deny execution for members of an Active Directory group.
• --admin — Run the session with administrative permissions.
• --all-users — Apply configuration settings to all users.

Session Lifecycle

• -a, --attach — Attach to stdin, stdout, and stderr of the session (not saved).
• -d, --detach — Run the session in the background (not saved).
• -n, --name=VALUE — Assign a session name.
• --temp — Remove the session when it exits.
• --enable-sync — Enable session synchronization (not saved).
• --stream — Enable streaming of the image when available.
• --pull / --no-pull — Pull base images from hub first, or prefer local images.
• --wait-after-error / --wait-after-exit — Leave the session open after an error or normal exit.

Startup Behavior

• --startup-file=VALUE — Override the startup file for this run (not saved).
• --startup-verb=VALUE — Override the startup verb for this run (not saved).
• --set-startup-file=VALUE — Persistently override the default startup file.
• --set-startup-verb=VALUE — Persistently override the default startup verb.
• --trigger=VALUE — Execute a named group of startup files (not saved).
• --show-window=VALUE — Control how the window appears; supported values: max, default.
• --skin-border-color=VALUE — Set the UI skin border color using a named color or hex value (for example, red, #FF0000).

Runtime And Isolation

• -i, --isolate=VALUE — Set isolation level: full, write-copy, merge, or merge-user.
• --enable=VALUE / --disable=VALUE — Enable or disable Turbo VM settings (not saved). Format: VALUE1[,VALUE2...].
• --vm=VALUE — Use the specified Turbo VM version for execution.
• --using=VALUE — Layer temporary dependency images with the highest override priority.
• --clipboard-mode=VALUE — Controls clipboard isolation. Supported values: Bidirectional, InboundOnly, OutboundOnly, Isolated.
• --clipboard-size=VALUE — Maximum clipboard size in bytes for both directions. Set to 0 for unlimited.
• --clipboard-size-inbound=VALUE — Maximum inbound clipboard size in bytes (host to session). Overrides --clipboard-size for inbound. Set to 0 for unlimited.
• --clipboard-size-outbound=VALUE — Maximum outbound clipboard size in bytes (session to host). Overrides --clipboard-size for outbound. Set to 0 for unlimited.

Environment And Files

• -e, --env=VALUE — Set an environment variable in the session (not saved). Format: key=value.
• --env-file=VALUE — Load environment variables from a line-delimited file (not saved).
• -w, --working-dir=VALUE — Set the initial working directory in the session (not saved).
• --mount=VALUE — Mount a host folder or another session folder (not saved). Format: [other-session:]SourceFolder[=TargetFolder].
• --mirror=VALUE — Mirror a directory path from another session (not saved). Format: session:path.
• --hide-drive=VALUE — Hide specified drives (not saved). Format: <*|V:|-V:>[,...].
• --hosts=VALUE — Add an entry to the virtual /etc/hosts file (not saved). Format: <redirect>:<name>.
• --link=VALUE — Add a link to another session (not saved). Format: <session>:<alias>.
• --route-add=VALUE / --route-block=VALUE — Add or block routes and protocols (not saved). Supported protocols: ip, pipe, tcp, udp.
• --route-file=VALUE — Read routing configuration from an INI file (not saved).

Networking And Proxy

• --network=VALUE — Run the session in the named network (not saved).
• --proxy-server=VALUE — Specify a proxy or Tnlr server (TLS required for Tnlr). Format: [socks5|http|https|tnlr]://proxy-address:port.
• --proxy-username=VALUE / --proxy-password=VALUE — Provide proxy credentials (not required for Tnlr). These settings are not saved in the session.
• --proxy-targets=VALUE — Set a semicolon-delimited list of proxied addresses; defaults to proxying all traffic if not set.
• --proxy-tls — Wrap the proxy connection in TLS; for use with SOCKS5-over-TLS gateways. Not saved.
• --proxy-tls-skip-verify — Skip TLS certificate verification for the proxy connection. Use only on trusted networks. Not saved.

Output And Diagnostics

• --format=VALUE — Choose output format. Supported values: json, json-stream.
• --diagnostic — Enable diagnostic logging for the session.

Examples

# Start a session from a single image
turbo run apache/apache

# Layer images; later images override conflicts
turbo run apache/apache,mysql/mysql

# Pin specific versions of multiple runtimes
turbo run microsoft/dotnet:3.5.1,microsoft/dotnet:4.0.3

# Use a temporary dependency layer for build tools
turbo run --using git/git clean

# Clone and build inside the session, then exit to discard git/git
(0x3842xd) git clone https://github.com/JodaOrg/joda-time.git C:\root
(0x3842xd) exit

# Separate Turbo flags from app arguments with --
turbo run spoonbrew/clean -- /d

# Attach or detach standard streams
turbo run -a <image>
turbo run -d <image>

# Override the startup file
turbo run --startup-file=cmd.exe oracle/jdk

# Set the working directory for the session
turbo run -w="C:\\" git/git

# Add session-only environment variables
turbo run -e=foo=bar -e=x=2 <image>

Create an env-file to add multiple variables:

foo=bar
utensil=turbo
my-var=10

Then load it when launching a session:

turbo run --env-file=env.list <image>

# Apply a colored border to a session window
turbo run --startup-file=notepad -d --skin-border-color=blue clean

Related Commands

• turbo start — Start a session from an installed container.
• turbo logs — Review diagnostic logs generated with --diagnostic.

Virtual Networks

By default, sessions run in the host network, meaning that any services exposed by a session can be accessible to the outside world just as if the application was running natively on the host. However, it is possible to run sessions in virtualized network environments by specifying a network name other than "host" with the --network flag. Running a session in virtualized network environment prevents it from exposing services to the outside world (unless --route-add flag is used appropriately) while allowing for easy communication between sessions running in the same virtualized network environment. In a virtual network, sessions can connect to each other using their names as specified with the --name flag if there was any or auto-generated from the image name otherwise.

# Launch a new session in the host network context (the default)
> turbo run --network=host <image>

# Launch two sessions in a "mynet" virtual network
> turbo run -d --network=mynet --name=web <image>
web#88e3bb0e

> turbo run -d --network=mynet myself/webbrowser http://web
webbrowser#dd73e48a

# The former will accessible by its name "web" within the network,
# and the latter by its auto-generated name: "webbrowser"

Note: When connecting, always use the session name and not the network name. After all, what should your application connect to if there were two separate sessions exposing the same services on the same virtual network if you connected by network name instead of session name?

Proxy Settings

Proxy settings allows the virtual application to route network traffic to the specified proxy server --proxy-server with --proxy-password as the proxy password (if required). You may also specify addresses using the --proxy-targets to proxy only the specified addresses within the application.

If the user omits the --proxy-server flag when executing in a Turbo Server domain while specifying --proxy-targets, the application will proxy using the built in Portal proxy in the domain using a Turbo's custom tnrl proxy protocol.

For example, turbo run firefox --proxy-targets=https://internaladdress.com will attempt to proxy any connections to internaladdr.com to the Portal domain's network. The equivalent command is turbo run firefox --proxy-server=tnrl://<PortalDomain>/tnrl --proxy-targets=http://internaladdress.com

Port Mapping

All network operations (opening/closing ports, for example) are passed through to the local machine when running in the host network context. To remap session ports to other ports on the local machine, use the --route-add flag. This flag also works when running in a virtualized network environment (by specifying the --network flag).

# Map session tcp port 8080 to local port 80
> turbo run --route-add=tcp://8080:80 <image>

# Map udp traffic on session port 8080 to local port 80
> turbo run --route-add=udp://8080:80 <image>

# Map session tcp port 80 to random port on local machine
# The random port can be later queried using the netstat command
> turbo run --route-add=tcp://80:0 <image>

The default policy of allowing sessions to bind to any port on the local machine can be changed with the --route-block flag. It isolates all services bound to session ports on specified protocols (tcp or udp). They can only be opened using the --route-add flag.

# Isolate all tcp services of a session
> turbo run --route-block=tcp <image>

# Isolate all tcp and udp services, but allow session tcp port 3486
# be bound to port 80 on local machine
> turbo run --route-block=tcp,udp --route-add=tcp://3486:80 <image>

Session-to-Session Links

If you decided to not expose any services running in a session to the public by specifying the --route-block flag and not --route-add, you may still want to be able to connect to the services in your session from another session on the same machine. Although this is best achieved by running the sessions in the same virtual network using the --network flag, session linking can be used for this purpose as well.

When creating a session with the turbo new command, you can use the --link flag to link it to any existing sessions and the new session will be able to connect to any services exposed by the linked sessions. Such connection creates a parent-child relationship where the newly created session is the parent.

With each link, an alias name must be specified. Name resolution overrides are added to the parent session so it can refer to its children by these names. Note how with session links the name that a session will use to refer to another session is defined by the former (the parent) using a parameter, instead of by the name of the session as is the case with virtual networks (the --network flag).

Session links also work between sessions running in different virtual networks.

Example

First create two sessions, each exposing web sites on private port 80, but with no services exposed outside the sessions. Run them in detached mode.

> turbo run --route-block=tcp,udp -d <image>

image#05bf1aa4

> turbo run --route-block=tcp,udp -d <image>

image#94a38820

Then create a web browser session linked to the previously created sessions.

> turbo run --link=05bf:web1 --link=94a3:web2 myself/webbrowser http://web1 http://web2

You will be able to browse websites served by the linked sessions even though they are not publically available.

Controlling Outbound Traffic

The --route-add and --route-block not only provide a way to create rules that apply to inbound network traffic with the tcp and udp protocols, but also rules that apply to outbound network traffic. For the outbound rules, the ip protocol is used. The rules can be implemented using a whitelist or a blacklist approach. It is also possible to reroute traffic from one IP address/host to another, effectively defining an IP address alias.

Routes can be defined using IPv4, IPv6 addresses, or based on hostnames. Note however that you cannot specify a host name on the right side of a --route-add mapping since the result would be ambiguous if the host name resolved to multiple IP addresses.

If your session requires several routing rules then we recommend creating a route-file. A route-file is an INI based, line-delimited text file that lists all the routing rules to add to the session. It can be added with --route-file flag.

Examples

Create a PuTTY session with all outbound access blocked except to IP address 10.0.0.34 (whitelist approach):

> turbo run --route-block=ip --route-add=ip://10.0.0.34 putty

In addition to the above, reroute all traffic to 1.1.1.1 to 10.0.0.34, making it possible to connect to host at 10.0.0.34 typing address 1.1.1.1 in PuTTY:

> turbo run --route-block=ip --route-add=ip://10.0.0.34 --route-add=ip://1.1.1.1:10.0.0.34 putty

It is also possible to use IP ranges using the CIDR notation. The following command allows PuTTY in the session to connect only to hosts in the 192.168.1.0/24 network:

> turbo run --route-block=ip --route-add=ip://192.168.1.0/24 putty

To disallow the app to connect to a set of specific IP addresses (blacklist approach), simply specify them in the --route-block flags:

> turbo run --route-block=ip://192.168.1.55 --route-block=ip://192.168.1.57  putty

When working with IPv6 addresses, it is necessary to enclose them in square brackets:

Block an IPv6 address:

> turbo run --route-block=ip://[2001:4860:4860::8888] putty

Block all IP traffic, except link local IPv6 space:

> turbo run --route-block=ip --route-add=ip://[fe80::c218:85ff:febd:5c01/64] putty

Reroute traffic to an IPv6 address to localhost:

> turbo run --route-block=ip --route-add=ip://[2001:cdba::3257:9652]:[::1] putty

To simplify working with mutliple IP addresses it is possible to use hostnames on the left side of all commands. When a hostname is specified with ip --route-add or --route-block, it is resolved to an IP address when the session starts, and the behavior is effectively the same as if the IP address was specified in place of the hostname. Additionally, all DNS resolves are intercepted and whenever a known hostname resolves to a previously unknown IP address, the IP address is added to the appropriate route table. This feature is what allows wildcard hostnames to work, since otherwise it would not be possible to infer the IP addresses of all possible subdomains.

For example, to run a Chrome session allowing only access to the turbo.net and blog.turbo.net domains, you can use the command:

> turbo run --route-block=ip --route-add=ip://turbo.net --route-add=ip://blog.turbo.net chrome https://turbo.net

Wildcards are supported in host name routing. So, for example, to unblock turbo.net and all of its subdomains, use the expression:

> turbo run --route-block=ip --route-add=ip://*.turbo.net chrome https://blog.turbo.net

Or, to run a Chrome session disallowing access to the facebook.com domain and all of its subdomains:

> turbo run --route-block=ip://*.facebook.com chrome

Another option is to use an INI based route-file which defines rules for blocking and allowing network traffic. The example below blocks all network traffic and then unblocks 192.168.198.0/24 and all turbo.net and spoon.net subdomains:

[ip-block]
*
[ip-add]
192.168.198.0/24
*.turbo.net
*.spoon.net

To create a firefox session with above route-file use this command:

turbo run --route-file=c:\turbo-rules.txt firefox https://turbo.net

If a large list of hostnames is used, such as in the turbobrowsers/block-ad-routes image, the default behavior as described above of resolving all of them to IP addresses at the start of the session would cause session startup to take too long. It can be overriden with the PreResolveHostNames=false setting in a route file, as shown below:

[settings]
PreResolveHostNames=false`
[ip-block]
adserver1.com
adserver2.com
...

Adding Custom Name Resolution Entries

All sessions use name resolution provided by the host operating system. You can add specific name resolution overrides using the --hosts flag. The syntax is similar to that of the hosts file of the operating system.

# Make name my-test-service resolve to whatever the name
# test-service-43 resolves
> turbo run --hosts=my-test-service:test-service-43 <image>

# Make name mysite.net resolve to IPv4 address 127.0.0.1 and
# name ipv6.mysite.net resolve to IPv6 address ::1
> turbo run --hosts=127.0.0.1:mysite.net --hosts=::1:ipv6.mysite.net <image>

Using Startup Triggers

Images can be created with Turbo Script that have multiple startup files. Collections of startup files can be linked together by a trigger name and executed together.

# in turbo.me file to create "test-trigger" image...
startup file ["c:\windows\system32\notepad.exe", "c:\windows\regedit.exe"]
startup file doc=[("c:\windows\system32\notepad.exe", "c:\doc\welcome.txt"), ("c:\windows\system32\notepad.exe", "c:\doc\howto.txt")]

# from command-prompt...

# launch both notepad and regedit are launched
> turbo run test-trigger

# launch welcome.txt and howto.txt in notepad
> turbo run test-trigger --trigger=doc

Folder Sharing

Turbo provides two primary methods for sharing folders between the host and sessions, or between multiple sessions: Mounting and Mirroring.

Using Mount (--mount)

The --mount option provides a one-way share, allowing a session to access files from the host or another session's sandbox. This is useful for providing access to source code, tools, or shared caches without copying them into the image. The mounted folder's content is not committed to the image nor synchronized to the Turbo Hub.

If the source folder doesn't exist, the mount option is ignored. If the target folder doesn't exist, it is created.

Mount from Host:

# Mount a host folder into the session
turbo run --mount "C:\FolderOnHostSystem=C:\FolderInSession" clean

# Mount a local Maven repository to share a cache
turbo run --mount "%USERPROFILE%\.m2=%USERPROFILE%\.m2" jdk,maven

Mount from Another Session:

It is also possible to mount a folder from another session's sandbox, which allows one session to access the files of another. This feature works reliably with both local and remote sandboxes.

For example, you can create a shared "storage" session and mount its folders into other sessions:

# Create a session to act as the shared storage
turbo new google/chrome -n=storage --remote-sandbox

# Mount the storage session's download folder into a new Chrome session
turbo new google/chrome --remote-sandbox --mount=storage:@DOWNLOADS@=@DOWNLOADS@

# Mount the same storage session's download folder into a new VS Code session
turbo new google/vscode --remote-sandbox --mount=storage:@DOWNLOADS@=@DOWNLOADS@

Using Mirror (--mirror)

The --mirror option provides real-time, bidirectional file synchronization between a session and the host, or between two running sessions. This is the recommended method for use cases that require immediate, two-way updates, such as syncing a downloads folder from a browser session with a local development environment.

The --mirror flag works with both the run and start commands and is designed to work seamlessly with remote sandboxes.

# Mirror the @DOWNLOADS@ folder from a running 'chrome' session
# into the new session's @DOWNLOADS@ folder.
turbo run --mirror=chrome:@DOWNLOADS@ my-dev-image

Isolation Settings

The isolate parameter enables different levels of visibility and access from the vm to the host environment. The full isolation setting prevents read and write to the host system and registry. This is the preferred setting if you want the vm to run like a clean, completely isolated system.

The writecopy isolation setting allows the vm to read the host file system and registry but not write to the host. This is the preferred setting if you want the vm to be able to access host applications and settings, but not alter the host in any way.

The merge isolation setting allows read and write access to the host system.

Note that the vm isolation setting does not override more restrictive isolation settings that already exist in the image. For example, if you created an image in Turbo Studio and set specific folders and keys to full isolation, those settings would be preserved even if the vm isolation is set to merge.

For applications like Gimp or Notepad++ where you want to allow the vm to edit and save files you work with to the host file system, but otherwise do not want to let the application litter the host system for example with settings stored in the file system or the registry, there is the +merge-user isolation modifier. Used as full+merge-user or write-copy+merge-user, it uses merge isolation for user folders like Desktop or Documents, but keeps the base full or write-copy isolation for the rest of the system, making sure that the host system is kept clean. The preferred mode is write-copy+merge-user.

The well-known root folders affected by the +merge-user modifier are: @DESKTOP@, @DESKTOPCOMMON@, @DOCUMENTS@, @PICTURES@, @DOWNLOADS@, @MUSIC@, @VIDEOS@, and @TEMPLATES.

As a separate convenience feature, if the startup verb is not empty, the startup file of the session is set to merge isolation, regardless of the isolation level that it would otherwise have. This way, when executing a shell operation like opening a file on the host system through a Turbo application that has host system file associations set, it is possible for the virtualized application to access and make changes to the file. The MergeStartupDir vm flag takes this feature one step further and sets the isolation level to merge for the whole parent folder of the startup file and all its subfolders except well-known root folders. For example, if the startup file was C:\myproject.proj and the flag was enabled, the folder C:\myproject-files would have merge isolation, but e.g., C:\Windows or C:\Program Files, being well-known root folders, would have isolation level unchanged.

Exit Code

When the session stops, the exit code of startup file is displayed as the process exit code. The error code will also be return as the Turbo Command's process exit code. If there was an internal Turbo error that was not the result of the virtual application, a negative error code (int32) will be returned. The following exit codes are reserved for Turbo:

public const int SuccessErrorCode = 0;

// Generic Turbo error. Missing startup files will return this code.
public const int GenericErrorCode = -1;

// Application license error
public const int DrmErrorCode = -2;

Selecting VM version

A specific VM version can be selected by using the --vm=version flag. This version will persist through subsequent launches within the same session. To unset the VM, use the --vm= flag with an empty string.

JSON Output

When --format=json option was passed this command will provide output in JSON format. It will contain either a session array with information about created session or an error object if command failed.

Auto Update

The run command checks once a day for new image releases. Specify the --pull option to force checking for the latest release. Updates are download within the specified release: turbo run firefox updates to the latest Firefox. turbo run firefox:42 updates to the Firefox within release 42, like 42.0, 42.1 42.2 etc.

Remote vs. Local Image Usage

The behavior is to prioritize locally cached images over remote, unless the update check triggers an update of the repositories image.

# Start with an empty local image cache
> turbo run firefox
Downloading image firefox:3.5 from https://turbo.net/users/mozilla
Pull complete

# If the update check has not been done for firefox repository, run will update to the latest version
> turbo run firefox
Using VM 18.7.1306 from local
Using image clean:26 from local
Upgrading image firefox to version 61.0.2
Upgrading image firefox-base to version 61.0.2
Running new session firefox#165115f7

# Remove the created session and the latest image
> turbo rm firefox
Removing session firefox#165115f7

> turbo rmi firefox:61
Image mozilla/firefox:61.0.2 was removed

# Running firefox again will use the local image with the older version because the update check has already been done in the previous run
> turbo run firefox
Using VM 18.7.1306 from local
Using image clean:26 from local
Using image firefox:3.5 from local
Running new session firefox#9afe83e2

If the user does not want to trigger the update to the latest firefox, specify the release explicitly:

> turbo run firefox:3.5
Using VM 18.7.1306 from local
Using image clean:26 from local
Using image firefox:3.5 from local
Running new session firefox:3.5#a524349c

Run In Existing Session

If the user issues a run or start command targeting an already running virtual application session, then the process will start under the existing virtual session.

# Open a command prompt, detached
> turbo run clean -d
Running new session clean#a7b31817

# Open another command prompt, using the existing session
> turbo run clean
Running existing session clean#a7b31817

The application was started inside a running session

# Exit the second command prompt window, the turbo command unblocks

Running a process in an existing session will wait until the process exits before completing the turbo command. The wait for exit does not include child processes. Often an application's startup file such as firefox or notepad++ will immediately exit when another instance of the application is running. The turbo command will immediately exit. Persisted session data will be synchronized in the original turbo session.