Skip to main content
These four routes manage the current local control-plane workspace. They are registered only when a deployment settings service exists, require owner authentication and additionally require tenant local-workspace. Other tenants receive 403 deployment_management_forbidden; application tokens are rejected by the owner route policy. This is not an API for provisioning hosted deployments.

Read settings

GET /v1/deployment returns 200 with config, revision, restart_required, optional ingress status, and environment_overrides. Revision is the SHA-256 of the parsed/defaulted configuration JSON. Restart_required compares saved revision with the running process’s startup revision.
Config contains outbound_proxy (optional), no_proxy and ingress. Ingress status, when configured, has state, attempts, checked_at and possibly code. Environment_overrides has boolean proxy/ingress indicators; it does not expose the values or enumerate every environment override. A missing deployment.json uses defaults; malformed/unreadable saved configuration returns 500 deployment_configuration_invalid.

Replace configuration

PUT /v1/deployment accepts strict {config,expected_revision}. Expected_revision must be a 64-character string matching the current revision returned by GET. Config is a complete replacement, not a merge: No-proxy entries permit * or the schema’s host-like patterns, not URLs, arbitrary shell expressions or general regular expressions. Refer to configuration for environment precedence: saved values do not necessarily override explicit process environment. Prepare deployment-update.json with your GET revision and complete intended config. For example, {config:{no_proxy:[],ingress:{mode:"cloudflare"}},expected_revision:...} selects temporary ingress and removes any saved outbound proxy. Use actual JSON in the file, not this illustrative notation.
Success returns 200, {config,revision,restart_required:true}. The implementation takes an exclusive file lock, checks revision, writes a private temporary file and atomically renames it to deployment.json. It does not restart the process or establish a working tunnel. Omitted fields get defaults, including cloudflare ingress; do not omit fields intending to preserve them. 409 deployment_configuration_changed means your revision is stale: re-read and reconcile the complete intended configuration. 409 deployment_configuration_busy means the update lock exists; investigate the active writer before touching a lock. A lost response can follow a successful file replacement. Read the saved revision/config before retrying, and schedule any restart through the local management workflow. There is no automatic rollback of an applied config if a later restart fails.

Retry temporary credential ingress

POST /v1/deployment/ingress/retry takes no required body and normally returns 200 with the currently available ingress status. It requires the running environment’s HEXAGON_ACCESS_TUNNEL to equal cloudflare; otherwise 409 development_ingress_disabled.
The handler starts retry without awaiting completion, then reads status. A successful response does not prove ingress is ready. Poll deployment/health and inspect status. If the optional ingress service is absent, do not assume a status object or an attempt occurred merely because the route exists.

Stop ingress

POST /v1/deployment/ingress/stop takes no required body. It awaits the configured ingress service’s stop and returns 200 with its available status. It does not rewrite saved ingress mode, disable future process startup or close Sessions.
Retry and stop both reject with 409 active_run if any nonterminal Run in the database exists; the guard is not limited to the current tenant. Stopping ingress can affect credential delivery for later tasks, so verify readiness before resuming work. Neither operation has a request idempotency key or changes the saved configuration revision. Malformed strict update bodies return 400 invalid_request. Source: settings and environment composition, route guards, ingress lifecycle. Examples assume HEXAGON_API_URL without /v1 and a local owner token. No settings, processes or tunnels were changed in this documentation pass.

SDK examples: save an intent before changing settings

Use an initialized local-workspace owner client. These independent helpers illustrate a deliberate change to an already operated external HTTPS credential-ingress origin; they do not provision the host, install a certificate or configure a reverse proxy. Defining them does not change settings. Read networking before choosing the actual origin.
Preparation reads the current revision and clones the entire config, preserving saved outbound_proxy and no_proxy while replacing ingress. It does not save the file. Review and privately persist this intent before separately applying it. Do not pass the entire deployment GET response as config: status, environment_overrides and revision are response metadata, not configuration fields. The server validates the origin and full configuration on update; the helper does not certify them. The apply helper sends the originally observed revision. deployment_configuration_changed requires comparison with the latest saved config, not automatically substituting its revision; a lost successful response may produce the same conflict. On deployment_configuration_busy, investigate the writer rather than deleting its lock. Saving returns the new config/revision and restart_required; it neither restarts the control plane nor verifies ingress. Explicit process environment can still override saved values after restart. Retry and stop are separate operational choices, not steps to run after every save. Temporary-ingress retry requires the running cloudflare mode; saving external mode does not convert it into an external-endpoint repair API. A retry response can describe an attempt still in progress. Stop does not change saved ingress config, close Sessions or disable the next startup. Both operations reject if any nonterminal Run exists in the database, not merely a Run belonging to the caller’s tenant. A later GET through deployment is an observation, not a guarantee of readiness. The generic stop request uses /deployment/ingress/stop without /v1; it fills a convenience-method gap without bypassing role or active-Run checks. If the optional ingress service supplies no status body, JSON decoding can fail after an accepted operation: query deployment/health rather than inferring no operation happened. These snippets do not implement a restart, polling deadline or automatic retry. Local syntax/type checks are separate from a real configuration migration and tunnel verification. Next: local workspace, networking, HTTP overview.