hexagon deploy command. Run source commands from the repository root after npm ci. The source of truth is package.json and tooling/local.ts.
Invocation and environment
npm run local with no subcommand defaults to status. Arguments after npm’s -- reach the launcher. It uses positional arguments, not a general option parser. There is no dedicated --help branch: unknown subcommands print usage and fail. Do not treat ignored extra arguments as supported flags.
Use the same data directory, database and port across commands for one installation. The default database URL does not create PostgreSQL or its database.
TEST_DATABASE_URL belongs to test scripts; it does not select the launcher’s database. More deployment settings are covered in networking.
Every launcher invocation first creates the data directory if absent, including status. All subcommands except status also acquire an exclusive operation.lock there, released on normal completion. A lock conflict is not permission to remove the file: establish whether an operation is still active before investigating a stale lock.
Managed-service commands
Successful start output includes
state, Console URL, the owner credential file/field location and credential-access status; it does not print the owner token. Source npm run dev starts the control plane in the foreground and is not the managed launcher or a file watcher. Use npm run db:migrate before that direct path. Do not run foreground and managed instances against the same dataset accidentally.
Caught launcher failures print a message to stderr and set exit code 1. Normal commands exit zero unless their check sets a failure code. npm also prints its own script wrapper, so the entire npm run stdout should not be assumed to be a single JSON document. Do not classify readiness or cleanup using exit code alone.
Configure deployment settings
cloudflare, disabled and external (with an HTTPS origin in url). outbound_proxy is optional; no_proxy defaults to an empty array. See settings.ts for exact URL/schema constraints.
The result contains the revision and restart_required: true; the command does not restart the service. An explicitly supplied process environment may still override the saved file. Disabled ingress prevents protected cloud execution from reaching the control-plane credential service; it is not a substitute for configuring a working cloud connection. Use networking for external ingress and proxy setup.
Export diagnostics
{"written":true}. It uses the allowlisted support projection: timestamp, platform/architecture/Node, reachability and service-state indicators. It does not bundle raw logs, arbitrary health fields, tokens or user prompts. An unreachable service can still produce a useful report and a successful command exit; check reachable and the state fields. Review the report before sharing.
Offline backup and restore
pg_dump, and includes master.key, owner.json, optional deployment settings, a database dump and integrity manifest. Output reports directory, schema, files and state: verified. The bundle contains secrets and must remain private. A failed attempt can leave a partial destination; do not reuse it as a verified backup.
pg_restore, validates the restored identity, and returns requires_start: true and the restored schema. It does not start the service or recreate cloud resources. Configure the restored schema’s search path when it is not the default. Backup/restore require PostgreSQL client tools and suitable privileges.
Do not blindly retry a failed restore: database or staging changes may remain. Inspect the failure and use the recovery procedure in backup and restore. Errors such as backup_close_sessions_first, backup_identity_mismatch, restore_database_not_empty and restore_integrity_failed identify distinct corrective actions; never bypass them by deleting the source identity.
Failure, timeout and partial progress
The PostgreSQL subprocess helper has a 120-second deadline, sends SIGTERM, then may send SIGKILL after five more seconds. This applies to its
pg_dump/pg_restore child, not to the local launcher’s control-plane stop command, which does not force-kill. The restore subprocess uses a single PostgreSQL transaction; subsequent identity checks and moving private files are separate steps, so the whole restore procedure is not one atomic operation.
The backup result state: verified means the backup routine completed its source-identity checks and wrote a dump plus hashes. It does not mean that bundle has been restored in a rehearsal. Similarly, requires_start: true after restore means service startup and readiness still need verification. Use the backup/restore runbook for the full procedure.
Source development and verification scripts
The release checker accepts
--artifact <directory> after npm’s separator to inspect an artifact. Its pattern scan is not comprehensive secret detection. See testing for evidence scope, private artifacts and required checks.
Real-cloud scripts are separate: verify:cloud -- <private-config> [harness ...], verify:compatibility -- <private-config> and verify:serverless -- <provider> <harness-key>. They may create resources and incur cloud/model charges; their inputs and scope differ. Read testing before use. Internal fault-injection scripts are not installation steps.
A distribution produced by build:local has a different generated package manifest: local, start and db:migrate. Install its dependencies with npm ci --omit=dev, then use npm run local -- start or npm start. Do not expect source verification commands to exist in that distribution. No public package/download availability is implied by a successful local build.
Verification scope
The command inventory was checked usingnpm run (exit 0), which lists scripts without executing them. A subsequent isolated launcher check executed seven cases in a temporary data directory: stopped status, valid configuration, unreachable-service diagnostics, diagnostics overwrite refusal, unknown command, missing configure input and invalid configuration. It confirmed exit codes, preserved existing files, private file modes and lock release; temporary files were removed afterward.
Those checks did not use a database or start/stop a service. Migration, backup/restore, live readiness and cloud acceptance were not executed by this check. Their semantics above were reviewed against the launcher, settings, backup, diagnostics and build implementations; historical operational evidence retains its own scope and date.
Next: installation, local workspace, testing.