Align sandbox defaults with the cchost configuration schema

[Copilot]

The sandbox inherited test-optimized defaults from the e2e infrastructure, causing its generated configuration and CLI help to diverge from documented cchost defaults—for example, a 100ms rather than 1000ms signature delay.

• Schema-backed defaults
  • Map CLI arguments to host configuration schema paths.
  • Derive defaults and descriptions from the schema, including unit conversion.

CLI_ARGUMENT_CONFIG_PATHS = {
    "sig_ms_interval": "ledger_signatures.delay",
    "snapshot_tx_interval": "snapshots.tx_count",
}

• Sandbox behavior

  • Make sandbox.sh opt into schema defaults while preserving faster e2e defaults.
  • Remove wrapper-specific node configuration overrides.
  • Preserve explicit command-line values as the highest precedence.

• Distribution and documentation

  • Install the host schema alongside the sandbox infrastructure.
  • Document the sandbox/e2e default distinction.

• Fixes Clarify default configuration options for the sandbox #4273

[Copilot]

Pull request overview

Aligns sandbox configuration defaults and CLI help with the cchost schema while retaining optimized e2e defaults.

Changes:

• Adds schema-backed default resolution and unit conversion.
• Enables schema defaults for sandbox.sh.
• Adds documentation, installation support, and regression tests.

Custom instructions used

• .github/copilot-instructions.md
• .github/instructions/changelog.instructions.md

Reviewed changes

Copilot reviewed 7 out of 7 changed files in this pull request and generated 1 comment.

Show a summary per file

File	Description
tests/start_network.py	Adds the schema-default opt-in flag.
tests/sandbox/sandbox.sh	Enables schema defaults and removes overrides.
tests/infra/e2e_args.py	Resolves defaults and descriptions from the schema.
tests/e2e_args_test.py	Tests defaults, precedence, and diagnostics.
doc/build_apps/run_app.rst	Documents sandbox default behavior.
CMakeLists.txt	Installs the schema and registers tests.
CHANGELOG.md	Records the user-facing change.

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.

[Amaury Chamayou (achamayou)]

Copilot resolve the merge conflicts in this pull request

[Copilot]

Copilot resolve the merge conflicts in this pull request

Resolved the merge conflict with origin/main and pushed merge commit a808eaf53.

[Copilot]

Pull request overview

Copilot reviewed 6 out of 6 changed files in this pull request and generated 1 comment.

[Amaury Chamayou (achamayou)]

Ran tests/sandbox/sandbox.sh --help at base a1e231e and PR head 2a1bc82 in the same WSL environment. The working directory was held constant to avoid an unrelated checkout-path difference.

--- main (a1e231e): ./tests/sandbox/sandbox.sh --help
+++ PR #8176 (2a1bc82): ./tests/sandbox/sandbox.sh --help
@@ -59,6 +59,7 @@
                         [--redirection-kind {node-by-role,static-address}]
                         [--primary-hostname PRIMARY_HOSTNAME]
                         [--backup-hostname BACKUP_HOSTNAME]
+                        [--use-defaults-from-host-config]
 
 options:
   -h, --help            show this help message and exit
@@ -72,7 +73,8 @@
                         to be started manually (default: [])
   --log-level {trace,debug,info,fail,fatal}
                         Runtime log level (default: info)
-  --log-format-json     Set node stdout log format to JSON (default: False)
+  --log-format-json     If ``Json``, node logs will be formatted as JSON
+                        (default: False)
   -p, --package PACKAGE
                         The enclave package to load (e.g., logging) (default:
                         None)
@@ -85,27 +87,36 @@
                         Path to JSON file with JWT issuer definition (default:
                         [])
   --jwt-key-refresh-max-response-size JWT_KEY_REFRESH_MAX_RESPONSE_SIZE
-                        Maximum response body size accepted when fetching JWT
-                        issuer OpenID metadata and JWKS (default: 1MB)
+                        Maximum response body size accepted when fetching
+                        OpenID metadata and JWKS for JWT issuer auto-refresh
+                        (default: 1MB)
   -o, --network-only    Only start the network, do not run the client, and
                         wait. (default: False)
   --sig-tx-interval SIG_TX_INTERVAL
-                        Number of transactions between signatures (default:
-                        5000)
+                        Number of transactions after which a signature
+                        transaction is automatically generated (default: 5000)
   --sig-ms-interval SIG_MS_INTERVAL
-                        Milliseconds between signatures (default: 100)
+                        Maximum duration after which a signature transaction
+                        is automatically generated (default: 1000)
   --memory-reserve-startup MEMORY_RESERVE_STARTUP
                         Reserve this many bytes of memory on startup, to
                         simulate memory restrictions (default: None)
   --election-timeout-ms ELECTION_TIMEOUT_MS
