Projects

Update environment settings

Changed on
put/projects/{project_id}/environments/{env_id}/settings

Request

  • Base URL: /api (relative, and the document was published on a file host, not at the API’s origin)
  • URL: /api/projects/{project_id}/environments/{env_id}/settings
  • Auth: none declared

Path parameters

project_idinteger required

Project ID or slug

env_idinteger required

Environment ID or slug

Request body

anti_affinityboolean nullable

Anti-affinity: spread replicas across different nodes. When enabled, the scheduler avoids placing two replicas of the same environment on the same node. Defaults to true.

attack_modeboolean nullable

Per-environment CAPTCHA attack-mode override (tri-state):

  • absent → leave the current override unchanged
  • JSON null → clear the override (inherit the project-level setting)
  • true/false → override the project setting for this environment
automatic_deployboolean nullable

Enable/disable automatic deployments for this environment

branchstring nullable
build_location'control_plane' | 'node'

Where a source deployment's image is built.

The control plane is the default and the historical behaviour. Node moves the build — the most CPU- and memory-hungry step of a deployment — onto a worker node so it stops competing with the proxy, the database and running workloads on the control plane. A node labelled temps.sh/role=builder is preferred; otherwise the node the deployment is placed on builds it.

Node is a preference, not a requirement: when no worker can take the build (none joined, none of the right architecture, or a multi-architecture build) the build runs on the control plane and the build log says why. A static site may build on a worker of any architecture, since its output is read from that node and never runs.

cpu_limitinteger nullable

Maximum (limit) CPU in microcores. Send JSON null to clear → "no limit". Absent leaves the current value unchanged.

cpu_requestinteger nullable

Minimum (request) CPU in microcores. Send JSON null to clear (no request). Absent leaves the current value unchanged.

cross_architecture_buildsboolean nullable

Build one image per architecture the eligible nodes run (overrides the project-level setting). Off by default: cross-architecture builds are emulated on the control plane and substantially slower, so they are opted into per environment rather than triggered by cluster topology.

exposed_portinteger nullable

Port exposed by the container (overrides project-level port for this environment)

Priority order for port resolution:

  1. Image EXPOSE directive (auto-detected from built image)
  2. This environment-level exposed_port (overrides project setting)
  3. Project-level exposed_port (fallback)
  4. Default: 3000
force_httpsboolean nullable

Per-environment HTTP→HTTPS redirect override (tri-state):

  • absent → leave the current override unchanged
  • JSON null → clear the override (inherit the proxy default, which redirects only when the host has an active TLS certificate)
  • true → always redirect plain HTTP to HTTPS for this environment, even when no local certificate exists (TLS terminated upstream)
  • false → never redirect this environment, even when a certificate does exist

Requests under /.well-known/acme-challenge/ are never redirected regardless of this setting, so ACME HTTP-01 validation always completes.

idle_timeout_secondsinteger nullable

Seconds of inactivity before stopping containers (60-86400). Default: 300.

max_concurrent_connectionsinteger nullable

Override the proxy's cap on concurrent in-flight requests to this environment's upstream (0 = unlimited). Absent leaves the current value unchanged. Send JSON null to clear the override (inherit the project/global default). See issue #646.

memory_limitinteger nullable

Maximum (limit) memory in MB. Send JSON null to clear → "no limit". Absent leaves the current value unchanged.

memory_requestinteger nullable

Minimum (request) memory in MB. Send JSON null to clear (no request). Absent leaves the current value unchanged.

on_demandboolean nullable

Enable on-demand mode (scale-to-zero). Containers are stopped after idle_timeout_seconds of no traffic and started on the next request.

passwordstring nullable

Set a password to protect this environment. The proxy will show an HTML password form before allowing access. The password is bcrypt-hashed server-side and never stored in plaintext. Send an empty string to remove password protection.

performance_metrics_enabledboolean nullable

Enable/disable performance metrics collection

protectedboolean nullable

When true, git pushes do NOT auto-deploy to this environment. Deployments must be promoted from another environment.

replicasinteger nullable
request_timeout_secondsinteger nullable

Override the proxy's timeout for regular (non-streaming) HTTP requests to this environment, in seconds (0 = no timeout, or 1-86400). Always clamped to the operator's global hard ceiling regardless of what's set here. Absent leaves the current value unchanged. Send JSON null to clear the override (inherit the project/global default).

session_recording_enabledboolean nullable

Enable/disable session recording

sse_idle_timeout_secondsinteger nullable

Override the proxy's idle timeout for Server-Sent Events streams to this environment, in seconds (0 = no timeout, or 1-86400). Always clamped to the operator's global hard ceiling. Absent leaves the current value unchanged. Send JSON null to clear the override.

target_labelsunknown
target_nodesinteger[] nullable

Optional list of node IDs to deploy to (overrides project-level setting). Send an empty list to clear the environment-level override.

wake_timeout_secondsinteger nullable

Max seconds to wait for containers to start on wake (5-120). Default: 30.

websocket_idle_timeout_secondsinteger nullable

Override the proxy's idle timeout for WebSocket connections to this environment, in seconds (0 = no timeout, or 1-86400). Always clamped to the operator's global hard ceiling. Absent leaves the current value unchanged. Send JSON null to clear the override.

Example request

{
  "exposed_port": 8080
}

Response

Environment settings updated successfully

attack_modeboolean nullable

Per-environment CAPTCHA attack-mode override. null means inherit the project-level attack_mode; true/false explicitly enable/disable the challenge for this environment. Always serialized (NOT skipped) so the UI can distinguish null from false.

branchstring nullable
created_atinteger required
current_deployment_idinteger nullable
estimated_sleep_atinteger nullable

Estimated time (epoch millis) when the environment will go to sleep based on last activity + idle timeout. NULL when sleeping or on-demand disabled.

force_httpsboolean nullable

Per-environment HTTP→HTTPS redirect override. null means inherit the proxy default (redirect only when the host has an active TLS certificate); true always redirects plain HTTP for this environment, false never does. Always serialized (NOT skipped) so the UI can distinguish null from false.

idinteger required
is_previewboolean required

Indicates if this is a preview environment (auto-created per branch) For preview environments, 'branch' contains the feature branch name

last_activity_atinteger nullable

Last proxied request timestamp (epoch millis) for on-demand environments. NULL when on-demand is disabled or no traffic has been received yet.

main_urlstring required
namestring required
project_idinteger required
protectedboolean required

When true, git pushes do NOT auto-deploy to this environment. Deployments must be promoted from another environment.

sleepingboolean required

When true, the environment's containers are currently stopped due to inactivity (on-demand mode) and will start on the next request.

slugstring required
subdomainstring required

The host label stored for this environment (e.g. myproject-production). This is the prefix that is combined with the platform's preview domain at request time to produce main_url. Edit this via the rename-subdomain endpoint, not the full URL.

updated_atinteger required

Changes

    • info

      added the new optional request property

    • info

      added the optional property ///// to the response with the status

    • info

      added the optional property ///// to the response with the status