Skip to main content

Strategies

DbxSmith uses Strategies as provisioning blueprints. A strategy is a named configuration that determines how a box is isolated, what identity it runs under, and where its home directory lives. You choose a strategy once at creation time — it is recorded in the registry and applied automatically on every subsequent entry.

Strategy Comparison​

StrategyNetworkHome DirUserHostnamePost-Init
standardHost-BridgeHost $HOMEHost-UserHost hostnameFirst-run bootstrap + PS1 & Theme Injection
airgappedNone (post-sever)~/boxes/<name> (True tmpfs isolation)Host-UserHost hostnameFirst-run bootstrap → ip link set down interface isolation
ghostHost-Bridge~/ghostuser (ephemeral)ghostuserghost-shellghostuser creation + PS1 & Theme Injection
isolated-netDedicated NAT-Bridge~/boxes/<name> (True tmpfs isolation)Host-UserHost hostnameNAT bridge creation + PS1 & Theme Injection
ghost-airgappedNone (post-sever)~/ghostuser (ephemeral)ghostuserghost-shellghostuser creation + zero network
ghost-isolated-netDedicated NAT-Bridge~/ghostuser (ephemeral)ghostuserghost-shellghostuser creation + NAT bridge creation

Prerequisites​

Before running any strategy, DbxSmith requires:

  • Engine: distrobox and podman — if distrobox is missing, the installer will offer to set it up automatically.
  • Utilities: cksum (color hashing), base64 (init-hook payload injection), awk / grep (registry parsing and container list filtering).

standard — Host-Mirrored Daily Driver​

Scenario: You need a different OS (e.g. Alpine for testing, Ubuntu for a project) but want seamless access to all your host files, SSH keys, and your normal username.

What changes:

  • Network: Host-bridge — full internet access, host services visible inside the container.
  • Home Dir: Shared with host — $HOME is identical inside and outside.
  • User / Hostname: Your actual host username and hostname.
  • Prompt: Gains a cyan (<name>) marker prefix and a deterministic background color so you always know you're inside a box.

    [!NOTE] Dynamic background coloring requires a terminal that supports OSC 11 sequences (e.g., Kitty, XFCE Terminal, or VS Code).

dbx-smith-spin standard devbox docker.io/library/ubuntu:latest dev

airgapped — Zero-Network Vault​

Scenario: You are working with sensitive code, untrusted scripts, or private keys and need a guarantee that nothing can reach the outside network.

What changes:

  • Network: Permanently severed after first-run bootstrap. ping 8.8.8.8 returns "Network is unreachable". No bridge, no DNS, no external routing.
  • Home Dir: True tmpfs isolation. The host's /home is over-mounted with an empty tmpfs, and your custom home directory is cleanly mapped to ~/boxes/<name>. Host ~/.ssh, ~/.gnupg, and .bash_history are completely inaccessible from inside.
  • Forge & Freeze isolation: Bootstraps using the default Podman network so packages can be installed. After first-run setup completes, DbxSmith commits the container to a local "frozen" image and re-spawns it with a physical --network none flag. This ensures the container physically lacks network hardware, making the isolation impenetrable regardless of underlying rootless daemon modes.
dbx-smith-spin airgapped vault docker.io/library/alpine

ghost — Obfuscated Identity​

Scenario: You need to test scripts that behave differently based on username or hostname (e.g. permission-sensitive installers, CI scripts) without creating a real Linux user on your host.

What changes:

  • User: whoami returns ghostuser. Created permanently via a post-bootstrap podman exec routine to avoid distrobox initialization race conditions. The runtime (dbx-smith) automatically enters as this user — no manual flags needed.
  • Hostname: hostname returns ghost-shell.
  • Network: Host-bridge — full internet access.
  • Home Dir: Ephemeral ~/.ghostuser.
  • Privileges: Passwordless sudo is enabled by default via /etc/sudoers.d/dbx-smith-ghost.

[!IMPORTANT] Host Isolation: Even if you can see your host home directory in df -h, the ghostuser (UID 1001) is blocked from entering it at the filesystem level. This ensures your host files stay private even if untrusted scripts are run under the ghost identity.

dbx-smith-spin ghost tester docker.io/library/fedora

isolated-net — Dedicated NAT Sandbox​

Scenario: You are developing a service that needs its own dedicated network segment — to avoid port conflicts with other boxes or host services, or to get a reproducible private IP.

What changes:

  • Network: The container's network namespace is unshared from the host (--unshare-netns) and attached to a dedicated Podman NAT bridge (dbx-net-<name>). Outbound internet works via NAT; the container is off the host's default bridge.
  • Home Dir: True tmpfs isolation. The host's /home is over-mounted with an empty tmpfs, and your custom home directory is cleanly mapped to ~/boxes/<name>. Host ~/.ssh, ~/.gnupg, and .bash_history are completely inaccessible from inside.
  • Bridge lifecycle: The dbx-net-<name> network persists until dbx-smith-rm is explicitly run.
dbx-smith-spin isolated-net microservice docker.io/library/debian

Hybrid Ghost Strategies​

Scenario: You need the identity obfuscation of ghost, but also require strict network or home directory isolation.

ghost-airgapped​

Combines the ghostuser identity with a zero-network vault. Uses true tmpfs home isolation so the host's home is invisible, and creates an ephemeral /home/ghostuser for the session.

dbx-smith-spin ghost-airgapped secret_test alpine:latest

ghost-isolated-net​

Combines the ghostuser identity with a dedicated NAT bridge. Like ghost-airgapped, uses true tmpfs home isolation to prevent host dotfile leaks.

dbx-smith-spin ghost-isolated-net isolated_tester ubuntu:latest

Modular Strategy Design​

Since v1.3.1, DbxSmith uses a Modular Factory Pattern for all strategies. Each strategy is defined as a standalone script in src/strategies/.

This design provides:

  • Zero Regression: Changes to the airgapped logic are physically isolated from the standard strategy.
  • Extensibility: Adding a custom isolation strategy is as simple as dropping a new .sh file into the strategies directory.
  • Dependency Injection: Strategies dynamically receive distribution-specific configurations (like package manager commands) based on the target image.

Technical Deep-Dives​

DbxSmith relies on several advanced, low-level Linux and containerization techniques to guarantee absolute sandbox isolation and cross-distribution resiliency:

  • The Eclipse Hack: Dynamically over-mounting an empty RAM-backed tmpfs directly on top of the container's /home mount. This completely eclipses host home directory visibility while preserving Distrobox's strict bootstrapping process.
  • The Phoenix Cycle: A robust, two-phase provisioning workflow (spin $\rightarrow$ commit $\rightarrow$ re-create) that guarantees an airgapped container is physically spawned with zero network hardware (--network none) after package installation.
  • Dynamic PAM & Hook Injections: Automating shell configurations (precmd and PROMPT_COMMAND), bypassing unprivileged rootless namespace drops for unmapped UIDs (such as shadow file capability workarounds), and silencing Zsh interactive user-wizards automatically.

For a full, detailed breakdown of these architectural workarounds, sequence diagrams, and codebase internals, please refer to the engineering guides: