Skip to main content
Configuration has separate layers: control-plane process settings, saved local deployment settings, Session behavior/guest environment, and provider-specific Connections. Their scopes differ. Putting a cloud account key in Session env does not replace a Connection.

Control-plane process

Sources: main.ts, deployment mode, local discovery and tunnel. Changes require service restart, except internal readiness logic can update temporary ingress origins. Defaults below are entry-point defaults before local saved settings are applied. Hosted startup requires an explicit database, matching key, existing owner Token and HTTPS credential origin without userinfo, query, fragment or a non-root path. Development tunnels are rejected. Failures include invalid_deployment_mode, hosted_identity_and_storage_required, hosted_master_key_invalid, hosted_https_ingress_required and hosted_owner_identity_required. There is no automatic hosted identity bootstrap; see self-hosting. Listener ports are converted with Number(...) and passed to the server; invalid values do not all have one unified configuration error. Port conflicts, invalid hosts and listen failures use underlying errors. Changing HOST does not configure TLS, identity or reverse proxies.

Saved local deployment settings

The selected data directory contains deployment.json, validated by settings.ts. Local startup reads it; the direct hosted entry does not. The managed local launcher applies saved settings, so follow self-hosting instructions with explicit process configuration rather than mixing hosted startup with local bootstrap. Example configuration (the external hostname is a placeholder requiring real routing):
configure replaces the full config rather than merging a patch; omitted fields take defaults. It returns a revision and restart_required: true, without restarting. Invalid saved files cause deployment_configuration_invalid; concurrent updates can produce deployment_configuration_busy or deployment_configuration_changed. Read the current settings rather than bypassing locks/revisions.

Standard proxy variables

All variables below are optional process-environment strings. They apply at process startup; restart after changing an operator-supplied value. The local launcher and direct local entry first assemble saved settings, while direct hosted startup passes the environment to the outbound dispatcher without that assembly. Treat proxy URLs as sensitive if they contain authentication; do not copy them into public diagnostics. Host bypass lists are normally nonsecret but can expose internal names. The last row describes Hexagon’s wrapper, not a guarantee of how every provider SDK or external executable interprets environment variables. The tunnel wrapper attempts its proxy-stripped fallback only for its specific transport-failure classification and when fallback is not disabled. It does not retry every tunnel failure. Sources: local environment assembly, outbound dispatcher, Cloudflare wrapper. These settings configure control-plane transport, not Sandbox network policy or account authorization.

Proxy precedence

Local deploymentEnvironment chooses HTTPS_PROXY, then https_proxy, then saved outbound_proxy. HTTP proxy uses HTTP_PROXY, then http_proxy, then that selected proxy. NO_PROXY takes precedence over no_proxy and merges with saved entries plus 127.0.0.1,localhost. An explicitly present empty string can shadow saved values. HEXAGON_ACCESS_URL takes precedence over a saved external URL; a usable external address disables the temporary tunnel. Without one, explicit HEXAGON_ACCESS_TUNNEL takes precedence over ingress mode. Local environment assembly sets NODE_USE_ENV_PROXY to 1; setting it to 0 is therefore not guaranteed to disable proxies through that path. The direct hosted outbound setup does select direct transport when it receives 0. With a local proxy and no explicit HEXAGON_ACCESS_EGRESS_PROXY_URL, assembly fills that value from the selected proxy. HEXAGON_ACCESS_EGRESS_HOSTS then defaults to api.siliconflow.com,api.minimaxi.com,api.minimax.io,api.minimax.chat. This concerns credential-access proxy routing, not account authorization or the Sandbox network allowlist. See networking for advanced settings; application policy and process proxies are distinct.

Resolve conflicting settings

These examples describe the local deploymentEnvironment function with only the stated inputs; inherited shell variables can change the result. They use reserved example addresses, not working ingress services. Inspect names and origins without printing credentials. An empty proxy field is not a general “disable all proxies” switch: other inherited HTTP(S) variables and dedicated protected-upstream routing can still apply. Hosted startup does not call this local assembler; its outbound dispatcher honors NODE_USE_ENV_PROXY=0 directly.

Dedicated protected-upstream routing

These optional settings apply to both deployment modes. Set them before starting the process and restart to apply an operator change. The local assembler can supply defaults as described above; direct hosted startup has no such saved-setting fallback. See the protected transport implementation for proxy selection and endpoint validation. A proxy URL without matching hosts does not route every protected request through that proxy. A matching proxy with another URL scheme raises credential_egress_proxy_invalid; malformed URLs can raise the URL parser error. Selecting this trusted proxy delegates DNS enforcement to it; keep its policy under operator control.

Applying a saved change

Prepare the complete desired JSON, including fields you want to retain, then run npm run local -- configure /absolute/path/deployment.json. For example, replacing a configuration that contains an outbound proxy with only {"ingress":{"mode":"disabled"}} removes the saved proxy and resets no_proxy to []. Shell overrides can still apply after restart. The command saves privately and returns restart_required: true; it does not restart the running instance. Arrange the restart using the local workspace guide, then inspect health/readiness and test the intended access path. A healthy management listener alone does not establish working credential ingress. If the revision changed, read the latest configuration and reconcile your intended change; do not retry an obsolete replacement blindly.

Session settings and guest environment

variables is an alternative to env. Supplying variables together with nonempty env produces ambiguous_variables. Names match [A-Za-z_][A-Za-z0-9_]{0,127}. Prefixes HEXAGON_, OPENCODE_, PI_ and names PORT, NODE_OPTIONS, PYTHONPATH, PYTHONHOME, LD_PRELOAD, LD_LIBRARY_PATH are reserved. Values reject NUL; see limits for count/byte bounds. Do not use guest env to bypass control-plane credential storage. Sources: Session schema, environment schema, initialization. Create a new Session for a changed definition; saving deployment settings or restarting does not rewrite an existing Session’s pinned behavior.

Client and provider settings

SDK URL/Token constructor arguments are client configuration. Example HEXAGON_API_URL / HEXAGON_API_TOKEN variables are read by the example program, not control-plane identity-bootstrap switches. Hexagon.local() discovers identity using explicit data-directory selection, workspace descriptors and the user discovery file. Do not weaken private-file checks to make discovery succeed. Provider settings live in Connection config, with managed Secret or OAuth credentials. Their fields, defaults and verification scope are in integration guides, not global deployment environment variables. Test-only TEST_DATABASE_URL does not select the ordinary service database. This page was checked against current configuration readers; no running installation was changed or restarted. Next: installation, self-hosting, networking.