> ## Documentation Index
> Fetch the complete documentation index at: https://docs.hexagon.autos/llms.txt
> Use this file to discover all available pages before exploring further.

# Local deployment settings HTTP contract

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.

```sh theme={null}
curl --fail-with-body --silent --show-error \
  -H "Authorization: Bearer $HEXAGON_API_TOKEN" "$HEXAGON_API_URL/v1/deployment"
```

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:

| Field | Contract |
| - | - |
| outbound\_proxy | Optional HTTP/HTTPS origin; no user/password, query, fragment or non-root path |
| no\_proxy | Default empty array; at most 128 entries, each ≤253 characters matching the supported host-pattern schema |
| ingress | Default `{mode:"cloudflare"}`; strict mode-specific object |
| ingress.mode | cloudflare, disabled or external |
| ingress.url | Required only for external; HTTPS origin with the same URL restrictions |

No-proxy entries permit `*` or the schema's host-like patterns, not URLs, arbitrary shell expressions or general regular expressions. Refer to [configuration](https://docs.hexagon.autos/en/reference/configuration.md) 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.

```sh theme={null}
curl --fail-with-body --silent --show-error --request PUT \
  -H "Authorization: Bearer $HEXAGON_API_TOKEN" -H 'Content-Type: application/json' \
  --data-binary @deployment-update.json "$HEXAGON_API_URL/v1/deployment"
```

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`.

```sh theme={null}
curl --fail-with-body --silent --show-error --request POST \
  -H "Authorization: Bearer $HEXAGON_API_TOKEN" \
  "$HEXAGON_API_URL/v1/deployment/ingress/retry"
```

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.

```sh theme={null}
curl --fail-with-body --silent --show-error --request POST \
  -H "Authorization: Bearer $HEXAGON_API_TOKEN" \
  "$HEXAGON_API_URL/v1/deployment/ingress/stop"
```

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](https://github.com/NexusFox88/docs/blob/main/resources/modules/deployment/settings.ts), [route guards](https://github.com/NexusFox88/docs/blob/main/resources/apps/control-plane/server.ts), [ingress lifecycle](https://github.com/NexusFox88/docs/blob/main/resources/modules/deployment/ingress.ts). 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](https://docs.hexagon.autos/en/operate/networking.md) before choosing the actual origin.

```python theme={null}
from copy import deepcopy


def prepare_external_ingress(client, https_origin):
    current = client.deployment()
    config = deepcopy(current['config'])
    config['ingress'] = {'mode': 'external', 'url': https_origin}
    return {'config': config, 'expected_revision': current['revision']}


def apply_deployment_intent(client, intent):
    return client.update_deployment(intent['config'], intent['expected_revision'])


def retry_temporary_ingress(client):
    return client.retry_ingress()


def stop_current_ingress(client):
    return client.request('POST', '/deployment/ingress/stop')
```

```typescript theme={null}
type DeploymentIntent = { config: unknown; expected_revision: string };

async function prepareExternalIngress(client: Hexagon, httpsOrigin: string) {
  const current = await client.deployment();
  const config = structuredClone(current.config);
  config.ingress = { mode: 'external', url: httpsOrigin };
  return { config, expected_revision: current.revision } satisfies DeploymentIntent;
}

async function applyDeploymentIntent(client: Hexagon, intent: DeploymentIntent) {
  return await client.updateDeployment(intent.config, intent.expected_revision);
}

async function retryTemporaryIngress(client: Hexagon) {
  return await client.retryIngress();
}

async function stopCurrentIngress(client: Hexagon) {
  return await client.request('POST', '/deployment/ingress/stop');
}
```

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](https://docs.hexagon.autos/en/operate/local-workspace.md), [networking](https://docs.hexagon.autos/en/operate/networking.md), [HTTP overview](https://docs.hexagon.autos/en/reference/http.md).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.