Deployment lifecycle

A deployment is a running instance of your built application on a deploy target. This page documents the deployment state machine: every status, what triggers each transition, and what the platform does at each step.

Deploy target kinds

• agent — your own Kubernetes cluster. You install the Forginate deploy agent, which dials out to the platform over WebSocket (/agent/ws) using an enrollment key. The platform never connects into your cluster; it sends commands (apply / set image / scale / delete) over that socket and the agent applies Kubernetes manifests locally.
• aws_account — a dedicated AWS account vended for you under Forginate's AWS Organization. Apps run on ECS Fargate with a public IP per task; logs go to CloudWatch and are surfaced back into the product. AWS costs are passed through with a service margin.

Target statuses (mostly relevant for agent targets): pending → connected, then degraded (no heartbeat for 2 minutes) or disconnected (10 minutes), plus deprovisioning / removed. Agents heartbeat every 30 seconds.

Deployment statuses

The full status vocabulary (from the shared contracts):

planning            the AI planner is producing a deploy plan
awaiting_approval   plan ready; waiting for you to approve it
deploying           plan approved; being applied to the target
running             live and healthy
degraded            live but unhealthy (readiness failing, etc.)
failed              a step failed; see the recorded error
upgrading           a new image is being rolled out
stopping            being scaled to zero
stopped             scaled to zero (record and plan retained)
tearing_down        workload deletion in progress
torn_down           workload deleted (terminal)
separated           handed over to you; platform stops managing it (terminal)

torn_down and separated are terminal — no further transitions are possible; the only remaining action is deleting the deployment record.

State machine

 create ──▶ planning ──▶ awaiting_approval ──▶ deploying ──▶ running ⇄ degraded
               ▲   │            │  ▲              ▲  │           │
               │   ▼            │  │ (replan)     │  ▼           ▼
               │ failed ────────┴──┘          start│ stopping ─▶ stopped
               │   ▲                               └─────────────┘
    (replan)───┘   │
                   │        any non-terminal state:
 running ─▶ upgrading ─▶ running     stop ─▶ stopping
                                     teardown ─▶ tearing_down ─▶ torn_down
                                     separate ─▶ separated

Who drives what:

• You (user actions) set intent statuses: creating a deployment enters planning; Approve moves awaiting_approval → deploying; Re-plan moves back to planning (allowed from awaiting_approval, failed, running, degraded, stopped, optionally with extra guidance appended to the instructions); Stop and Teardown work from any non-terminal state — a working stop control is a product invariant; Start works only from stopped; Separate works from any non-terminal state.
• The orchestrator's background sweeps notice intent statuses and do the work, and the results (agent apply_result frames, or the in-process ECS calls) advance the deployment to the outcome status (running, stopped, torn_down, or failed).

Plan → approve → dispatch

1. Planning. The planner sweep picks up planning deployments.
   • For k8s targets, an LLM produces a complete manifest set (Deployment with probes and resource limits, Service, Ingress with TLS when the cluster has an ingress class and cert-manager), customized to the agent-reported cluster facts and your free-text instructions. If the app is already running, the planner receives the live configuration and evolves it rather than recreating it (names, PVCs, and local drift are preserved). Invalid planner output is retried; persistent failure sets failed with a "use Re-plan to retry" error.
   • For AWS targets, planning is deterministic (no LLM): a standard Fargate task definition + service (0.25 vCPU / 512 MB, port inferred from your instructions or defaulting to 8080, CloudWatch logging).
   • Either way, the plan lands with a plain-English plan summary and the status becomes awaiting_approval. If no image can be determined (no linked repo and no image ref), the deployment fails immediately.
2. Approval. You review the summary (and manifests) and approve, or re-plan with extra guidance. Nothing touches your infrastructure before approval.
3. Dispatch. The dispatch sweep handles deploying, upgrading, stopping, and tearing_down:
   • k8s: it publishes an agent command — apply (deploy/upgrade, with the target image patched into the stored manifests), apply with replicas 0 (stopping), or delete (teardown). The agent's apply_result advances the status. Dispatch is idempotent: a command already in flight is not re-sent for 10 minutes.
   • AWS: the orchestrator performs the ECS work directly — registers the task definition, ensures the cluster / execution role / security group / registry-pull secret exist, and creates or updates the service. Success sets running synchronously.

Deployments can also opt into auto-upgrade: with CI provisioned on the project repo, each push to the default branch builds a new image and rolls the deployment through upgrading automatically.

Stop / start / teardown / separate semantics

• Stop scales workloads to zero (k8s: replicas 0 apply; AWS: desiredCount 0). The record, plan, and data survive; on k8s, PVCs are untouched.
• Start re-enters deploying and re-applies the stored manifests at their original replica counts — the same idempotent apply path as a fresh deploy.
• Teardown deletes the workload:
  • k8s: the agent deletes exactly the resources named in the plan's manifests, in the plan's namespace.
  • AWS: the ECS service is deleted. Reusable scaffolding — the vended account itself, the ECS cluster, IAM execution role, log groups, security groups — is left in place, so a later deployment to the same target is fast. Terminal status: torn_down.
• Separate ends Forginate's management without touching the workload. On k8s the agent simply stops receiving commands for the deployment and you uninstall at your leisure; for AWS targets it begins the account-handover process (the vended account is flagged for operator-driven transfer to you). Terminal status: separated.
• Delete record (DELETE .../deployments/:id) is allowed only from torn_down, separated, or failed, so live cluster resources can never be orphaned by deleting a record.

Telemetry

Everything below is visible on the deployment detail page (and via the API):

• live_status — a rich operational snapshot: per-workload desired/ready replicas and images, pod phases/restarts/reasons (e.g. OOMKilled), volume usage, and a timestamp. Agents push it on change and on request (refresh-status); for AWS it is assembled from ECS task/service state.
• endpoints — where the app is reachable: ingress hosts discovered by the agent, or the public IP per Fargate task.
• recent_logs — a ring buffer of recent log lines per workload. Agents push up to 200 lines on request (request-logs); AWS deployments pull from CloudWatch.
• Metrics & uptime — CPU/memory sampled agent-side plus an HTTP availability probe, exposed via the metrics and uptime endpoints.
• Events — an append-only per-deployment event trail (plan_ready, plan_approved, cmd_sent, apply_succeeded, apply_failed, stop_requested, teardown_requested, incident_reported, ...) so you can reconstruct exactly what happened and when.
• Incidents — agents fingerprint recurring error patterns and report them as incidents; the monitor sweep automatically files each open incident as a bug-kind improvement request on the project (with the error sample attached). You approve the fix in the Improve screen and the normal improvement pipeline plus auto-upgrade close the loop.

Health staleness

While a deployment is running, agent heartbeats keep it honest: if workloads report not-ready, the status flips to degraded, and back to running on recovery. A failed deployment records its lastError on the deployment row — that is the first place to look.