Command Line

The Turbo command-line interface is accessible from the Windows command prompt using the turbo command.

help

To list the available commands in Turbo, execute turbo without parameters.

> turbo

To view help for a specific instruction, execute turbo help <command>.

See below for a list of all of the commands available through Turbo's command-line interface.

build

The build command is used to automate the creation of images. The build command can build images from a TurboScript or a .xappl configuration file.

Usage: turbo build <options> <path>

<options> available:
      --diagnostic           Enable diagnotic logging
  -e, --env=VALUE            Set environment variables inside the container
      --env-file=VALUE       Read in a line delimited file of ENV variables
      --format=VALUE         Use json format for output
      --mount=VALUE          Mount a host folder into the container. Format: [other-container:]SourceFolder=TargetFolder
  -n, --name=VALUE           Name of the image
      --no-base              Do not merge the base image into the new image
      --overwrite            Overwrite existing image
      --route-file=VALUE     Specify a routing rules file
      --vm=VALUE             The Turbo VM version to run the container with
      --wait-after-error     Leave program open after error
      --wait-after-exit      Leave program open after it exits

To build an image from an existing container, use the commit command.

Using TurboScript

A TurboScript is a list of instructions that Turbo will follow to create a container. After the last instruction in a script, Turbo will automatically run turbo commit on the recently created container, creating a new image.

When building from a .me script, Turbo will take the following steps:

  1. Create an empty container from all of the base images specified in the from instruction -- this is equivalent to turbo run <image>
  2. Perform the remaining instructions in the newly created container
  3. Commit the container to a new image
  4. Remove the container from the local machine

If there are any conflicts between a TurboScript instruction and a command-line flag then the TurboScript instruction will take precedence.

Using .xappl Files

A .xappl file is an XML file that contains all of the filesystem, registry, and configuration information for a given image. A .xappl file can be built using Turbo Studio.

Environment Variables

Environment variables can be added to the container through the -e or --env-file flags. These environment variables are initialized at container creation and thus may be overridden by variables created with the env instruction in the build script.

To create multiple environment variables in the container, use multiple -e flags. For example, the following command would add two environment variables, VAR1 with value 1 and VAR2 with value 2, to the built image.

> turbo build -e=VAR1=1 -e=VAR2=2 C:\TurboScript

Alternatively, use the --env-file flag and specify all of the environment variables you wish to add to the image in a line-delimited text file. For example, the previous command could be replicated using the following command:

> turbo build --env-file=C:\env-vars.txt C:\turbo.me

where env-vars.txt has the contents:

VAR1=1
VAR2=2

Note: If the --env-file and -e flags are used in the same command, the env-file flag is always processed before the -e flag. In the case of a conflict, the -e flag always takes precedence.

Other Command Line Flags

Name images using the -n flag and overwrite existing images with the same name using the --overwrite flag.

> turbo build -n=my-new-image C:\turbo.me
...
Output Image: my-new-image

# Try to build the same image second time
> turbo build -n=my-new-image C:\turbo.me
Error: The image already exists. You can overwrite with the --overwrite flag

# Try third time, with --overwrite flag
> turbo build -n=my-new-image C:\turbo.me --overwrite
...
Output Image: my-new-image

# Tags can be optionally added to the -n flag
> turbo build -n=my-new-image:1.0 C:\turbo.me
...
Output Image: my-new-image:1.0

The build command will create the intermediate container and output image using the latest version of the Turbo VM. To use a legacy version, specify the version number you wish to use with the --vm flag.

# Build the image using version 11.6.205 of the Turbo VM
> turbo build --vm=11.6.205 C:\turbo.me 

The --diagnostic flag enables logging within the intermediate container. This flag does not create diagnostic-mode images.

Merging Images

The build command will include all images, which are referenced with the from statement in the script. For example, when the script uses from spoonbrew/git, spoonbrew/nuget, then these two containers will be merged and stored into the newly built container.

The --no-base option will not merge in the script. Instead, the images are included at runtime.

JSON output

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

commit

The commit command builds an image from a container. The image is built from the container's most recent state.

Usage: commit <options> <container> <image> [--args <startup file params>]

<options> available:
      --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
  -e, --env=VALUE             Set environment variables inside the container
      --env-file=VALUE        Read in a line delimited file of ENV variables
      --format=VALUE          Use the specified format for output. Supported values: json
      --hosts=VALUE           Add an entry to the virtual /etc/hosts file (<redirect>:<name>)
      --no-base               Do not merge the base image into the new image
      --no-base-file-assocs   Do not merge the file associations from the base image into the new image
      --overwrite             Overwrite existing image
      --route-add=VALUE       Add route mapping. Supported protocols: ip, pipe, tcp, udp
      --route-block=VALUE     Block specified route or protocol. Supported protocols: ip, tcp, udp
      --route-file=VALUE      Read in a INI file of routing configuration
      --startup-file=VALUE    Override the default startup file and save it to the committed image
      --trigger=VALUE         Execute named group of startup files
      --wait-after-error      Leave process open after error
      --wait-after-exit       Leave process open after it exits

Merging Images

The commit command will merge all the base images used in the container. This behavior can be overridden with the --no-base flag.

For example, if a container were created with the command turbo run git/git,nuget/nuget and later committed with the command turbo commit <container id> my-new-image, the new image would contain:

  • Any files and registry keys created or modified in the container
  • The files and registry keys from the git/git image
  • The files and registry keys from the nuget/nuget image

However, if the same container were committed with the command turbo commit --no-base <container id> my-new-image, my-new-image would only contain the files and registry keys created or modified in the container. The git/git and nuget/nuget images are included as a dependency at runtime.

Startup File

To alter the selected startup file, apply the new value with --startup-file parameter. All parameters which are passed after the --args flag will be used as parameters to the startup file.

JSON output

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

config

The config command displays and allows modification of the current configuration settings.

Usage: turbo config <options>

<options> available:
      --container-path=VALUE       Overrides container storage to the specified path
      --debug-vm-path=VALUE        Path to debug VM
      --disable-redirector         Disable browser redirection
      --enable-redirector          Enable browser redirection
      --format=VALUE               Use the specified format for output. Supported values: json
      --hub=VALUE                  The remote hub to log into
	  --image-path=VALUE           Overrides image storage to the specified path. Supported values: full path, or "allusers" to use the system wide shared folder
      --reset                      Reset configuration to default values
      --startup-file-default=VALUE Overrides the default startup file if the main image does not have one
      --storage-path=VALUE         Path to local container and image storage
      --using=VALUE                Use specified images as temporary dependencies
      --wait-after-error           Leave process open after error
      --wait-after-exit            Leave process open after it exits

If turbo config is executed without command line parameters then the current settings are returned.

To modify any settings, specify them as command line flags and assign a value to the flag. This value will then be applied to that setting.

Change the Hub Server

The hub server that Turbo will connect to, and thus push to and pull from, can be configured with the --hub flag.

By default, Turbo is configured to connect to https://turbo.net/hub.

Change the Storage Path

The storage path points to the directory where images and containers are saved. By default, images and containers are saved in %LOCALAPPDATA%\Spoon\Containers. Use the --storage-path flag to set the storage path to a different location.

It may be more efficient to share a repository of images in multi-user environment while keeping container storage in a separate, per user location.

Use the --container-path flag to specify a new location for container storage.

Finally, the storage path can also be overwritten by the TURBOREPO environment variable which may be useful for testing an alternate location quickly without updating the client configuration.

Example
# Set container and image root path to C:\ProgramData\Spoon\Containers
> turbo config --storage-path=C:\ProgramData\Spoon\Containers

# Set the container storage path to %LOCALAPPDATA%\Spoon\Containers\sandboxes
> turbo config --container-path=%LOCALAPPDATA%\Spoon\Containers\sandboxes

