agentos-bootstrap

name	agentos-bootstrap
description	Inspect an environment and interactively establish or reconcile a persistent AgentOS First Mate in Kubernetes. Use only for first installation, a partial bootstrap, local-clone onboarding, cluster selection, or handoff from a temporary local agent to the cluster First Mate.

Bootstrap AgentOS

Treat the current local agent as a temporary seed and establish the persistent cluster First Mate before normal fleet work.

Guardrails

1. Inspect read-only first.
2. Explain observed state and viable paths.
3. Ask before credentials, login, cost, cluster creation, Akua contact, RBAC, installation, or mutation.
4. Use assets from one immutable AgentOS revision. Prefer a stable release; accept an explicitly chosen preview only as an exact Git commit plus immutable OCI digest and locally rendered manifest. Stop if a required asset is absent.
5. Never create a second First Mate to resolve ambiguous state.

Inspect

1. Determine whether the seed already runs in Kubernetes before inspecting kubeconfig:
   • check KUBERNETES_SERVICE_HOST with KUBERNETES_SERVICE_PORT or KUBERNETES_SERVICE_PORT_HTTPS;
   • check the standard ServiceAccount mount at /var/run/secrets/kubernetes.io/serviceaccount/ for token, ca.crt and namespace without printing the token;
   • read the namespace file and treat the hostname only as a weak Pod-name hint;
   • when safe tools are available, confirm with a read-only TLS-verified Kubernetes API request using the mounted CA and credential without exposing it in logs or process arguments. Multiple independent signals establish high confidence. One environment variable or a hostname alone is spoofable and only a hint; an absent ServiceAccount mount does not prove a local process because automount may be disabled. Pod name and namespace environment variables exist only when explicitly supplied, commonly through the Downward API. If strong in-cluster signals are absent, enumerate contexts with kubectl config get-contexts -o name; never change the user's global current context.
2. Present the target topologies in this order and let the developer choose:
   • a dedicated Kubernetes cluster, whether already available or created through optional Akua Zero-to-Cluster, for the strongest and simplest isolation;
   • an OSS vCluster with shared host nodes inside one explicit existing host cluster, for a separate Kubernetes API, CRDs and RBAC without separate worker infrastructure;
   • a direct installation into one explicit existing cluster, accepting its selected namespace-scoped or host cluster-admin boundary. Keep every non-Akua path complete without Akua. Explain that shared-node vCluster is API and control-plane isolation, not independent node, kernel, CNI or CSI isolation.
3. Against the selected host or target context, inspect client and server versions, StorageClasses, namespace agentos, StatefulSet, Pods, PVCs, ServiceAccount and bindings. Use kubectl auth can-i for the exact create and update permissions the selected path needs. Keep this phase read-only. For vCluster, inspect host permissions and isolation capabilities separately from the empty virtual target.
4. If an AgentOS First Mate or home PVC already exists, inspect its ownership, release image and health. Reconcile the owned installation; never create a competing First Mate.
5. Prefer the latest stable GitHub release and require a published, immutable v<semver> tag plus the fixed-name AgentOS manifest assets required by the selected path. Select only assets under /releases/download/<tag>/, never a branch manifest or a mutable latest-download URL. If no stable release fits and the developer explicitly chooses preview software, use an exact Git commit, render from that checkout and bind every First-Mate container to the same immutable @sha256: image; never install a branch snapshot or mutable tag. Verify that the manifest label identifies the selected stable or preview revision. Do not expect CNPG or PostgreSQL versions in AgentOS release metadata; the database skill discovers current compatible official releases when that path is chosen.

For a dedicated or direct existing cluster, the temporary seed needs only a compatible kubectl, the selected context's authentication and a browser for interactive provider login. It does not need an AgentOS clone, Mise, Bun, Node, Docker, Helm or PostgreSQL. The vCluster path additionally needs a reviewed vCluster CLI only after that topology is approved. Discover the current stable version and host compatibility from the official vCluster documentation, then install and invoke an exact version; do not install vCluster Platform implicitly. If a required client or external credential plugin is absent, explain what is missing and ask before installing it.

Install and hand off

