stakpak Documentation

The INFRA.md file serves as the source of truth for your infrastructure documentation. It is generated or updated by running stakpak init.

File Structure and Content

The file uses a structured format to ensure high scannability for engineers:

• Tables: Used for structured data like Kubernetes clusters, Application stacks, Running services, and Managed data services.
• Bullet Lists: Used for general descriptions and service dependencies.
• Status Markers:
  • [?]: Unconfirmed items that need further investigation.
  • [!]: Potential issues or outdated/inferred information.

Key Sections

• Cloud Providers: Accounts, regions, and key services.
• Kubernetes Clusters: Details on provider, region, version, namespaces, and GitOps tools.
• Infrastructure as Code: Tools (e.g., Terraform), backends, and key modules.
• Application Stack & Running Services: Mapping of components to technologies and their runtime locations.
• Networking, Monitoring, and Secrets: Overview of DNS, observability tools, and secrets management patterns.

Security Note: INFRA.md must never include secrets, tokens, passwords, or private key material.

# Infrastructure Overview

> Auto-generated by `stakpak init` on {date}. Verified by {user/auto}.
> Last updated: {date}

## Cloud Providers

### {Provider Name}
- **Accounts**: ...
- **Regions**: ...
- **Key Services**: ...

## Kubernetes Clusters

| Cluster | Provider | Region | Version | Namespaces | GitOps |
|---------|----------|--------|---------|------------|--------|
| ...     | ...      | ...    | ...     | ...        | ...    |

... (other sections) ...

*This file is maintained by Stakpak. Run `stakpak init` to refresh.*

The Application Discovery process is a two-phase approach designed to map infrastructure to the applications they serve. The agent follows these phases:

1. Phase 1: Automated Discovery (Breadth First): Rapidly enumerate all existing infrastructure and assets. The goal is to build a wide map without getting stuck in deep analysis.
2. Phase 2: Targeted Deep Analysis (Depth Second): Once targets are confirmed from Phase 1, perform deep-dives into specific applications to understand their dependencies, build processes, and health checks.

Key Mental Model: Apps as the Unit of Understanding Instead of cataloging infrastructure in isolation (e.g., "listing databases"), the agent focuses on the application context (e.g., "which app uses this database?"). Every finding should be framed around the operational needs of an application: how to build it, run it, monitor its health, and ship new versions.

The remote installation process is split into two distinct layers to maintain provider neutrality:

1. Target Adapter (Vendor-specific): Responsible for finding or provisioning a reachable Linux host and collecting SSH connection details (e.g., AWS, GCP, Azure, or Plain SSH).
2. Bootstrap Script (Provider-neutral): A generic Linux script that performs the actual installation and configuration of Stakpak Autopilot once a target is identified.

Normalized Adapter Output: Every target adapter must return a standardized set of connection details to ensure the bootstrap script can execute regardless of the source:

ssh_target=<user>@<host>[:port]
ssh_credential_method=default-keys|private-key|password
target_user=<linux-user>
private_key_path=<optional-local-path>
password=<optional-password>
provider=<ssh|aws|gcp|azure>
source_resource_id=<optional-provider-resource-id>
public_ip=<optional-public-ip>
private_ip=<optional-private-ip>

To prevent accidental destruction of production environments, the rollback command adheres to these strict rules:

• Session Scoping: Only changes made within the current session are eligible. The agent will not touch resources that existed before the session started.
• Explicit Selection: The agent only acts on candidates discovered in Phase 1 and explicitly selected by the user in Phase 2.
• Mandatory Confirmation: Even when using /rollback all, a final confirmation step (Phase 3) is required before any destructive command is executed.
• Credential Preflight: Before any cloud reversal, the agent verifies credentials (e.g., aws sts get-caller-identity, gcloud auth list). If credentials are missing, those candidates are marked as skipped (missing credentials).
• Dry-Run Preference: For cloud providers that support it, the agent runs a --dry-run first. Only if the dry-run succeeds does it execute the real command.
• Fault Tolerance: If one reversal fails, the agent does not abort the entire batch; it records the failure and moves to the next candidate.

The agent performs automated infrastructure discovery by launching parallel subagents scoped to specific domains. This process aims to build a map of service name $\rightarrow$ runtime (e.g., EKS, ECS, Lambda, VM, Docker) $\rightarrow$ location (region/cluster) $\rightarrow$ endpoints.

Subagent Execution Rules

• Tool Selection: Use the view tool for reading local config files. Use the run_command tool for CLI discovery (e.g., kubectl, aws, gcloud).
• Sandbox Mode: When using run_command, enable sandbox mode (enable_sandbox=true) to allow autonomous execution without manual approval.
• Fallback: If Docker is unavailable, the agent falls back to non-sandboxed subagents using only the view tool (file-based discovery) and will notify the user that CLI-based discovery was skipped.
• Scope: Subagents should be narrow and focused. Prefer many small subagents over a few large ones. If a domain is large (e.g., Cloud Providers), split it into separate subagents per provider.
• Safety: All operations must be read-only. Never perform mutations, resource creation, or read/log actual secret values, tokens, passwords, or private keys.

When working with subagents, you must manage tool permissions and execution modes.

Tool Categories

• Read-only tools (Safe for research): view, search_docs, view_web_page, search_memory, load_skill, search_paks, get_pak_content.
• Mutating tools (Grant sparingly): create, str_replace, remove, run_command, run_command_task.

Sandbox Mode Behavior

• Sandboxed (enable_sandbox=true): Subagents run autonomously to completion without approval pauses. This is ideal for parallel discovery or bulk diagnostics but requires Docker and adds 5-10s startup overhead.
• Non-sandboxed (Default): The subagent pauses and waits for user approval before calling any mutating tool (run_command, create, str_replace, remove). Read-only tools never trigger a pause.

Best Practices

• Use view instead of shell commands like cat, ls, or find for faster, non-interactive exploration.
• Always use view with grep or glob arguments instead of running file exploration commands.
• Before using str_replace, always use view to confirm the target string (old_str) exists in the latest file version.

When implementing discovery subagents, strict security protocols must be followed to prevent accidental exposure of sensitive data:

Data Handling Rules

• Cloud Services: When listing managed data services (RDS, Cloud SQL, etc.), only list names, types, and regions. Never output connection strings or credentials.
• Environment Variables: When checking for .env files, note their existence only. Never read or log their contents.
• Secrets Management: When discovering tools like HashiCorp Vault, SOPS, or 1Password, only report the existence and type of the management tool. Never read, log, or output actual secret values, tokens, passwords, or private keys.
• SSH Configuration: When checking ~/.ssh/config, list host aliases only. Never read private key files.
• Cloud Configs: When reading AWS/GCP/Azure config files, only inspect the structure. Do not extract secret values.