Appearance
new
The new command creates new session from an image.
Usage: turbo new <options> [<image>] [--name=<name>]
<options> available:
-- Parameters after -- are passed directly to the session process
-a, --attach Attach to stdin, stdout, and stderr of the session. This setting is not saved in the session.
--ad-domain-allow=VALUE Allow execution from the Active Directory domain
--ad-domain-deny=VALUE Disallow execution from the Active Directory domain
--ad-group-allow=VALUE Allow execution for members of the Active Directory group
--ad-group-deny=VALUE Disallow execution for members of the Active Directory group
--admin Run the session with administrative permissions
--all-users Applies the configuration settings to All Users
--api-key=VALUE Login with specified API key
--clipboard-mode=VALUE Controls clipboard isolation. Supported values: Bidirectional, InboundOnly, OutboundOnly, Isolated
--clipboard-size=VALUE Maximum clipboard size in bytes. Set to 0 for unlimited.
-d, --detach Run the session in the background
--diagnostic Enable diagnostic logging
--disable=VALUE Disable the specified Turbo VM setting. This setting is not saved in the session. Format: VALUE1[,VALUE2...].
-e, --env=VALUE Set an environment variable inside the session. This setting is not saved in the session.
--enable=VALUE Enable the specified Turbo VM setting. This setting is not saved in the session. Format: VALUE1[,VALUE2...].
--enable-sync Enable session synchronization. This setting is not saved in the session.
--env-file=VALUE Read in a line delimited file of environment variables. This setting is not saved in the session.
--format=VALUE Use the specified format for output. Supported values: json, json-stream
--hide-drive=VALUE Hide specified drives. This setting is not saved in the session. Format: <*|V:|-V:>[,...]
--hosts=VALUE Add an entry to the virtual /etc/hosts file (<redirect>:<name>). This setting is not saved in the session.
-i, --isolate=VALUE Set isolation level: full, write-copy, merge or merge-user.
--install Installs the session after it is created
--link=VALUE Add link to another session (<session>:<alias>). This setting is not saved in the session.
--mirror=VALUE Mirrors a directory path from another session to the current session's corresponding directory path. Format: session:path
--mount=VALUE Mount a host folder into the session. This setting is not saved in the session. Format: [other-session:]SourceFolder[=TargetFolder]
-n, --name=VALUE Name of created session
--network=VALUE Run session in specified named network. This setting is not saved in the session.
--no-pull Uses local images to run the session if possible. If not present, will pull from the hub.
--no-run Create the session without executing it
--proxy-password=VALUE Password used to connect to the proxy server. It is not required when using Tnlr. This setting is not saved in the session.
--proxy-server=VALUE Proxy or Tnlr server (Tnlr requires TLS). This setting is not saved in the session. Format: [socks5|http|https|tnlr]://proxy-address:port
--proxy-targets=VALUE A list of addresses (separated by semicolons) which will be proxied. If not set, all traffic will go through the proxy. The address could be either a DNS name or an IP address.
--proxy-username=VALUE Username used to connect to the proxy server. It is not required when using Tnlr. This setting is not saved in the session.
--pull Pulls base images from hub before running, if they exist
--route-add=VALUE Add route mapping. Supported protocols: ip, pipe, tcp, and udp. This setting is not saved in the session.
--route-block=VALUE Block specified route or protocol. Supported protocols: ip, tcp, and udp. This setting is not saved in the session.
--route-file=VALUE Read in a INI file of routing configuration. This setting is not saved in the session.
--set-startup-file=VALUE Override the default startup file permanantly
--set-startup-verb=VALUE Override the default startup verb permanantly
--show-window=VALUE Controls how window is shown. Supported values: max, default
--skin-border-color=VALUE Sets the UI skin color. Accepts color names (e.g., 'red') or hex values (e.g., '#FF0000').
--startup-file=VALUE Override the default startup file. This setting is not saved in the session.
--startup-verb=VALUE Override the default startup verb. This setting is not saved in the session.
--stream Enable streaming of the image if available
--temp Remove session when it exits
--trigger=VALUE Execute named group of startup files. This setting is not saved in the session.
--using=VALUE Use specified images as a temporary dependency
--vm=VALUE Use the specified Turbo VM version for execution
-w, --working-dir=VALUE Set the initial working directory inside the session. This setting is not saved in the session.
--wait-after-error Leave session open after error
--wait-after-exit Leave session open after it exitsTurbo new can be used to specify multiple images by separating each image with a comma. If the same file, registry entry, or environment variable exists in multiple images, then the one from whichever image was specified last will win the conflict and be used in the virtual environment. Virtual machine settings are taken from the last specified image. Due to this "layering" approach, it is a good practice to specify images with newer versions of applications or libraries after images with older versions.
# Create a session with the apache/apache image
> turbo new apache/apache
# Create a session with apache and mysql
> turbo new apache/apache,mysql/mysql
# Create a session with .NET 3 and 4
> turbo new microsoft/dotnet:3.5.1,microsoft/dotnet:4.0.3To use images temporarily, without committing them to the final image, use the --using switch. This is handy for a tool like 7zip and Git that may only needed during the build process.
# Create a session using git temporarily to get a project
> turbo new --using git/git clean
# Clone a git project
(0x3842xd) C:\> git clone https://github.com/JodaOrg/joda-time.git C:\root
# Build project...
# Exit and commit image
(0x3842xd) C:\> exit
# Git will not be part of the session after shutdownSessions are started with the startup file specified in the last passed image that is not a modifier layer. A modifier layer is an image that has no startup file or auto-start services defined. Regardless of its position on the command line, it is never used as the entry point to the session.
If a startup file is not set in the base image then cmd.exe /k is used.
# Default startup file is used to start session
> turbo new oracle/jdk
# Override the startup file to use the command prompt
> turbo new --startup-file=cmd.exe oracle/jdkWhen passing arguments to a startup file or command, we recommend separating these arguments from the rest of the command with a --. Arguments specified after the -- mark are passed directly to the startup file/command.
If a -- mark is not used, any argument matching a new command flag will be interpreted by Turbo which may lead to unexpected behavior.
# Turbo will interpret the /d flag and execute a session in detached mode
> turbo new spoonbrew/clean /d
# /d flag is passed to cmd.exe, disabling execution of AutoRun commands from the registry
> turbo new spoonbrew/clean -- /dA session's standard streams (stdin/out/err) can be redirected to either the current command prompt or the background using the --attach and --detach flags.
# Redict standard streams to current command prompt
> turbo new -a <image>
# Detach the session from the native prompt
> turbo new -d <image>Detaching from a session will allow further work to be done in the native prompt while the session is running.
The initial working directory for the session can be set with the workdir instruction or the -w flag. The current directory will be used if workdir was not specified and no --startup-file parameter was provided when building the image.
# By default, a session's working directory matches the host's working directory
C:\Users> turbo new git/git
(0x3842xd) C:\Users>
# This sets the working directory to the root of the C drive
C:\Users> turbo new -w="C:\" git/git
(0x3842xd) C:\>Sessionized applications can be distinguished from normal apps by applying a colored border. This can be done with the --skin-border-color flag. This setting accepts common color names (e.g., red, blue) or hex color codes (e.g., #FF0000).
# Opens a detached, sessionized notepad with a blue border around its window
turbo new --startup-file=notepad -d --skin-border-color=blue cleanThe legacy +skin(color) syntax is still supported but the flag is the recommended method.
Turbo VM settings can be enabled or disabled with the --enable and --disable flags, respectively. For a list of Turbo VM settings, see VM Settings section of the documentation.
When the --diagnostic flag is used, the session will generate diagnostic logs that detail all of the operations that occur within the session. These diagnostic logs can later be viewed using the turbo logs command and be used to troubleshoot errors and configuration issues.
Please note that turbo.exe always runs outside of the session on the host even if executed from within the session.
Adding Environment Variables
Environment variables can be added to a session with the -e or --env-file flags.
# Add environment variable 'foo' with value 'bar'
> turbo new -e=foo=bar <image>
# Specify multiple env vars with multiple flags
> turbo new -e=foo=bar -e=x=2 <image>If your session requires several environment variables then we recommend creating an env-file. An env-file is a line-delimited text file that lists all the environment variables to add to the session. The example file below lists 3 environment variables:
foo=bar
utensil=turbo
my-var=10Environment variables are always expanded on the host system before they are added to the session.
> echo %PATH%
C:\Windows\system32;C:\Windows;
> turbo new -e=%PATH%;C:\Users <image>
(2fedfja3) > echo %PATH%
C:\Windows\system32;C:\Windows;C:\UsersVirtual 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 new --network=host <image>
# Launch two sessions in a "mynet" virtual network
> turbo new -d --network=mynet --name=web <image>
web#88e3bb0e
> turbo new -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?
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 new --route-add=tcp://8080:80 <image>
# Map udp traffic on session port 8080 to local port 80
> turbo new --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 new --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 new --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 new --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.
Examples
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 new --route-block=tcp,udp -d <image>
image#05bf1aa4
> turbo new --route-block=tcp,udp -d <image>
image#94a38820Then create a web browser session linked to the previously created sessions.
> turbo new --link=05bf:web1 --link=94a3:web2 myself/webbrowser http://web1 http://web2You 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.
Routes cannot be used to restrict traffic to loopback addresses like 127.0.0.1.
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 new --route-block=ip --route-add=ip://10.0.0.34 puttyIn 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 new --route-block=ip --route-add=ip://10.0.0.34 --route-add=ip://1.1.1.1:10.0.0.34 puttyIt 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 new --route-block=ip --route-add=ip://192.168.1.0/24 puttyTo disallow the app to connect to a set of specific IP addresses (blacklist approach), simply specify them in the --route-block flags:
> turbo new --route-block=ip://192.168.1.55 --route-block=ip://192.168.1.57 puttyWhen working with IPv6 addresses, it is necessary to enclose them in square brackets:
Block an IPv6 address:
> turbo new --route-block=ip://[2001:4860:4860::8888] puttyBlock all IP traffic, except link local IPv6 space:
> turbo new --route-block=ip --route-add=ip://[fe80::c218:85ff:febd:5c01/64] puttyReroute traffic to an IPv6 address to localhost:
> turbo new --route-block=ip --route-add=ip://[2001:cdba::3257:9652]:[::1] puttyTo 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 new --route-block=ip --route-add=ip://turbo.net --route-add=ip://blog.turbo.net chrome https://turbo.netWildcards are supported in host name routing. So, for example, to unblock turbo.net and all of its subdomains, use the expression:
> turbo new --route-block=ip --route-add=ip://*.turbo.net chrome https://blog.turbo.netOr, to run a Chrome session disallowing access to the facebook.com domain and all of its subdomains:
> turbo new --route-block=ip://*.facebook.com chromeAnother 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.netTo create a firefox session with above route-file use this command:
turbo new --route-file=c:\turbo-rules.txt firefox https://turbo.netIf 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 new --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 new --hosts=127.0.0.1:mysite.net --hosts=::1:ipv6.mysite.net <image>Using Startup Triggers
Images can be created with TurboScript 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 new test-trigger
# launch welcome.txt and howto.txt in notepad
> turbo new test-trigger --trigger=docFolder 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 new --mount "C:\FolderOnHostSystem=C:\FolderInSession" clean
# Mount a local Maven repository to share a cache
turbo new --mount "%USERPROFILE%\.m2=%USERPROFILE%\.m2" jdk,mavenMount 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 new 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 new --mirror=chrome:@DOWNLOADS@ my-dev-imageIsolation 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 write-copy 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 full+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 in decimal form.
Selecting VM version
A specific VM version can be selected by using the --vm=version flag. If the selected version is lower than the minimum version that is required by turbo.exe, then the minimum version will be used instead.
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 new 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 new firefox updates to the latest Firefox. turbo new firefox:42 updates to the Firefox within release 42, like 42.0, 42.1 42.2 etc.