1. Establish the chosen target before installing AgentOS. For vCluster, create it in a dedicated host namespace with explicit host-cluster approval, enable reviewed Pod Security, resource, and network policies supported by that host, and keep a separate explicit kubeconfig or context for its API. Verify that cluster-admin inside the vCluster cannot administer the host API. Do not claim hard isolation when workloads still share host nodes or when the host CNI cannot enforce the selected NetworkPolicy.
2. Explain the namespace-scoped agentos-firstmate.yaml and the dedicated-target agentos-firstmate-cluster-admin.yaml, including the recovery operations unavailable in scoped mode. A dedicated real cluster or isolated vCluster normally uses cluster-admin inside that target; a direct shared host installation requires a separate explicit decision. Ask for the selected RBAC and installation approval.
3. Load AgentOS Runtime. Apply the selected stable release URL or reviewed local preview manifest with kubectl --context <target-context> apply -f <source>. Never apply the AgentOS manifest through the host context when vCluster was selected.
4. Wait for the StatefulSet and verify a bound retained PVC, two successful sequential init containers, one running First Mate container, exactly one Herdr agent named firstmate, and the selected image digest on all three containers.
5. Load AgentOS Authentication. Authenticate Pi inside the persistent pod and verify a harmless real model request. When the Captain selects a concrete First-Mate model or thinking level after the initial Pi session already exists, apply it through Pi's native live interface and verify the effective live profile; writing settings.json alone prepares a future process and does not change the running session. Present personal GitHub login and the organization-owned GitHub App path separately; GitHub is optional until a selected project workflow requires it, and either path needs its own approval.
6. Replace the Pod once. Verify the same PVC identity, an Agent-home marker, exactly one First Mate pane, the same native Pi session and ordinary Mise tool resolution from a foreign worktree. If a GitHub App was selected, verify that only First Mate received its Secret mount and prove one harmless short-lived-token read after replacement.
7. Attach the developer to the persistent First Mate, hand it authority and stop the local seed from performing competing Fleet work.
8. From the cluster First Mate, load AgentOS Database. Present external PostgreSQL and self-hosted CloudNativePG without an implicit preference. After the developer chooses, use the released AgentOS database shape and apply its SQL assets as the selected Fleet-owner login; the migrations create or adopt the root First-Mate row and bind it to that same login. Do not create a separate migrator or manually map First Mate. For self-hosting, discover and verify the current compatible official CNPG and PostgreSQL releases before requesting installation approval.
9. After Fleet identity exists, present the model-capacity posture for workers and trusted harness automation. Recommend the optional Fleet AI Gateway for a delegation-ready Fleet; keep direct authentication owned separately by every Agent harness as the complete minimal alternative and recovery path. Explain the gateway's additional service, retained credential authority, selected-client Secret and NetworkPolicy boundary, and that pooled personal subscription use is experimental rather than provider-endorsed. Record the Captain's choice in Fleet-scoped Captain state. Ask separately before gateway installation, each provider login, initial client-Secret distribution and any required Pod restart unless exact standing authorization already covers the action. Verify one harmless real no-tool request from an approved worker or trusted harness automation through the selected path. If the Captain defers this step, report minimal single-Mate mode plainly and require a verified direct login before each future worker launch; do not call the Fleet delegation-ready.
10. Until the database exists, First Mate may converse with the developer, inspect read-only and finish approved provisioning, but it must not accept durable Fleet work, create Assignments or delegate another Agent. Do not use an issue tracker, transcript or local file as a temporary coordination backend.
11. Leave bootstrap mode only after runtime, First-Mate authentication, schema, current_agent_id() resolving the single active root First Mate, and every security check implemented by the selected release pass. Treat step 9's successful capacity probe as the separate boundary for claiming that the Fleet is delegation-ready.

Upgrade or remove an installation

Treat both operations as a new reconciliation: inspect first, resolve the exact installed release, image digest, database migration journal, retained PVC, persistent AgentOS checkout and active work, then explain the proposed state change. Never overwrite a dirty or divergent checkout, strand an Assignment or assume that deleting a workload also retires its durable Agent identity.

For an upgrade:

1. Resolve one newer immutable stable release and its fixed-name manifest. Read the intervening release and migration changes, verify the target image digest and inspect the server-side manifest diff. Stop when the release lacks an executable migration or compatibility path from the installed version.
2. Preserve unfinished work before changing the persistent AgentOS checkout. With approval, fetch and select the exact release tag in the clean checkout; never copy changed release files into the PVC or edit the immutable image seed.
3. Load AgentOS Database when migrations are pending. Establish the developer-selected backup or recovery boundary first, then apply only the release's ordered forward migrations in its documented compatibility order. AgentOS has no implicit down-migration or database rollback path.
4. Explain the First-Mate interruption and ask before applying the selected new manifest. Preserve the existing StatefulSet identity and home claim; never recreate the namespace or PVC as an upgrade shortcut.
5. Verify the observed target digest on every init and runtime container, the same PVC and native Pi session, the exact release checkout, Herdr attach, provider authentication, database identity and released security checks. Reapply an approved installation-specific database client patch only when inspection proves the manifest update removed it.

For removal, first present two explicit scopes:

• Stop AgentOS and retain state: remove the Mate workload and unnecessary AgentOS RBAC, including any cluster-admin binding, while retaining the namespace, home PVC, database and unfinished Git work for recovery.
• Permanently remove the Fleet: after the developer has exported or deliberately discarded every required home, database and Git artifact, remove the AgentOS namespace and its PVCs, then revoke AgentOS-specific provider credentials and external integration access.

Show the exact resources and retained data before either mutation and ask for the selected scope. Never delete an external PostgreSQL database, a shared CloudNativePG controller, shared registry, host vCluster namespace or provider repository as an AgentOS uninstall side effect. Verify that no AgentOS workload or unintended cluster-wide grant remains; report retained PVCs, database state and credentials rather than calling a state-retaining removal complete data deletion.

If bootstrap or later dogfooding needs a private image path, load AgentOS Image Builds and AgentOS Registry. Do not install a builder or registry merely because AgentOS itself is being installed from a public immutable image.

Repeat safely from the first incomplete verified boundary after interruption.