-                        Raft maximum election timeout for each node in the
-                        network (default: 4000)
+                        Maximum timeout (time string) after which backup nodes
+                        that have not received any message from the primary
+                        node (or voted for a candidate) will trigger a new
+                        election. This timeout is also used by candidates to
+                        restart unsuccessful elections. This should be set to
+                        a significantly greater value than 'message_timeout'
+                        plus the expected network delay (default: 5000)
   --consensus-update-timeout-ms CONSENSUS_UPDATE_TIMEOUT_MS
-                        Raft maximum timeout before primary sends updates
-                        (default: 100)
+                        Maximum interval (time string) at which the primary
+                        node sends messages to backup nodes to maintain its
+                        primary-ship. This should be set to a significantly
+                        lower value than 'election_timeout' (default: 100)
   --worker-threads WORKER_THREADS
-                        number of worker threads inside the enclave (default:
-                        0)
+                        Number of additional threads processing incoming
+                        client requests (default: 0)
   --pdb                 Break to debugger on exception (default: False)
   --workspace WORKSPACE
                         Temporary directory where nodes store their logs,
@@ -122,8 +133,8 @@
                         Throws if test requirements are not met, skip test
                         otherwise (default: True)
   --subject-name SUBJECT_NAME
-                        Subject Name in node certificate, eg. CN=CCF Node
-                        (default: CN=CCF Node)
+                        Subject name to include in node certificate (default:
+                        CN=CCF Node)
   --subject-alt-names SUBJECT_ALT_NAMES
                         Subject Alternative Name in node certificate. Can be
                         either iPAddress:xxx.xxx.xxx.xxx, or
@@ -132,7 +143,10 @@
                         Curve to use for member and user identities (default:
                         secp384r1)
   --join-timer-s JOIN_TIMER_S
-                        Timer period when trying to join an existing network
+                        Interval (time string) at which the node sends join
+                        requests to the existing service. This should be less
+                        than the value of 'consensus.election_timeout' set on
+                        the primary node of the existing service to join
                         (default: 1)
   --initial-member-count INITIAL_MEMBER_COUNT
                         Number of members when initializing the network
@@ -158,49 +172,69 @@
                         On recovery, maximum timeout (s) while reading the
                         ledger (default: 30)
   --ledger-chunk-bytes LEDGER_CHUNK_BYTES
-                        Size (bytes) at which a new ledger chunk is created
-                        (default: 20KB)
+                        Minimum size (size string) of the current ledger file
+                        after which a new ledger file (chunk) is created
+                        (default: 5MB)
   --ledger-max-transaction-bytes LEDGER_MAX_TRANSACTION_BYTES
-                        Maximum total serialised ledger entry size, including
-                        its header (size string) (default: 32MB)
+                        Maximum total serialised size (size string) of a
+                        transaction written to the ledger. Reserved internal
+                        signature transactions are exempt. This covers the
+                        whole ledger entry: the fixed 8-byte ledger entry
+                        header, the ledger encryption header, public domain
+                        size field, public domain and encrypted private
+                        domain. Must be smaller than 'memory.max_msg_size', by
+                        at least the ring-buffer range response overhead, so
+                        that a single ledger entry can be read back from the
+                        host (default: 32MB)
   --snapshot-tx-interval SNAPSHOT_TX_INTERVAL
-                        Number of transactions between two snapshots (default:
-                        10)
+                        Number of transactions after which a snapshot is
+                        automatically generated (default: 10000)
   --snapshot-min-tx-interval SNAPSHOT_MIN_TX_INTERVAL
-                        Minimum number of transactions before a time-based
-                        snapshot can trigger (default: 2)
+                        Minimum number of transactions that must have elapsed
+                        since the last snapshot before a time-based snapshot
+                        can be triggered. Has no effect if time_interval is
+                        not set. If lower than 2 while time_interval is
+                        enabled, snapshots will be triggered indefinitely.
+                        (default: 2)
   --snapshot-time-interval SNAPSHOT_TIME_INTERVAL
                         Time interval after which a snapshot should be
-                        triggered (e.g. 30s, 5min) (default: 0s)
+                        triggered, provided more than min_tx_count
+                        transactions have elapsed since the last snapshot. Set
+                        this to 0s to disable time-based snapshotting.
+                        (default: 0s)
   --max-open-sessions MAX_OPEN_SESSIONS
-                        Soft cap on max open TLS sessions on each node
-                        (default: 1000)
+                        The maximum number of active client sessions on that
+                        interface after which clients will receive an HTTP 503
+                        error (default: 1000)
   --max-open-sessions-hard MAX_OPEN_SESSIONS_HARD
