Deploy

Deploy mode gets an existing Lex app running in a target environment using steps served by the remote Lex handbook, and never records a secret value.

A
Written By Atakan KayaLast updated about 1 month ago

Deploy

Deploy mode gets an existing LEX app running in a target environment. It configures and runs; it does not write application code. The step bodies come from the remote Lex deployment handbook rather than from a local catalogue, so there is no fixed step count.

Slash command: /lex-deploy. With ten tools it is the smallest surface of any mode.

The flow

/lex-deploy
  ↓
kickstart_deployment(project_path=... OR github_url=...,
                     deployment_target="staging", notes="...")   # mandatory first call
  ↓ loop:
get_deployment_step(step=N) → runSubagent("lex-deploy-step", ...)
    → notify_deployment_step_complete(step=N, summary=..., status="completed")
  ↓
finalize_deployment()          # writes deployment/DEPLOYMENT-REPORT.md

deployment_target is free text — recorded, never validated. Local, staging and production are examples, not an allowed set. get_deployment_status() re-orients the coordinator after an interruption.

Steps come from the remote handbook

There is no local step catalogue, and synthesising a step body is forbidden. If the remote is unreachable the tool returns a structured ok: false halt naming the connectivity and credential settings to check, never a plausible-looking invented step — a wrong deployment instruction executed with confidence is worse than none. See Troubleshooting for the halt contract.

What the mode owns locally is the session, the per-step record, the index, the report, and a scan of the deployment surface: compose files, Dockerfiles, .env templates, requirements/pyproject/manage.py, Procfile, Makefile, Justfile, *.service units, and any CI, deploy, infra, charts, k8s or nginx directories, and the Streamlit or Reflex dashboard processes the project has to start beside the app. That scan is deliberately shallow — orientation for the first step, not an infrastructure audit.

Secrets are never recorded

This rule is non-waivable and it shapes the whole mode:

  • No secret value is ever written — not in a step summary, note, index row, report or log line. Only the key name and where it belongs.
  • The report carries an explicit Secrets section saying so, in case the absence reads as an omission.
  • A credential found already committed is a halt, not a finding to list and move past.
  • The agent does not type credentials for you and does not commit a populated .env. The artifact it produces is the .env.example.

This is also why the mode is git-free by design: a deployment run writes configuration, and an auto-commit is precisely how a populated .env reaches a remote.

Blocked steps and verification

notify_deployment_step_complete accepts completed, partial or blocked, and only completed advances the cursor — a blocker walks the coordinator back to the problem rather than past it. Re-running a step replaces its record instead of appending a second one. finalize_deployment refuses when no steps were recorded at all, and otherwise returns every step still blocked or partial alongside the report.

Two purpose-built agents do the work. lex-deploy-step executes the handbook step; lex-deploy-verifier establishes whether the application actually works in the target environment, not whether the steps were performed. The verifier treats step notes as claims to be tested and never repairs what it verifies, because an agent that fixes and confirms in one pass cannot report a failure.

Where output lands

Everything is written under <project_root>/deployment/: step-NN-<run-id>.md per step, an auto-maintained _index.md, and the consolidated DEPLOYMENT-REPORT.md. Commit them yourself. See Outputs and artifacts and Mode chooser.

Was this helpful?

Your feedback shapes what we write next.