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 (in procinto di essere rimosso - progetto 30)
  • pull and sync -> same dispatcher family (pull()) (in procinto di essere rimosso - progetto 30)
  • push -> push() dispatcher (in procinto di essere rimosso - progetto 30)
  • setup-storage -> S3 bucket bootstrap helper (in procinto di essere rimosso - progetto 30)
  • __internal_sync_daemon -> background save/push daemon (in procinto di essere rimosso - progetto 30)

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. enters /workspace through docker exec -it

Persistence Boundaries

TazPod persistence relies on two layers:

  • project workspace persistence: the host project mounted into /workspace
  • gopass credential store: secrets managed via gopass with a git remote (tazlab-secrets)

See Also