# Ms. Computer deployment workflow Return the exact URL provided by the Deploy API; never construct a hostname from the application name or infer deployment health from its suffix. Applications use generated `https://-<4 digits>.ms.computer` URLs. Run every command from the clean application repository root. ## 1. Plan 1. Run `mscomputer plan --write --json`. 2. Parse the single JSON result from stdout. Do not call Railpack directly. 3. Exit `0` means `mscomputer.toml`, `.mscomputer/railpack-plan.json`, and `.mscomputer/railpack-info.json` are ready. 4. Exit `2` means the result names an agent or owner action. Inspect only the listed repository evidence before changing anything. 5. Make one minimal persistent change and review the diff. Railpack overrides belong only in `.mscomputer/railpack.json`; never create a root `railpack.json`. 6. Rerun the same command until ready, or until a product decision or an unsupported capability requires the owner. 7. Never invent secrets, remove real application requirements, use a development server as production behavior, or add framework-specific detection merely to pass one repository. `mscomputer.toml` is the only root file Ms. Computer creates. Plans, state, logs, and the exported image stay below `.mscomputer/`, whose generated contents are git-ignored. Unsupported in this release: user environment variables or secrets, databases and other stateful services, persistent volumes, background workers, multiple services, WebSockets or streaming responses, request bodies over 1 MiB, and responses over 16 MiB. ## 2. Build and local smoke test After planning exits `0`, run `mscomputer build`. It needs a running Docker Engine with the Buildx plugin; for `BUILD_ENGINE_UNAVAILABLE` or `BUILD_ENGINE_INCOMPATIBLE`, install Docker Desktop (macOS/Windows) or Docker Engine plus Buildx (Linux), start it, and rerun the command. Never place Docker credentials or environment files in the repository. The build produces a `linux/amd64` image from the saved plan and smoke-tests it under the exact `small-v1` runtime profile miners use: 1 CPU, 1 GiB memory, 256 processes, a read-only filesystem with a 64 MiB `/tmp`, user `65532`, no Linux capabilities, and no network egress. The application must listen on `0.0.0.0:$PORT` and answer `GET /` with `200` twice in a row within 60 seconds. `BUILD_SMOKE_FAILED` reports the miner-equivalent reason (`container_exited`, `health_timeout`, `health_unexpected_status`) with a bounded log excerpt; an image that fails here would fail on miners too. The tested image is exported to `.mscomputer/oci` as a verified OCI image. That export, not a registry, is what `mscomputer deploy` uploads. When Railpack selects only its staticfile provider, `index.html` is present, and nothing in the build context suggests server code (API routes, a start script or dependencies, a Procfile, SSR framework config, hidden files such as `.env`, `.git` or a `Caddyfile`), the build reports a static site. It is built from the pinned staticfile template and left unlabeled, so the platform decides: an image it cannot prove static is deployed as a dynamic image, unchanged. Use `mscomputer build --static` to claim static explicitly; a claim the platform rejects makes `mscomputer deploy` show the reason and rebuild once without the claim, as a dynamic image. Use `mscomputer build --dynamic` to opt out. (`--dynamic` labels the image `oci-image-v1`, which only a platform with static-by-default accepts.) `deploy` prints the admitted workload kind (`static-site-v1` or `oci-image-v1`). Repository builds execute repository code with bounded local Docker resources and normal package-download network access. Docker is not a complete sandbox for malicious build scripts; build only repositories the user intends to run. ## 3. Deploy No token setup is needed: without `MSCOMPUTER_TOKEN` the CLI obtains a free six-hour access token itself, caches it with mode 0600 outside the repository, and replaces it when it expires. An application secret is stored separately on first deployment and remains the application's authority for the app's whole lifetime, so later redeploys, status and teardown keep working. ```bash mscomputer deploy # token from MSCOMPUTER_TOKEN or obtained automatically mscomputer deploy --token-stdin mscomputer deploy --name my-app ``` Deployed images are readable by every miner and must be treated as public. The command uploads only blobs the platform does not already hold, waits for the image to be verified, submits the deployment, and follows its events until the verified temporary origin serves the public URL or a terminal result is reached. Do not poll the Deploy API separately while this command runs. Success is exit `0` with `Deployment`, `Artifact`, and `URL` fields; return the URL to the user. The public URL can start serving from a temporary origin. Origin serving reports `deploying`; `healthy` means three miner replicas passed acceptance and serve the URL. In the current prelaunch origin-only mode, miner placement is disabled and the temporary origin continues serving until teardown; do not expect `healthy` or infer it from a reachable URL. Return the status and URL the API actually provides. The first deployment of an application stores a one-time application secret in `$XDG_CONFIG_HOME/mscomputer/applications/` (mode `0600`). It is the only authority over the application once the API token expires. Never copy it into the repository, an image, a log, or a result. Never put the API token in a command-line argument, repository file, image, build argument, result, or log. ## 4. Status, recovery, and teardown An interrupted or timed-out deploy does not cancel server-side work. Run `mscomputer status` (or `mscomputer status `) once to read the current state; rerunning `mscomputer deploy` with the same build resumes the same request. `mscomputer teardown` stops the application and waits until it is `terminated` (`--no-wait` returns once teardown is accepted). The hostname stays reserved for the application. A live application must be torn down before a new version is deployed (`APPLICATION_ALREADY_LIVE`). On a terminal failure, use only its code, action, diagnostic, and repository evidence to make one minimal persistent correction, review the diff, and rerun plan, build, and deploy. Make at most five correction attempts; then return the complete structured failure to the owner instead of broadening the changes.