agentos-bootstrap

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 a bound retained PVC, two successful sequential init containers, one running and live First Mate container, exactly one Herdr agent named firstmate, and the selected image digest on all three containers. Do not wait for StatefulSet rollout readiness yet: semantic readiness intentionally remains false until provider authentication and the post-LISTEN Fleet catch-up below exist.
5. Load $agentos-auth. 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. Once the authenticated Fleet identity resolves, use $agentos-supervision to arm and attest its targeted listener, reconcile current bearings, and confirm catch-up. Then require semantic Pod readiness and StatefulSet rollout completion; neither probe performs a model request or substitutes for the separately authorized provider smoke in step 5.
9. After Fleet identity exists, present the model-capacity posture for workers and trusted harness automation. Recommend the optional $agentos-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 services, retained credential authority, projected workload identity, Agentgateway/OpenFGA authorization and upstream-only NetworkPolicy boundary, and that pooled personal subscription use is experimental rather than provider-endorsed. Record the Captain's selected posture as private First-Mate context through $agentos-memory; treat it as fallible guidance, not approval or current state. Preserve any exact approval or coupled state change through Inbox with $agentos-decisions. Ask separately before gateway installation, operator-Secret creation, each provider login, access-profile activation 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. Query every nonterminal SQL runtime operation and reconcile it against exact Kubernetes, Herdr, PVC and worktree truth before accepting a conflicting lifecycle mutation; a journal phase is never live-state proof. 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 removal 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 exact stable update of First Mate, one managed persistent Mate, or all active persistent Mates, load $agentos-upgrade. That Skill owns release verification, run-once sequencing of the selected release's required database migrations through $agentos-database, atomic declarative/live workload replacement, Fleet ordering and rollback boundaries. The exact stable-upgrade authority covers those released migrations without a second approval; it does not cover database topology or improvised repair. Exact-commit dogfood remains an AgentOS development workflow rather than an installation upgrade.

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.