> turbo config
Hub server: https://turbo.net/
Storage path: C:\ProgramData\Spoon\Containers
Container storage path: C:\Users\matt\AppData\Local\Spoon\Containers\sandboxes
Browser redirection is enabled

# Switch storage path to %LOCALAPPDATA%\Spoon\Containers\repo\images
# Keep container storage path in %LOCALAPPDATA%\Spoon\Containers\sandboxes
> SET TURBOREPO=%LOCALAPPDATA%\Spoon\Containers

# Sets the image repository storage path to C:\ProgramData\Spoon\Containers for all users
> turbo config --image-path=allusers --all-users

Resetting Config Settings

The configuration settings for Turbo can be reset to their default values by issuing the config command with the --reset flag.

JSON output

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

containers

The containers command lists all containers on the local machine.

Usage: turbo containers <options>

<options> available:
      --csv                  Print output with tab-separated columns
      --format=VALUE         Use json format for output
      --include=VALUE        Specify a column that is to be returned
  -l, --latest               List the most recently created container
  -n, --number=VALUE         List the 'n' most recently created containers
      --no-trunc             Don't truncate output

Command line flags for the containers flag serve to modify or filter the command's results.

# Only show most recently created container
> turbo containers -l

ID            Images                  Command      Created               Status
--            ------                  -------      -------               ------
db4d5baff206  spoonbrew/clean                    9/3/2014 11:26:35 AM  Stopped

# Show last 'n' created containers
> turbo containers -n=3
ID            Images                  Command      Created               Status
--            ------                  -------      -------               ------
db4d5baff206  spoonbrew/clean                      9/3/2014 11:26:35 AM  Stopped
b5c63c6d242e  nodejs/nodejs           node app.js  9/3/2014 11:25:18 AM  Running
b92981a3dd27  nodejs/nodejs           node app.js  9/3/2014 11:05:36 AM  Stopped

If the value specified for -n is greater than the number of containers present on the local machine, all of the containers are listed (same result as running turbo containers).

Formatting Results

The table that is returned by the containers command is space-formatted. If you wish to return the table with tabs between each column then use the --csv flag.

> turbo containers --csv

Data in the table returned by the containers command is truncated so that it prints nicely and is easily readable in a command prompt. If you wish to view the untruncated data in each column, use the --no-trunc flag.

> turbo containers --no-trunc

The --no-trunc flag includes additional columns in the output, Ports, Settings and VM version, as seen below.

ID                                Images       Command  Created               Status   Ports      Settings  VM version
--                                ------       -------  -------               ------   -----      --------  ----------
df6ac93f8b6147b986d4c7849c3dcef0  ghost:0.5.1           8/26/2014 3:27:17 PM  Running  8080:2368  SpawnVm   11.6.270
d6e44ae706c44ed1bd75a0830bed3239  ghost:0.5.1           8/26/2014 3:22:14 PM  Stopped             SpawnVm   11.6.270

The Ports column contains active port mappings. See the turbo netstat command for more information. The VM version contains version number of VM used to create and run container.

JSON output

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

continue

The continue command downloads the last state of a container and then starts it.

Usage: turbo continue <options> <state-id>

<options> available:
  -a, --attach               Attach to stdin, stdout, and stderr of the
                               container
      --admin                Run the container as admin user
  -d, --detach               Run the container in the background
      --diagnostic           Enable diagnotic logging
      --disable=VALUE        Disable the specified Turbo VM setting
      --disable-sync         Disable container synchronization
  -e, --env=VALUE            Set environment variables inside the container
      --enable=VALUE         Enable the specified Turbo VM setting
      --enable-sync          Enable container synchronization
      --env-file=VALUE       Read in a line delimited file of ENV variables
      --format=VALUE         Use json format for output
      --hosts=VALUE          Add an entry to the virtual /etc/hosts file
                               (<redirect>:<name>)
  -i, --isolate=VALUE        Set isolation level: full, write-copy or merge
      --link=VALUE           Add link to another container
                               (<container>:<alias>)
      --mount=VALUE          Mount a host folder into the container. Format:
                               [other-container:]SourceFolder[=TargetFolder]
      --private              Synchronize this container privately, visible
                               only to me
      --public               Synchronize this container publicly, visible to
                               everyone
      --route-add=VALUE      Add route mapping. Supported protocols: ip, pipe, tcp, udp
      --route-block=VALUE    Block specified route or protocol. Supported protocols: ip, tcp, udp
      --route-file=VALUE     Specify a routing rules file
      --startup-file=VALUE   Override the default startup file
      --startup-verb=VALUE   Override the default startup verb
      --trigger=VALUE        Execute named group of startup files
      --using=VALUE          Use selected images as a temporary dependency
      --vm=VALUE             The Turbo VM version to run the container with
      --wait-after-error     Leave program open after error
      --wait-after-exit      Leave program open after it exits
      --with-root=VALUE      Set the containers root directory

If the continue command is run against an already-running container then no action will be taken.

To enable diagnostic logging for the container, specify the --diagnostic flag.

To run the container in the background, specify the -d or --detach flag.

JSON output

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

copyi

The copyi command copies an image to another repository on your local machine. cpi is an alias for this command.

Usage: turbo copyi <options> <image> [<repository>/]<image>[:<tag>]

<options> available:
      --format=VALUE         Use json format for output
      --overwrite            Overwrite existing image
      --wait-after-error     Leave program open after error
      --wait-after-exit      Leave program open after exit

If the repository specified in the command does not already exist, a new one is automatically created.

# Copy nodejs/nodejs to a new repository
> turbo copyi nodejs/nodejs my-node

Output image: my-node

# Copy the image to the existing repository with a new tag
> turbo copyi nodejs/nodejs my-node:1.0

JSON output

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

cp

The cp command copies a files from one container to another or between a container and the native filesystem.

Usage: turbo cp [<source-container>:]<path-from> [<target-container>:]<path-to>

<options> available:
     --format=VALUE         Use json format for output

Examples:

# Copy a file from a container to the native system
> turbo cp 2de7:C:\project\file.txt C:\Users\Spoonuser

# Copy a file from a container to another container
> turbo cp 2de7:C:\project\file.txt 3vj3:C:\other-project

# Container paths must be absolute
> turbo cp 2de7:file.txt C:\Users\Spoonuser

ERROR

# Native paths are relative to the current prompt
C:\Users> turbo cp 2de7:C:\project\file.txt \Spoonuser

JSON output

When --format=json option was passed this command will provide output in JSON format. It will contain only an exit code data or an error object if command failed.

diff

The diff command shows changes made in a container's filesystem.

Usage: turbo diff <options> <container>

<options> available:
      --format=VALUE         Use json format for output
      --path=VALUE           Only show changes in subdirectories of the specified path
      --registry-path=VALUE  Only show changes in subkeys of the specified registry path
      --subsystems=VALUE     Show only diff for selected subsystems: files, registry

Changes are shown relative to the base images that the container was created from.

# Show all changes made in a container
> turbo diff <container id>

Interpreting Results

The leading character of each line denotes the type of change made at that path.

|| Character || Type of Change || || A || Added || || C || Changed || || D || Deleted ||

If a file is changed, the diff results will show the a change in the folder along with the change to the file.
For example, if one added a file to a container at C:\Users\Spoonuser\file.txt:

> turbo diff --subsystems=files <container id>

File system changes:
C C:\Users\Spoonuser
A C:\Users\Spoonuser\file.txt

Filtering Results

The diff command will show changes in the virtual filesystem and registry. To change this behavior use the --subsystems flag.

# Only show changes to the registry
> turbo diff --subsystems=registry <container id>

# Only show changse to the filesystem
> turbo diff --subsystems=files <container id>

To only show changes beneath a certain node in the filesystem or registry directory tree, use the --path or --registry-path flags.

# Only show changes in HKCU
> turbo diff --registry-path=@HKCU@ <container id>

# Only show changes in system32
> turbo diff --path=C:\Windows\system32

JSON output

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

export

