TazPod Architecture

TazPod is the operator execution environment for TazLab. It is not just a convenience container: it is the runtime shell around the operator’s durable project workspace, encrypted vault, cloud login path, and AI tooling.

Runtime Contract

The runtime contract is defined by .tazpod/config.yaml and loaded from ConfigPath = .tazpod/config.yaml in cmd/tazpod/config.go.

Current verified defaults:

  • image: "tazzo/tazpod-ai:latest"
  • container_name: "tazpod-lab"
  • user: "tazpod"
  • build.dockerfile: ".tazpod/Dockerfile.ai"
  • build.context: "."
  • features.ghost_mode: true
  • features.debug: false

This means the normal local project contract is: one project directory, one .tazpod/ envelope, one operator container around it.

CLI Execution Model

The entrypoint is cmd/tazpod/main.go.

Dispatch rules that matter operationally:

  • no arguments -> smartEntry()
  • ssh and enter -> same enter() path
  • unlock, lock, save, login -> direct vault lifecycle commands
  • pull and sync -> same dispatcher family (pull())
  • push -> push() dispatcher
  • setup-storage -> S3 bucket bootstrap helper
  • __internal_sync_daemon -> background save/push daemon

The design is intentionally biased toward smartEntry() as the normal path. The other commands are lower-level controls used when the operator wants to override the default lifecycle.

Container Lifecycle

The real lifecycle logic lives in cmd/tazpod/lifecycle.go.

ensureContainerUp()

This function is the hard gate before interactive work:

  1. checks whether cfg.ContainerName already exists in Docker
  2. if it exists but is stopped, runs docker start
  3. if it does not exist, creates it with:
    • current working directory mounted into /workspace
    • host SSH directory mounted read-only into /home/tazpod/.ssh
    • HOST_CWD=<cwd> exported into the container
    • sleep infinity as the long-lived container process

The design implication is important: the container is disposable, but the workspace is not. TazPod preserves state in the mounted project directory, not in the container layer.

smartEntry()

smartEntry() is the canonical operator path:

  1. if .tazpod/ is missing, it offers initProject()
  2. ensures the container exists and is running
  3. checks whether the vault is already unlocked by testing the mountpoint at vault.MountPath
  4. if local encrypted vault exists, offers tazpod unlock
  5. if local encrypted vault is missing, offers the bootstrap sequence:
    • tazpod login
    • tazpod pull vault
    • tazpod unlock
  6. enters /workspace through docker exec -it
  7. when the shell exits, it runs lock() automatically

This is why TazPod behaves like an operational shell rather than a loose bag of commands: the default path already encodes environment recovery and secret lifecycle.

Persistence Boundaries

TazPod deliberately splits persistence into three layers:

  • project workspace persistence: the host project mounted into /workspace
  • encrypted operator persistence: .tazpod/vault/vault.tar.aes
  • volatile secret runtime: /home/tazpod/secrets on tmpfs

The .tazpod/ directory is therefore the local operational envelope of the project, not just a config folder.

See Also