Startup Performance Guide (Advanced)

This guide helps power users and integrators minimize startup latency for turbo run and turbo start across a variety of environments (offline, slow networks, proxies, enterprise domains).

TL;DR

• By default, the run and start commands prefer local images, which avoids remote update checks on typical launches.
• Use explicit flags only when you need the associated network behavior (--pull, --enable-sync, --server-proxy, etc).
• Keep heavyweight network operations opt-in or time-boxed during cold-starts.

How startup time is determined

Startup typically includes these phases:

1. Resolve and compose configuration
2. Proxy/TNLR preparation (if used)
3. Image resolution and download (if required)
4. Optional remote session sync (if enabled)
5. Optional Turbo Drive operations (if required or waited on)
6. Launch

Most startup latency comes from network operations in phases 2–4.

Defaults that help

• Local-first image fetch
  • turbo run and turbo start default to using locally cached images when possible.
  • Remote checks and pulls happen only if required to resolve or when explicitly requested.
• Turbo Drive bring-up is asynchronous by default
  • Startup does not block for Turbo Drive unless you explicitly require it to be ready.
• Sync is opt-in
  • Remote session list/get/pull is performed only when you enable sync.

Common sources of delay and how to mitigate

• Credential loading/renewal when hub is offline

  • During startup when the hub is unreachable, credential operations can time out if you're either logged out or have expired credentials.
  • Mitigation: Log in with valid credentials before the hub goes offline, or use --offline flag to skip credential checks.

• Proxy/TNLR probing

  • Using a proxy or TNLR can add startup latency if probing or tunnel bring-up is required.
  • Mitigation: Configure only the minimal set of proxy targets; prefer static proxy settings when possible.

• Image downloads (first-time or updates)

  • Unavoidable if the image isn't present locally.
  • Mitigation: Pre-pull during maintenance windows; pin to specific versions for reproducible launches.

• Remote session sync (opt-in)

  • Listing/reading/pulling containers from remote storage can significantly increase startup time.
  • Mitigation: Enable sync only when necessary, or defer it until after launch if your workflow allows.

Fast-path recipes

• Fastest local launch with no remote checks

  turbo run --no-pull <image>

  Uses local-only if possible; fails if the image is missing locally.

• Prefer cached images, allow resolving only if required

  turbo run <image>

  Default behavior; avoids remote update checks unless strictly necessary to resolve.

• Explicit offline usage

  turbo run --offline <image>

  Treats the environment as offline; uses local artifacts only and skips online checks.

• Pin to a specific version (no surprise updates)

  turbo run vendor/app:1.2.3

  Prevents moving to newer releases during startup.

• Avoid remote session synchronization

  • Do not pass flags that enable sync.

Image fetch strategies

Use local cache unless you deliberately want to refresh:

• No flag (default): prefers local images; resolves remotely only if needed.
• --no-pull: local-only; fails if missing.
• --pull: always check/pull base images before running.

For reproducible environments, specify exact versions (e.g., app:1.2.3) and pre-pull with a scheduled task.

Proxy and TNLR guidance

• For general proxy use, set --proxy-server explicitly and specify --proxy-targets only for the addresses that need proxying.
• When integrating with a Turbo Server domain, providing --proxy-targets without --proxy-server may enable the built-in portal proxy (TNLR). This can add startup time while the local proxy is prepared.
• Keep the target list as small as possible to reduce probing overhead.

Examples:

# Proxy only specific intranet targets
turbo run firefox --proxy-server=https://proxy.corp:8443 --proxy-targets=https://intranet.corp;https://api.corp

# Use TNLR-based proxying (domain-integrated)
turbo run firefox --proxy-targets=https://intranet.corp

Sync behavior and impact

Sync is off by default. When enabled, run/start may:

• List/get remote containers
• Pull remote session state before launch

Enable only when you need to resume a remote session or reconcile with server state. For most cold-starts, leave it off for faster launches.

Example (only when needed):

turbo start <container-id> --enable-sync

Turbo Drive and TDriveLite

• Turbo Drive service initialization is asynchronous by default and does not block startup.
• Only the following will block startup:
  • --require-tdrive: fail if Turbo Drive is not ready
  • --wait-for-tdrive: wait until it mounts
  • --tdrive-lite=...: pre-download content before launch

Use waits only when your application requires immediate drive access. Otherwise, keep them off for faster starts.

Troubleshooting startup slowness

• Are images missing locally?
  • Pre-pull: turbo pull vendor/app[:version]
• Is the environment behind a slow/unreliable proxy?
  • Test without proxy; narrow proxy targets; ensure the proxy host is reachable.
• Are you launching by config URI?
  • Verify config endpoint latency and availability; pre-cache.
• Is sync enabled unexpectedly?
  • Remove --enable-sync from your automation; confirm your defaults and policies.
• Is the app pinned to a moving release?
  • Pin exact versions during rollout.

Quick decision guide

Goal	Suggested approach
Instant launch, no network	--no-pull and/or --offline
Prefer local cache but allow resolve if required	Default (no pull flags)
Force refresh	--pull
Avoid remote session reconciliation	Omit --enable-sync
Proxy-required environment	Use explicit --proxy-server and minimal --proxy-targets
Immediate Turbo Drive access required	Use --require-tdrive or --wait-for-tdrive only when necessary
Deterministic versions	Pin app:version and pre-pull

Examples

• Cold-start developer browser with zero network ops:

  turbo run --no-pull --offline mozilla/firefox:115.0.3

• Controlled refresh on CI once per day:

  turbo pull vendor/app:1.2.x
  turbo run vendor/app:1.2.x

• Proxy only for a specific API:

  turbo run myapp --proxy-server=https://proxy.corp:8443 --proxy-targets=https://api.corp

• Resume a known remote session only when needed:

  turbo start <container-id> --enable-sync