The export command copies an image from the local registry to a specified path on your local machine or network.

export - Export an image from the local repository to the specified path

Usage: turbo.exe export <options> <image> <path>

<options> available:
      --format=VALUE         Use the specified format for output. Supported values: json
      --type=VALUE           Export image type. Supported values: svm, exe
      --wait-after-error     Leave process open after error
      --wait-after-exit      Leave process open after it exits

Examples:

# Export an image to the local file system
> turbo export image C:\path\to\image.svm

# Export an image to a network share
> turbo export image \\server\folder\image.svm

# Export an image to a portable exe
> turbo export --type=exe image C:\path\to\image.exe

JSON output

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

fork

The fork command creates a copy of an existing container.

Usage: turbo fork  <existing container> [<new container name>]

<options> available:
      --format=VALUE         Use the specified format for output. Supported values: json
      --images=VALUE         Use specified images for new container
      --wait-after-error     Leave process open after error
      --wait-after-exit      Leave process open after it exits

The `--images' flag replaces all images in the new container with the ones that are specified. Any images from the original container that are required in the new container would need to be specified again.

Examples:

# Create an unnamed copy of a container
> turbo fork 28c

# Create a named copy of a container
> turbo fork test-container copy-of-test-container

# Create a copy with Java & Firefox as new main images
> turbo fork chrome-container --images=oracle/jre,mozilla/firefox

JSON output

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

gc

The gc command garbage collects unused containers that have been forked. By default a container is considered unused if not run within the past 7 days.

Usage: turbo.exe gc <options>

<options> available:
      --all                  Include unforked containers for removal
      --days=VALUE           Number of days until a container is considered unused
      --format=VALUE         Use the specified format for output. Supported values: json
      --trial                Run without deleting the images

The run or subscriptions commands forks containers when the base image is automatically upgraded to a newer release. The gc command removes older version of these forked containers.

gci

The gci command garbage collects unreferenced images.

Usage: turbo.exe gci <options>

<options> available:
      --all-users            Applies command to images stored in all users folder
      --format=VALUE         Use the specified format for output. Supported values: json
      --ignore-containers    Remove images even if they are referenced by containers
      --ignore-forks         Remove images even if they are referenced by forked containers
      --trial                Run without deleting the images

Images used in containers, subscriptions, or installed images are kept in local repository cache. All other images are considered unreferenced and removed.

history

The history command lists all images used in the past.

Usage: turbo history <options> <image>

<options> available:
      --csv                  Print output with tab-separated columns
      --format=VALUE         Use json format for output
  -n=VALUE                   List the 'n' most recently used images
      --no-trunc             Don't truncate output

The most used recent images are listed first.

# List the recently used images
> turbo history

ID            Last used             Name            Tag
--            ---------             ----            ---
73dfe6973074  8/29/2014 4:51:08 PM  nodejs/nodejs      
07b66f57ed8d  8/29/2014 4:50:33 PM  git/git       

To show the history of a certain image, use turbo history image-name.

By default 50 entries are shown. Specify -n flag to show more entries.

The results of turbo history are truncated so that they are most readable in the command prompt. To prevent Turbo from truncating data, specify the --no-trunc flag.

The --csv flag can be specified to return the output as a tab-separated table.

JSON output

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

images

The images command lists all of the images present in the local registry.

Usage: turbo images <options>

<options> available:
      --csv                  Print output with tab-separated columns
      --format=VALUE         Use json format for output
      --no-trunc             Don't truncate output

The results are truncated so that they are most readable in the command prompt. To prevent Turbo from truncating data, specify the --no-trunc flag.

The --csv flag can be specified to return the output as a tab-separated table.

Examples:

# List all images in local registry
> turbo images

ID 			  Name  				  Tag	 Created 				Size
-- 			  ----  				  ---    -------    			----
7a85fe8f7ad1  chocolatey/chocolatey          8/22/2014 11:34:19 AM  3.6 MB

JSON output

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

import

The import command is used to add Turbo images or non-Turbo file types from your local machine to your local registry.

Usage: turbo import <options> <type> <path>

<options> available:
      --format=VALUE         Use json format for output
  -n, --name=VALUE           Name of the image
      --overwrite            Overwrite existing image
      --wait-after-error     Leave program open after error
      --wait-after-exit      Leave program open after exit

The type must be specified when importing external configurations into the Turbo registry.

svm           Turbo image
msi           Microsoft Software Installer
thinapp       Thinapp Configuration

You can optionally specify a name for the newly-imported image. Use the --overwrite flag to overwrite an existing image.

# Import a thinapp config
turbo import -n=my-thinapp-image thinapp C:\s\package.ini

# Import a turbo image
turbo import -n=my-svm-image svm C:\s\my-image.svm

Turbo Studio users can use this command to import their existing components.

JSON output

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

inspect

The inspect command displays contents of the image.

inspect - Inspect changes to the image

Usage: turbo inspect <options> <image>

<options> available:
      --exclude=VALUE        Show details for all subsystems, except the
                               specified ones
      --format=VALUE         Use json format for output
      --include=VALUE        Show only details for selected subsystems:
                               dependencies, files, registry, services, startu-
                               p, dns, ports, env

Examples:

# Show all details about the image
> turbo inspect my-image

# Show filesystem changes only
> turbo inspect --include=files my-image

# Show all changes, but files and registry
> turbo inspect --exclude=files,registry my-image

JSON output

When --format=json option was passed this command will provide output in JSON format. It will contain either an inspect object with all available information about image or an error object if command failed.

install

The install command creates a shortcut for the specified container in the Start Menu

Usage: turbo install <options> <container>

<options> available:
      --format=VALUE         Use the specified format for output. Supported values: json
      --register-extensions  Register file associations for installed applications

Installation integrates the container into the Windows shell by adding a Start Menu shortcut for the specified container.

Use the turbo containers --no-trunc command to see the list of installed containers.

There are two options for removing the container from the system:

  1. Use the turbo uninstall command
  2. Uninstall from "Add/Remove Programs" or "Programs and Features"

JSON output

When --format=json option was passed this command will provide output in JSON format. It will contain exit code and an error object if command failed.

installi

The installi creates Start menu shortcuts for the specified image set.

Usage: installi <options> <image> [run flags...]

<options> available:
      --all-users            Install for all users on this machine. Requires admin privilege.
      --format=VALUE         Use the specified format for output. Supported values: json
  -n, --name=VALUE           Name of installed image
      --wait-after-error     Leave process open after error
      --wait-after-exit      Leave process open after it exits

login

The login command is used to log a user into the current remote registry.

Usage: turbo login [<username> <password>]

<options> available:
     --all-users            Applies the login to all users on the machine. Requires admin privilege.
     --api-key=VALUE        Login with specified API key
     --format=VALUE         Use json format for output

API Keys

API Keys can be used to login to a user account or an organization without providing a username and password. It eliminates the need to hard code passwords or pass them in as parameters to automation scripts. API Keys are generated and revoked using user profile or organization settings at the Turbo.net website.

Examples:

# Log in by specifying username and password
> turbo login spoonuser password-here

# Without parameters, returns state of logged-in user
> turbo login

spoonuser logged in at 8/25/2014 at 5:40:45 PM

# Log in to shared user credentials
> turbo login --all-users
Login: spoonuser
Password: ********

Logged in as spoonuser

# Login in by specifying API key
> turbo login --api-key=key-here

spoonuser logged in at 8/25/2014 at 5:40:45 PM

See turbo config for information about setting your remote registry location.

JSON output

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

logout

The 'logout' command is used to log the current user out of the remote registry.

Usage: turbo logout

<options> available:
     --format=VALUE         Use json format for output
     --all-users            Logout from the shared user credentials. Requires admin privilege.

Examples:

# Logout the current user
> turbo logout

spoonuser logged out

# Logout from shared user credentials
> turbo logout --all-users

spoonuser logged out

# No action taken if a user isn't currently logged in
> turbo logout

You are not currently logged into Turbo

JSON output

When --format=json option was passed this command will provide output in JSON format. It will contain only an exitCode value or an error object if command failed.

logs

The logs command displays the logs for a container. This is especially useful for debugging or inspecting containers.

Usage: turbo logs <options> <container>

<options> available:
      --diagnostic           Show diagnostic logs
  -f                         Follow log output
      --format=VALUE         Use json format for output
      --list                 List available logs
      --pid=VALUE            Show logs for specified process (default: 0=main process of container)
  -s                         Show stream prefixes of log entries
      --stderr               Only show the stderr logs
      --stdout               Only show the stdout logs
  -t                         Show timestamps of log entries
      --tail=VALUE           Only show the last VALUE lines of each log file

Only the standard streams for a container are recorded and logged. To enable more comprehensive logging, use the --diagnostic flag of the run command when the container is created or of the start command when the container is restarted.

Previous logs are kept until the next start of a given container instance. Logs can be viewed at any time. To see available logs, use the --list flag.

# Show only stdout or stderr logs
> turbo logs --stdout 2de7fda8

> turbo logs --stderr 2de7fda8

# Show timestamps for log entries
> turbo logs -t 2de7fda8

# Show stream prefixes of log entries
> turbo logs -s 2de7fda8

# Follow log output in real-time
> turbo logs -f 2de7fda8

# Similar to Unix 'tail', only show last 5 lines
> turbo logs --tail=5 2de7fda8

# Show diagnostic logs instead of standard streams
> turbo logs --diagnostic 2de7fda8

# Show logs for specified process
> turbo logs --pid=666 2de7fda8

# List available logs
> turbo logs --list 2de7fda8

JSON output

When --format=json option was passed this command will provide output in JSON format. It can contain streamLogs and diagnosticLogs arrays if asked for list of logs, a log string if asked for specific log, or an error object if command failed.

netstat

The netstat command displays active port mappings, name resolution information, and links for the specified container.

Usage: turbo netstat <container>

<options> available:
     --format=VALUE         Use json format for output

Examples:

> turbo run --route-add=tcp://80:0 --route-add=tcp://8081:0 --hosts=localhost:lhost --link=0218:service -d <image> 63621076457c4b4fb7fff3fcbfda06b1
> turbo netstat 6362

Active port mappings:
49767:80

Name resolution overrides:
localhost lhost

Container links:
021833f5b86c4a80980eff9e5e9f39e2 as service

Note: only active port mappings are printed. Since the container in the example did not expose any service on tcp port 8081, the mapping corresponding to flag --route-add=tcp://8081:0 was not present in the output.

JSON output

When --format=json option was passed this command will provide output in JSON format. It will contain ports, dns and containerLinks arrays with information about container or an error object if command failed.

new

The new command creates new container from an image.

Usage: new <options> [<image>] [--name=<name>]

<options> available:
      --                           Parameters after -- are passed directly to the container process
  -a, --attach                     Attach to stdin, stdout, and stderr of the container
      --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 container with administrative permissions
  -d, --detach                     Run the container in the background
      --diagnostic                 Enable diagnostic logging
      --disable=VALUE              Disable the specified Turbo VM setting
  -e, --env=VALUE                  Set environment variables inside the container
      --enable=VALUE               Enable the specified Turbo VM setting
      --enable-log-stream          Enable web streaming of logs
      --enable-screencast          Enable web streaming of screenshots
      --enable-sync                Enable container synchronization
      --env-file=VALUE             Read in a line delimited file of ENV variables
      --format=VALUE               Use the specified format for output. Supported values: json
      --hosts=VALUE                Add an entry to the virtual /etc/hosts file (<redirect>:<name>)
  -i, --isolate=VALUE              Set isolation level: full, write-copy or merge
      --install                    Create shortcut for created container in Start Menu
      --link=VALUE                 Add link to another container (<container>:<alias>)
      --mount=VALUE                Mount a host folder into the container. Format: [other-container:]SourceFolder[=TargetFolder]
  -n, --name=VALUE                 Name of created container
      --network=VALUE              Run container in specified named network
      --no-pull                    Uses local images if to run the container if possible.  If not present, will pull from the hub.
      --no-run                     Create container but do not execute it
      --private                    Synchronize this container privately, visible only to me
      --public                     Synchronize this container publicly, visible to everyone
      --pull                       Pulls base images from hub before running, if they exist
      --route-add=VALUE            Add route mapping. Supported protocols: ip, pipe, tcp, udp
      --route-block=VALUE          Block specified route or protocol. Supported protocols: ip, tcp, udp
      --route-file=VALUE           Read in a INI file of routing configuration
      --startup-file=VALUE         Override the default startup file
      --startup-file-default=VALUE Overrides the default startup file if the main image does not have one
      --startup-verb=VALUE         Override the default startup verb
      --temp                       Remove container when it exits
      --trigger=VALUE              Execute named group of startup files
      --upgrade-from=VALUE         Upgrade from specified container, when images have changed
      --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 container
      --wait-after-error           Leave process open after error
      --wait-after-exit            Leave process open after it exits

Turbo 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 container with the apache/apache image
> turbo new apache/apache

# Create a container with apache and mysql
> turbo new apache/apache,mysql/mysql

# Create a container with .NET 3 and 4
> turbo new microsoft/dotnet:3.5.1,microsoft/dotnet:4.0.3

To 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 container 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 container after shutdown

Containers 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 container.

If a startup file is not set in the base image then cmd.exe /k is used.

# Default startup file is used to start container
> turbo new oracle/jdk

# Override the startup file to use the command prompt
> turbo new --startup-file=cmd.exe oracle/jdk

When 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 container 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 -- /d 

A container'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 container from the native prompt
> turbo new -d <image>

Detaching from a container will allow further work to be done in the native prompt while the container is running.

The initial working directory for the container 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 container'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:\> 

Containerized applications can be distinguished from normal apps with skin layering. Passing +skin(color) switch after image names pulls skin layer from hub. Skin layer paints colored border around all containerized application windows.

# Opens detached, containerized notepad with blue border around its window
turbo new --startup-file=notepad -d clean+skin(blue)

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 container will generate diagnostic logs that detail all of the operations that occur within the container. 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 container on the host even if executed from within the container.

Adding Environment Variables

Environment variables can be added to a container 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 container 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 container. The example file below lists 3 environment variables:

foo=bar
utensil=turbo
my-var=10

Environment variables are always expanded on the host system before they are added to the container.

> echo %PATH%

C:\Windows\system32;C:\Windows;

> turbo new -e=%PATH%;C:\Users <image>

(2fedfja3) > echo %PATH%
C:\Windows\system32;C:\Windows;C:\Users	

Virtual Networks

By default, containers run in the host network, meaning that any services exposed by a container can be accessible to the outside world just as if the application was running natively on the host. However, it is possible to run containers in virtualized network environments by specifying a network name other than "host" with the --network flag. Running a container 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 containers running in the same virtualized network environment. In a virtual network, containers 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 container in the host network context (the default)
> turbo new --network=host <image>

# Launch two containers 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 container name and not the network name. After all, what should your application connect to if there were two separate containers exposing the same services on the same virtual network if you connected by network name instead of container 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 container 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 container tcp port 8080 to local port 80
> turbo new --route-add=tcp://8080:80 <image>

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

# Map container 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 containers to bind to any port on the local machine can be changed with the --route-block flag. It isolates all services bound to container ports on specified protocols (tcp or udp). They can only be opened using the --route-add flag.

# Isolate all tcp services of a container
> turbo new --route-block=tcp <image>

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

Container-to-Container Links

If you decided to not expose any services running in a container 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 container from another container on the same machine. Although this is best achieved by running the containers in the same virtual network using the --network flag, container linking can be used for this purpose as well.

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

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

Container links also work between containers running in different virtual networks.

Example

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

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

image#05bf1aa4

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

image#94a38820

Then create a web browser container linked to the previously created containers.

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

You will be able to browse websites served by the linked containers 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 container 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 container. It can be added with --route-file flag.

Examples

Create a PuTTY container 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 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 new --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 container 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 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 new --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 new --route-block=ip://[2001:4860:4860::8888] putty

Block all IP traffic, except link local IPv6 space:

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

Reroute traffic to an IPv6 address to localhost:

> turbo new --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 container 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 container 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.net

Wildcards 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.net

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

> turbo new --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 container with above route-file use this command:

turbo new --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 container would cause container 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 containers 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=doc

Using Mount

The mount option provides a way to mount folders from the host into the container, giving access to resources from the host system. The mounted folder's content is not committed to the image nor synchronized to the Turbo Hub and therefore is not available when using the continue command. If the source folder doesn't exist, the mount option is ignored. If the target folder doesn't exist, it is created.

Example for mounting a folder.

turbo new --mount "C:\FolderOnHostSystem=C:\FolderInContainer" clean

Mounts are useful to share a cache folder, like a local Maven repository:

turbo new --mount "%USERPROFILE%\.m2=%USERPROFILE%\.m2" jdk,maven

Mounting multiple folder is done by repeating the mount parameter:

turbo new --mount "C:\Mount1=C:\InContainer1" --mount "C:\Mount2=C:\InContainer2" clean

It is also possible to mount a folder from another container:

turbo new --mount <containerid>:"C:\FolderInSourceContainer=C:\FolderInTargetContainer" clean

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 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 container 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 container 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 container array with information about created container 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.

ps

The ps command returns a list of all the processes running in containers on the local machine.

Usage: turbo ps <options> [<container>]

<options> available:
      --csv                  Print output with tab-separated columns
     --format=VALUE         Use json format for output
  -l                         Display long format
      --no-trunc             Don't truncate output

Examples:

# View all processes running in containers
> turbo ps

PID   Name     Container     User
---   ----     ---------     ----
2252  cmd.exe  f1ea9fe59eeb  Administrator

# View the "long-format" results for additional information
> turbo ps -l

PID   Name     Container     User           UTime     KTime     Command
---   ----     ---------     ----           -----     -----     -------
2252  cmd.exe  f1ea9fe59eeb  Administrator  00:01:05  00:01:10	"C:\Windows\system32\cmd.exe"

The UTime is the amount of CPU time the process spent in user-mode code.

The KTime is the amount of time spent in system calls within the kernel.

JSON output

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

pull

The pull command syncs an image from a remote registry to your local registry.

Usage: turbo pull <options> [<namespace>/]<image>[:<tag>]

<options> available:
      --format=VALUE         Use json format for output
      --wait-after-error     Leave program open after error
      --wait-after-exit      Leave program open after exit

The image to pull can be specified with up to 3 identifiers, only 1 of which (the name) is mandatory:

  • Namespace (user or org on the remote hub)
  • Name of the remote repository
  • Tag

If a namespace is not specified then it will default to that of the current user.

If a tag is not specified then the head tag is applied.

JSON output

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

push

The push command syncs an image from your local registry to the remote registry.

Usage: turbo push <options> <image> [<remote image>]

<options> available:
      --format=VALUE         Use json format for output
      --wait-after-error     Leave program open after error
      --wait-after-exit      Leave program open after exit

If the namespace is not specified then Turbo will look for a repository belonging to the current user that corresponds to the image name. If this does not exist, a new, public repository will be created and the image will be pushed there.

JSON output

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

release

The release command applies a new release to an image.

Usage: turbo release <image> <release>

<options> available:
     --format=VALUE         Use json format for output

Apply a new release to the head version of an image.

> turbo release my-image 1.0
Output image: my-image:1.0

JSON output

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

releases

The releases command returns all the available releases for an image.

Usage: turbo releases <image>

<options> available:
     --format=VALUE         Use json format for output

All the available releases are displayed.

> turbo releases my-image
All available releases of my-image:
head (local)
1.0 (local)
0.1.29

JSON output

When --format=json option was passed this command will provide output in JSON format. It will contain either releases array with list of available releases or an error object if command failed.

resume

The resume command resumes a paused container.

Usage: turbo resume <container>

<options> available:
     --format=VALUE         Use json format for output

If the container specified is not paused then no action will be taken.

JSON output

When --format=json option was passed this command will provide output in JSON format. It will contain container object with information about resumed container or an error object if command failed.

revert

The revert command is used to undo all changes to a container.

Usage: turbo revert <container>

<options> available:
     --format=VALUE         Use json format for output

Configuration settings and metadata will be maintained but all changes to the container's filesystem and registery will be reverted.

JSON output

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

rm

The rm command removes containers from the local machine.

Usage: turbo rm <options> <container>

<options> available:
  -a, --all                  Remove all containers on the local machine
     --format=VALUE         Use json format for output

Use the -a flag to remove all containers at one time. Note that this operation cannot be undone.

# Remove a single container by specifying the ID
> turbo rm f1ea9fe

Container f1ea9fefjdkaslfh324fdadfshjkl3cndkj3 has been removed

# Remove all containers on the local machine with the -a flag
> turbo rm -a

All containers have been removed

JSON output

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

rmi

The rmi command removes images from the local registry.

<options> available:
  -a, --all                  Remove all images from the local machine or all matching images if argument is specified
      --all-users            Applies command to images stored in all users folder
  -f, --force                Attempts to stop running images
      --format=VALUE         Use the specified format for output. Supported values: json

Use the -a flag to remove all images at one time. Note that this operation cannot be undone.

# Remove an image by specifying it by name
> turbo rmi my-image

Image my-image was removed

# Remove all images with the -a flag
> turbo rmi -a

All images have been removed

If the same image is forked or tagged multiple times then the rmi command will only untag the specified name, not remove the image itself.

> turbo images

ID            Name                    Tag  Created                Size
--            ----                    ---  -------                ----
7a85fe8f7ad1  chocolatey/chocolatey        8/22/2014 11:34:19 AM  3.6 MB
7a85fe8f7ad1  chocolatey-forked       1.0  8/22/2014 12:00:01 PM  3.6 MB

> turbo rmi chocolatey/chocolatey

Image chocolatey/chocolatey was untagged

> turbo images

ID            Name                Tag  Created                Size
--            ----                ---  -------                ----
7a85fe8f7ad1  chocolatey-forked   1.0  8/22/2014 12:00:01 PM  3.6 MB

> turbo rmi chocolatey-forked:1.0

Image chocolatey-forked:1.0 was removed

JSON output

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

run

The run command creates a new container from an image or starts the container with the same name and images.

Usage: run <options> [<image>][+skin(color)] [<parameters>...]

<options> available:
      --                           Parameters after -- are passed directly to the container process
  -a, --attach                     Attach to stdin, stdout, and stderr of the container
      --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 container with administrative permissions
  -d, --detach                     Run the container in the background
      --diagnostic                 Enable diagnostic logging
      --disable=VALUE              Disable the specified Turbo VM setting
  -e, --env=VALUE                  Set environment variables inside the container
      --enable=VALUE               Enable the specified Turbo VM setting
      --enable-log-stream          Enable web streaming of logs
      --enable-screencast          Enable web streaming of screenshots
      --enable-sync                Enable container synchronization
      --env-file=VALUE             Read in a line delimited file of ENV variables
      --format=VALUE               Use the specified format for output. Supported values: json
      --hosts=VALUE                Add an entry to the virtual /etc/hosts file (<redirect>:<name>)
  -i, --isolate=VALUE              Set isolation level: full, write-copy or merge
      --install                    Create shortcut for created container in Start Menu
      --link=VALUE                 Add link to another container (<container>:<alias>)
      --mount=VALUE                Mount a host folder into the container. Format: [other-container:]SourceFolder[=TargetFolder]
  -n, --name=VALUE                 Name of created container
      --network=VALUE              Run container in specified named network
      --no-pull                    Uses local images if to run the container if possible.  If not present, will pull from the hub.
      --private                    Synchronize this container privately, visible only to me
      --public                     Synchronize this container publicly, visible to everyone
      --pull                       Pulls base images from hub before running, if they exist
      --route-add=VALUE            Add route mapping. Supported protocols: ip, pipe, tcp, udp
      --route-block=VALUE          Block specified route or protocol. Supported protocols: ip, tcp, udp
      --route-file=VALUE           Read in a INI file of routing configuration
      --startup-file=VALUE         Override the default startup file
      --startup-file-default=VALUE Overrides the default startup file if the main image does not have one
      --startup-verb=VALUE         Override the default startup verb
      --temp                       Remove container when it exits
      --trigger=VALUE              Execute named group of startup files
      --upgrade-from=VALUE         Upgrade from specified container, when images have changed
      --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 container
      --wait-after-error           Leave process open after error
      --wait-after-exit            Leave process open after it exits

Turbo run 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 container with the apache/apache image
> turbo run apache/apache

# Create a container with apache and mysql
> turbo run apache/apache,mysql/mysql

# Create a container with .NET 3 and 4
> turbo run microsoft/dotnet:3.5.1,microsoft/dotnet:4.0.3

To 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 container using git temporarily to get a project
> turbo run --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 container after shutdown

Containers 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 container.

If a startup file is not set in the base image then cmd.exe /k is used.

# Default startup file is used to start container
> turbo run oracle/jdk

# Override the startup file to use the command prompt
> turbo run --startup-file=cmd.exe oracle/jdk

When 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 run command flag will be interpreted by Turbo which may lead to unexpected behavior.

# Turbo will interpret the /d flag and execute a container in detached mode
> turbo run spoonbrew/clean /d
  
# /d flag is passed to cmd.exe, disabling execution of AutoRun commands from the registry
> turbo run spoonbrew/clean -- /d 

A container'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 run -a <image>

# Detach the container from the native prompt
> turbo run -d <image>

Detaching from a container will allow further work to be done in the native prompt while the container is running.

The initial working directory for the container 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 container's working directory matches the host's working directory
C:\Users> turbo run git/git

(0x3842xd) C:\Users>

# This sets the working directory to the root of the C drive
C:\Users> turbo run -w="C:\" git/git

(0x3842xd) C:\> 

Containerized applications can be distinguished from normal apps with skin layering. Passing +skin(color) switch after image names pulls skin layer from hub. Skin layer paints colored border around all containerized application windows.

# Opens detached, containerized notepad with blue border around its window
turbo run --startup-file=notepad -d clean+skin(blue)

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 container will generate diagnostic logs that detail all of the operations that occur within the container. 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 container on the host even if executed from within the container.

Adding Environment Variables

Environment variables can be added to a container with the -e or --env-file flags.

# Add environment variable 'foo' with value 'bar'
> turbo run -e=foo=bar <image>

# Specify multiple env vars with multiple flags
> turbo run -e=foo=bar -e=x=2 <image>

If your container 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 container. The example file below lists 3 environment variables:

foo=bar
utensil=turbo
my-var=10

Environment variables are always expanded on the host system before they are added to the container.

> echo %PATH%

C:\Windows\system32;C:\Windows;

> turbo run -e=%PATH%;C:\Users <image>

(2fedfja3) > echo %PATH%
C:\Windows\system32;C:\Windows;C:\Users	

Virtual Networks

By default, containers run in the host network, meaning that any services exposed by a container can be accessible to the outside world just as if the application was running natively on the host. However, it is possible to run containers in virtualized network environments by specifying a network name other than "host" with the --network flag. Running a container 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 containers running in the same virtualized network environment. In a virtual network, containers 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 container in the host network context (the default)
> turbo run --network=host <image>

# Launch two containers 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 container name and not the network name. After all, what should your application connect to if there were two separate containers exposing the same services on the same virtual network if you connected by network name instead of container 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 container 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 container tcp port 8080 to local port 80
> turbo run --route-add=tcp://8080:80 <image>

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

# Map container 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 containers to bind to any port on the local machine can be changed with the --route-block flag. It isolates all services bound to container ports on specified protocols (tcp or udp). They can only be opened using the --route-add flag.

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

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

Container-to-Container Links

If you decided to not expose any services running in a container 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 container from another container on the same machine. Although this is best achieved by running the containers in the same virtual network using the --network flag, container linking can be used for this purpose as well.

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

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

Container links also work between containers running in different virtual networks.

Example

First create two containers, each exposing web sites on private port 80, but with no services exposed outside the containers. 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 container linked to the previously created containers.

> 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 containers 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 container 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 container. It can be added with --route-file flag.

Examples

Create a PuTTY container 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 container 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 container 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 container 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 container 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 container 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 container would cause container 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 containers 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 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 run test-trigger

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

Using Mount

The mount option provides a way to mount folders from the host into the container, giving access to resources from the host system. The mounted folder's content is not committed to the image nor synchronized to the Turbo Hub and therefore is not available when using the continue command. If the source folder doesn't exist, the mount option is ignored. If the target folder doesn't exist, it is created.

Example for mounting a folder.

turbo run --mount "C:\FolderOnHostSystem=C:\FolderInContainer" clean

Mounts are useful to share a cache folder, like a local Maven repository:

turbo run --mount "%USERPROFILE%\.m2=%USERPROFILE%\.m2" jdk,maven

Mounting multiple folder is done by repeating the mount parameter:

turbo run --mount "C:\Mount1=C:\InContainer1" --mount "C:\Mount2=C:\InContainer2" clean

It is also possible to mount a folder from another container:

turbo run --mount <containerid>:"C:\FolderInSourceContainer=C:\FolderInTargetContainer" clean

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 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 container 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 container 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 container array with information about created container 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.

When images are updated, the container is forked with the new images.

save

The save command saves specified container to the hub.

Usage: turbo.exe save <options> <container>

<options> available:
      --format=VALUE         Use the specified format for output. Supported values: json
      --wait-after-error     Leave process open after error
      --wait-after-exit      Leave process open after it exits

Use the continue command to restore the saved container.

search

The search command is used to search the remote registry for images.

Usage: turbo search <query> [<query>...]

<options> available:
     --format=VALUE         Use json format for output

Only public repositories are listed in search results.

Multiple queries can be added to make searches more specific. The search command will return the set intersection of multiple queries (AND not OR). For example, the command below will only return images with Java and Maven.

> turbo search java maven

JSON output

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

start

The start command restarts a stopped container or starts an application inside an already running container.

Usage: start <options> <container>

<options> available:
      --                           Parameters after -- are passed directly to the container process
  -a, --attach                     Attach to stdin, stdout, and stderr of the container
      --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 container with administrative permissions
  -d, --detach                     Run the container in the background
      --diagnostic                 Enable diagnostic logging
      --disable=VALUE              Disable the specified Turbo VM setting
  -e, --env=VALUE                  Set environment variables inside the container
      --enable=VALUE               Enable the specified Turbo VM setting
      --enable-log-stream          Enable web streaming of logs
      --enable-screencast          Enable web streaming of screenshots
      --enable-sync                Enable container synchronization
      --env-file=VALUE             Read in a line delimited file of ENV variables
      --format=VALUE               Use the specified format for output. Supported values: json
      --hosts=VALUE                Add an entry to the virtual /etc/hosts file (<redirect>:<name>)
  -i, --isolate=VALUE              Set isolation level: full, write-copy or merge
      --link=VALUE                 Add link to another container (<container>:<alias>)
      --mount=VALUE                Mount a host folder into the container. Format: [other-container:]SourceFolder[=TargetFolder]
      --network=VALUE              Run container in specified named network
      --no-pull                    Uses local images if to run the container if possible.  If not present, will pull from the hub.
      --private                    Synchronize this container privately, visible only to me
      --public                     Synchronize this container publicly, visible to everyone
      --pull                       Pulls base images from hub before running, if they exist
      --route-add=VALUE            Add route mapping. Supported protocols: ip, pipe, tcp, udp
      --route-block=VALUE          Block specified route or protocol. Supported protocols: ip, tcp, udp
      --route-file=VALUE           Read in a INI file of routing configuration
      --startup-file=VALUE         Override the default startup file
      --startup-file-default=VALUE Overrides the default startup file if the main image does not have one
      --startup-verb=VALUE         Override the default startup verb
      --trigger=VALUE              Execute named group of startup files
      --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 container
      --wait-after-error           Leave process open after error
      --wait-after-exit            Leave process open after it exits

If the start command is run against an already-running container then no action will be taken.

To enable diagnostic logging for the container, specify the --diagnostic flag.

To run the container in the background then specify the -d or --detach flag.

To temporarily alter the startup file, specify it with --startup-file parameter. The change overrides the original startup files and does not apply to a subsequent container starts or commits.

When the container stops, the exit code of startup file is displayed in decimal form.

JSON output

When --format=json option was passed this command will provide output in JSON format. It will contain container object with information about started container or an error object if command failed.

states

The states command lists all of the container states on the Turbo.net Hub.

Usage: turbo states <options>

<options> available:
      --csv                  Print output with tab-separated columns
      --format=VALUE         Use json format for output
  -l, --latest               List the most recently created container state
  -n, --number=VALUE         List the 'n' most recently created container states
      --no-trunc             Don't truncate output

Command line flags can be used to filter or limit the results.

# Show the last state created
> turbo states -l

Container  Created              State     Visibility
---------  -------              -----     ----------
e4b1ba0f   2014-12-01 18:48:47  2e981e1e  Public

# Show last 'n' container states that were created
> turbo states -n=3
Container  Created              State     Visibility
---------  -------              -----     ----------
e4b1ba0f   2014-12-01 18:48:47  2e981e1e  Public
cf6ba018   2014-12-01 18:34:55  5f2b7843  Public
dfc32e73   2014-12-01 18:33:35  eafa3740  Public

If the value specified for -n is greater than the number of container states present on the hub, all of the states will be listed.

Formatting Results

The table returned by the states command is space-formatted by default. Use the --csv flag to return a tab delimited table.

> turbo states --csv

Data in the table returned by the states command is truncated so that it prints nicely and is easily readable in a command prompt. Use the --no-trunc flag to view all of the data.

> turbo states --no-trunc

JSON output

When --format=json option was passed this command will provide output in JSON format. It will contain either states array with list of states available on hub or an error object if command failed.

stop

The stop command stops containers which are currently running.

Usage: turbo stop <options> <container>

<options> available:
  -a, --all                  Stop all running containers
      --format=VALUE         Use json format for output
      --wait-after-error     Leave program open after error
      --wait-after-exit      Leave program open after exit

start command accepts either a container to close or -a parameter to close all running containers.

If the stop command is run against a non-running container then no action will be taken.

JSON output

When --format=json option was passed this command will provide output in JSON format. It will contain container object with information about stopped container or an error object if command failed.

subscribe

The subscribe command is used to subscribe to a channel. A channel is a set of one or more applications.

Usage: subscribe <options> <channel>

<options> available:
      --all-users            Subscribe all users on the machine. Requires Administrator privileges
      --format=VALUE         Use the specified format for output. Supported values: json
      --wait-after-error     Leave process open after error
      --wait-after-exit      Leave process open after it exits

Subscribe All Users

When --all-users is specified, the subscription will be installed for all users on the machine. This command requires Administrator privileges and that the Turbo client is installed for all users. See the install options for the Turbo installer for more information on how to install for all users.

Automatic Updates

Subscribing to a channel creates a Winodws task that executes a daily update of the subscription. To avoid automatic updates, the subscription command has a suspend action or the scheduled task can be disabled or modified to suit the desired update process.

subscription

The subscription command is used to update, suspend, resume and print the details of a subscription.

Usage: subscription <options> [action] <name>
       sub <options> [action] <name>

<options> available:
      --format=VALUE         Use the specified format for output. Supported values: json
      --no-pull              Update the subscription without pulling images
      --wait-after-error     Leave process open after error
      --wait-after-exit      Leave process open after it exits

The available actions are update, suspend, resume and print.

Update a Subscription

The update action updates all of the images in the subscription to the latest version.

Use the --no-pull option to update the subscription without pulling new image versions, instead the images will be streamed on demand.

Suspend and Resume a Subscription

The suspend action suspends updates for the specified subscription. The resume command will resume updates.

Listing Details

The print action shows details about the subscription.

   > turbo subscription print example-channel
    Subscription example-channel for the current user
    Created 08.02.2016 17:20:23, last updated never (automatic)
    
    Name                            Repo             Status     Release   Layers
    ----                            ----             ------     -------   ------
    Mozilla Firefox & Flash Latest  mozilla/firefox  Installed  44.0      adobe/flash:20.0.0.267
    Mozilla Firefox Latest          mozilla/firefox  Installed  44.0      

subscriptions

The subscriptions command lists the subscriptions that are currently registered on the device.

Usage: subscriptions <options>
       subs <options>

<options> available:
      --format=VALUE         Use the specified format for output. Supported values: json
      --no-trunc             Don't truncate output

The subscriptions command provides some basic information about the subscriptions registered on the device including the name, last updated time and a list of applications.

For more detailed information about a specific subscription, use the subscription command.

suspend

The suspend command is used to suspend a running container.

Usage: turbo suspend <container>

<options> available:
     --format=VALUE         Use json format for output

This will suspend all processes and threads within the specified container.

JSON output

When --format=json option was passed this command will provide output in JSON format. It will contain container object with information about paused container or an error object if command failed.

try

The try command creates a new, temporary container which is removed once it is closed.

Usage: turbo.exe try <options> <image>[+skin(color)] [<parameters>...]

<options> available:
      --                           Parameters after -- are passed directly to the container process
  -a, --attach                     Attach to stdin, stdout, and stderr of the container
      --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 container with administrative permissions
  -d, --detach                     Run the container in the background
      --diagnostic                 Enable diagnostic logging
      --disable=VALUE              Disable the specified Turbo VM setting
  -e, --env=VALUE                  Set environment variables inside the container
      --enable=VALUE               Enable the specified Turbo VM setting
      --enable-log-stream          Enable web streaming of logs
      --enable-screencast          Enable web streaming of screenshots
      --enable-sync                Enable container synchronization
      --env-file=VALUE             Read in a line delimited file of ENV variables
      --format=VALUE               Use the specified format for output. Supported values: json
      --hosts=VALUE                Add an entry to the virtual /etc/hosts file (<redirect>:<name>)
  -i, --isolate=VALUE              Set isolation level: full, write-copy, merge or merge-user.
      --install                    Register the container to the desktop
      --link=VALUE                 Add link to another container (<container>:<alias>)
      --mount=VALUE                Mount a host folder into the container. Format: [other-container:]SourceFolder[=TargetFolder]
  -n, --name=VALUE                 Name of created container
      --network=VALUE              Run container in specified named network
      --no-pull                    Uses local images if to run the container if possible.  If not present, will pull from the hub.
      --private                    Synchronize this container privately, visible only to me
      --proxy-password=VALUE       Proxy password
      --proxy-server=VALUE         Proxy server. Format: [socks5|http|https]://yourproxy:port
      --proxy-username=VALUE       Proxy username
      --public                     Synchronize this container publicly, visible to everyone
      --pull                       Pulls base images from hub before running, if they exist
      --route-add=VALUE            Add route mapping. Supported protocols: ip, pipe, tcp, udp
      --route-block=VALUE          Block specified route or protocol. Supported protocols: ip, tcp, udp
      --route-file=VALUE           Read in a INI file of routing configuration
      --show-window=VALUE          Controls how window is shown. Supported values: max, default
      --startup-file=VALUE         Override the default startup file
      --startup-file-default=VALUE Overrides the default startup file if the main image does not have one
      --startup-verb=VALUE         Override the default startup verb
      --stream                     Enable streaming of the image if available
      --temp                       Remove container when it exits
      --trigger=VALUE              Execute named group of startup files
      --upgrade-from=VALUE         Upgrade from specified container, when images have changed
      --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 container
      --wait-after-error           Leave process open after error
      --wait-after-exit            Leave process open after it exits

Turbo try 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 container with the apache/apache image
> turbo try apache/apache

# Create a container with apache and mysql
> turbo try apache/apache,mysql/mysql

# Create a container with .NET 3 and 4
> turbo try microsoft/dotnet:3.5.1,microsoft/dotnet:4.0.3

Containers 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 container.

If a startup file is not set in the base image then cmd.exe /k is used.

# Default startup file is used to start container
> turbo try oracle/jdk

# Override the startup file to use the command prompt
> turbo try --startup-file=cmd.exe oracle/jdk

The initial working directory for the container 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 container's working directory matches the host's working directory
C:\Users> turbo try git/git

(0x3842xd) C:\Users>

# This sets the working directory to the root of the C drive
C:\Users> turbo try -w="C:\" git/git

(0x3842xd) C:\> 

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.

Please note that turbo.exe always runs outside of the container on the host even if executed from within the container.

Adding Environment Variables

Environment variables can be added to a container with the -e or --env-file flags.

# Add environment variable 'foo' with value 'bar'
> turbo try -e=foo=bar <image>

# Specify multiple env vars with multiple flags
> turbo try -e=foo=bar -e=x=2 <image>

If your container 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 container. The example file below lists 3 environment variables:

foo=bar
utensil=turbo
my-var=10

Environment variables are always expanded on the host system before they are added to the container.

> echo %PATH%

C:\Windows\system32;C:\Windows;

> turbo try -e=%PATH%;C:\Users <image>

(2fedfja3) > echo %PATH%
C:\Windows\system32;C:\Windows;C:\Users	

Virtual Networks

By default, containers run in the host network, meaning that any services exposed by a container can be accessible to the outside world just as if the application was running natively on the host. However, it is possible to run containers in virtualized network environments by specifying a network name other than "host" with the --network flag. Running a container 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 containers running in the same virtualized network environment. In a virtual network, containers 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 container in the host network context (the default)
> turbo try --network=host <image>

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

> turbo try -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 container name and not the network name. After all, what should your application connect to if there were two separate containers exposing the same services on the same virtual network if you connected by network name instead of container 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 container 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 container tcp port 8080 to local port 80
> turbo try --route-add=tcp://8080:80 <image>

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

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

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

# Isolate all tcp services of a container
> turbo try --route-block=tcp <image>

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

Container-to-Container Links

If you decided to not expose any services running in a container 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 container from another container on the same machine. Although this is best achieved by running the containers in the same virtual network using the --network flag, container linking can be used for this purpose as well.

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

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

Container links also work between containers running in different virtual networks.

Example

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

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

image#05bf1aa4

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

image#94a38820

Then create a web browser container linked to the previously created containers.

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

You will be able to browse websites served by the linked containers 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 container 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 container. It can be added with --route-file flag.

Examples

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

> turbo try --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 try --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 container to connect only to hosts in the 192.168.1.0/24 network:

> turbo try --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 try --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 try --route-block=ip://[2001:4860:4860::8888] putty

Block all IP traffic, except link local IPv6 space:

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

Reroute traffic to an IPv6 address to localhost:

> turbo try --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 container 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 container allowing only access to the turbo.net and blog.turbo.net domains, you can use the command:

> turbo try --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 try --route-block=ip --route-add=ip://*.turbo.net chrome https://blog.turbo.net

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

> turbo try --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 container with above route-file use this command:

turbo try --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 container would cause container 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 containers 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 try --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 try --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 try test-trigger

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

Using Mount

The mount option provides a way to mount folders from the host into the container, giving access to resources from the host system. If the source folder doesn't exist, the mount option is ignored. If the target folder doesn't exist, it is created.

Example for mounting a folder.

turbo try --mount "C:\FolderOnHostSystem=C:\FolderInContainer" clean

Mounts are useful to share a cache folder, like a local Maven repository:

turbo try --mount "%USERPROFILE%\.m2=%USERPROFILE%\.m2" jdk,maven

Mounting multiple folder is done by repeating the mount parameter:

turbo try --mount "C:\Mount1=C:\InContainer1" --mount "C:\Mount2=C:\InContainer2" clean

It is also possible to mount a folder from another container:

turbo try --mount <containerid>:"C:\FolderInSourceContainer=C:\FolderInTargetContainer" clean

Exit code

When the container 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 container array with information about created container or an error object if command failed.

Auto Update

The try 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 try firefox updates to the latest Firefox. turbo try firefox:42 updates to the Firefox within release 42, like 42.0, 42.1 42.2 etc.

uninstall

The uninstall command will remove the Start Menu shortcut for the specified container

Usage: turbo.exe uninstall <options> <container>

<options> available:
      --format=VALUE         Use json format for output

If the specified container has not been previously registered to the host device using the turbo install command, then no action will be taken.

JSON output

When --format=json option was passed this command will provide output in JSON format. It will contain exit code and an error object if command failed.

uninstalli

The uninstalli removes the Start menu shortcuts for the image and disables the update process for the images registered with installi or subscribe commands.

Usage: uninstalli <options> <image>

<options> available:
  -a, --all                  Uninstalls all images on the local machine
      --all-users            Subscriptions for all users on this machine. Requires admin privilege.
      --format=VALUE         Use the specified format for output. Supported values: json
      --wait-after-error     Leave process open after error
      --wait-after-exit      Leave process open after it exits

Uninstalling an Image that is Part of a Subscription

An image removed by uninstalli will not be updated or reinstalled during the subscription update process. However, it can be reinstalled by running the subscribe command again.

unsubscribe

The unsubscribe command unsubscribes a specified subscription or all subscriptions. It uninstalls shortcuts and removes the update task.

Usage: unsubscribe <options> <subscription>

<options> available:
  -a, --all                  Unsubscribes all subscriptions on the local machine
      --format=VALUE         Use the specified format for output. Supported values: json
      --wait-after-error     Leave process open after error
      --wait-after-exit      Leave process open after it exits

If the --all-users option was used during, the unsubscribe command will unsubscribe all users. In this case, the command needs to be run as an Administrator.

To unsubscribe from all subscriptions, use the --all option.

version

The version command shows the current version of Turbo.

Usage: turbo version

<options> available:
     --format=VALUE         Use json format for output

JSON output

When --format=json option was passed this command will provide output in JSON format. It will contain version string with current version number.

vm

The vm command displays the most recent version of the Turbo VM which is available on the local machine.

Usage: turbo vm

<options> available:
     --format=VALUE         Use json format for output

If there is a user logged in to a remote registry then this command will also display the latest version of the Turbo VM available in that registry.

> turbo vm

The latest local version of the Turbo VM is 11.6.213
The latest version of the Turbo VM is 11.6.215

JSON output

When --format=json option was passed this command will provide output in JSON format. It will contain either vms array with one tag item for local VM and one for latest VM available on hub or an error object if command failed.

vms

The vms command lists all the available versions of the Turbo VM.

Usage: turbo vms

<options> available:
     --format=VALUE         Use json format for output

If a user is logged in to a remote registry then all versions which are available both locally and remotely will be displayed.

If no user is logged in then only local versions of the Turbo VM are displayed.

JSON output

When --format=json option was passed this command will provide output in JSON format. It will contain either vms array with list of available VM versions or an error object if command failed.

Questions? Projects? Talk to us.