-                        Hard cap on max open TLS sessions on each node
-                        (default: 1010)
+                        The maximum number of active client sessions on that
+                        interface after which clients sessions will be
+                        terminated, before the TLS handshake is complete. Note
+                        that its value must be greater than the value of
+                        ``max_open_sessions_soft`` (default: 1010)
   --jwt-key-refresh-interval-s JWT_KEY_REFRESH_INTERVAL_S
-                        JWT key refresh interval in seconds (default: 1800)
+                        Interval at which JWT keys for issuers registered with
+                        auto-refresh are automatically refreshed (default:
+                        1800)
   --common-read-only-ledger-dir COMMON_READ_ONLY_LEDGER_DIR
                         Location of read-only ledger directory available to
                         all nodes (default: None)
-  --curve-id {0,1}      Elliptic curve to use as for node and network
-                        identities (default: 0)
+  --curve-id {0,1}      Elliptic curve to use for node identity key (default:
+                        0)
   --ccf-version CCF_VERSION
                         CCF version of local checkout (default: None)
   --initial-node-cert-validity-days INITIAL_NODE_CERT_VALIDITY_DAYS
-                        Initial validity period in days for certificates of
-                        nodes before the first certificate renewal (default:
-                        1)
+                        Initial validity period (days) for node certificate
+                        (default: 1)
   --initial-service-cert-validity-days INITIAL_SERVICE_CERT_VALIDITY_DAYS
-                        Initial validity period in days for service
-                        certificate before the first certificate renewal
+                        Initial validity period (days) for service certificate
                         (default: 1)
   --maximum-node-certificate-validity-days MAXIMUM_NODE_CERTIFICATE_VALIDITY_DAYS
-                        Maximum allowed validity period in days for
-                        certificates of trusted nodes (default: 365)
+                        The maximum number of days allowed for node
+                        certificate validity period (default: 365)
   --maximum-service-certificate-validity-days MAXIMUM_SERVICE_CERTIFICATE_VALIDITY_DAYS
-                        Maximum allowed validity period in days for service
-                        certificate (default: 365)
+                        The maximum number of days allowed for service
+                        certificate validity period (default: 365)
   --reconfiguration-type {OneTransaction,TwoTransaction}
                         Reconfiguration type (default: OneTransaction)
   --previous-service-identity-file PREVIOUS_SERVICE_IDENTITY_FILE
@@ -209,15 +243,23 @@
                         Absolute path to node JSON configuration file
                         (default: None)
   --max-http-body-size MAX_HTTP_BODY_SIZE
-                        Maximum allowed size for body of single HTTP request
-                        (default: 1048576)
+                        Maximum size (size string) of a single HTTP request
+                        body. Submitting a request with a payload larger than
+                        this value will result in the client session being
+                        automatically closed (default: 1048576)
   --max-http-header-size MAX_HTTP_HEADER_SIZE
-                        Maximum allowed size of single header in single HTTP
-                        request (default: 16384)
+                        Maximum size (size string) of a single HTTP request
+                        header (key or value). Submitting a request with a
+                        header larger than this value will result in the
+                        client session being automatically closed (default:
+                        16384)
   --max-http-headers-count MAX_HTTP_HEADERS_COUNT
-                        Maximum number of headers in single HTTP request
+                        Maximum number of headers in a single HTTP request.
+                        Submitting a request with more headers than this value
+                        will result in the session being automatically closed
                         (default: 256)
-  --http2               Enable HTTP/2 for all interfaces (default: False)
+  --http2               The application protocol used by all sessions on this
+                        interface (default: False)
   --snp-endorsements-servers SNP_ENDORSEMENTS_SERVERS
                         Servers used to retrieve attestation report
                         endorsement certificates (AMD SEV-SNP only) (default:
@@ -225,10 +267,13 @@
   --forwarding-timeout-ms FORWARDING_TIMEOUT_MS
                         Timeout for forwarded RPC calls (in milliseconds)
                         (default: 3000)
-  --tick-ms TICK_MS     Tick period (in milliseconds) (default: 1)
+  --tick-ms TICK_MS     Interval at which the enclave time will be updated by
+                        the host (modify with care!) (default: 10)
   --max-msg-size-bytes MAX_MSG_SIZE_BYTES
-                        Maximum message size (bytes) allowed on the ring
-                        buffer (default: 64MB)
+                        Maximum size (size string) for a message sent over the
+                        ringbuffer. Messages may be split into multiple
+                        fragments, but this limits the total size of the sum
+                        of those fragments (default: 64MB)
   --gov-api-version GOV_API_VERSION
                         api-version to be used for accessing /gov endpoints
                         (default: latest)
@@ -261,3 +306,6 @@
   --backup-hostname BACKUP_HOSTNAME
                         The backup hostname to set when --redirection-kind is
                         set to static-address (default: None)
+  --use-defaults-from-host-config
+                        Use defaults and descriptions from the cchost
+                        configuration schema (default: False)