Agent Runtime Limits

The Ordyn agent applies local limits to instruction history, process execution, downloaded artifacts, and Windows user interaction. These limits keep endpoint work predictable and affect which diagnostic details remain available after an instruction finishes.

Local instruction history

The agent keeps a short local history for status reporting and recovery. Each entry contains:

• instruction ID and capability
• receipt, issue, and expiration times
• verification and execution status
• the signed payload hash
• job, target, task, workflow, and display identifiers when supplied

The submitted instruction payload is not stored in local instruction history. Script content, resolved credentials, secret redaction values, unlock PINs, and signed download URLs therefore cannot be recovered from the local agent status output after execution.

Instruction results and audit information reported to Ordyn remain available according to the server retention settings.

Process output

For blocking endpoint scripts and workflow commands, the agent retains stdout and stderr independently. The default limit is 1 MiB for each stream. Output beyond the limit is discarded while the agent continues draining the process, so a process cannot block because its retained output is full. Discarded output is not written to a recovery spool and cannot be retrieved later.

Docker Compose configuration discovery uses the same retained-output limit. If the resolved Compose JSON exceeds the limit, the action fails with compose_config_too_large rather than parsing a partial document. Diagnostic stderr is retained only up to the configured limit.

Results include stdout_total_bytes, stderr_total_bytes, stdout_truncated, and stderr_truncated. The byte totals describe everything emitted on each captured stream; stdout and stderr contain only the retained prefixes. A JSON-output script whose stdout exceeds the limit generally fails JSON validation because the retained document is incomplete.

The local agent configuration can change the retained-byte limit:

[execution]
output_limit_bytes = 1048576

The value must be at least one byte. It applies to newly started processes and does not recover output already discarded.

Process cancellation

On Linux, each blocking script runs in a dedicated process group. Cancellation and timeout first send SIGTERM to the whole group. Processes that remain after the default five-second grace period receive SIGKILL.

The grace period can be changed in the local agent configuration, including setting it to zero for immediate forced termination:

[execution]
termination_grace_seconds = 5

A descendant that deliberately creates a different process group or session is outside the original script process group and may continue running. Processes left behind by a script that completes normally are not terminated. Non-blocking Windows scripts are detached and are not tracked or stopped by job cancellation.

Artifact downloads

Agent-managed package, OS image, stored-file, agent-update, WinPE, and driver-bundle downloads use HTTPS. HTTP is not supported. Redirects are accepted only when they keep the same host, port, and allowed scheme as the original request. Connection setup is limited to 10 seconds, a transfer fails after 60 seconds without readable data, and one request can run for at most four hours. The job or instruction timeout can end it sooner.

The agent requires the destination filesystem to have room for the declared file size plus 256 MiB of free-space headroom by default. It writes into a private temporary file and stops reading as soon as the declared size would be exceeded. The completed file must match both the exact byte count and the signed SHA-256 checksum. The agent then syncs the file and moves it into place atomically. A failed, cancelled, oversized, or corrupt download does not publish a partial file and does not replace an existing file.

Package and OS-image workflow steps reuse a previously downloaded file only when its size and SHA-256 checksum both still match. Rechecking a large existing file reads the complete file and can add time before the next workflow step starts.

Signed download query parameters and URL credentials are omitted from agent log messages. Artifact identifiers and file names must be single safe path components; values containing traversal separators, control characters, drive separators, or reserved Windows names are rejected.

Cache-file and agent-release manifests are limited to 1 MiB. A detached agent-release signature response is limited to 64 KiB.

On Linux, agent artifact directories use mode 0700, downloaded files use mode 0600, and the system service runs with UMask=0077. On Windows, the shared artifact root grants full control to SYSTEM and Administrators and read/execute access to local Users so user-context workflow processes can read their inputs.

Archive extraction

Staged package ZIPs and WinPE driver bundles are rejected when they exceed any of these limits:

• 100,000 entries
• 50 GiB total expanded size
• 50 GiB for one expanded entry
• 32 path components for one entry
• a 100:1 expansion ratio for an entry of at least 1 MiB

Unsafe paths, duplicate paths, and symbolic-link entries are rejected. The destination filesystem must also have room for the declared expanded size plus 256 MiB of headroom. Extraction takes place in a private temporary directory and becomes visible only after every entry succeeds. Existing extracted content is not replaced by an invalid or incomplete archive.

Retrieved files and directories

A retrieved file can be at most 15 GiB by default. A retrieved directory can contain at most 100,000 non-symlink entries, use at most 32 path components, and contain at most 15 GiB of regular-file data. Symbolic links are skipped when a directory archive is created. The completed ZIP must also be no larger than 15 GiB. The destination filesystem must have room for the source data plus 256 MiB of free-space headroom by default. The agent streams files into the archive and removes the private temporary archive if creation or validation fails.

Configuring artifact limits

The local agent configuration controls upload, archive, and free-space limits. These defaults apply when the section is omitted:

[artifacts]
max_upload_bytes = 16106127360
max_archive_entry_count = 100000
max_archive_expanded_bytes = 53687091200
max_archive_entry_bytes = 53687091200
max_archive_path_depth = 32
max_archive_compression_ratio = 100
download_free_space_reserve_bytes = 268435456
archive_free_space_reserve_bytes = 268435456

Every value must be at least 1, and max_archive_entry_bytes cannot exceed max_archive_expanded_bytes. max_upload_bytes applies to collected and retrieved files and to completed retrieval archives. The archive entry-count and path-depth settings apply to both directory retrieval and archive extraction. Expanded-size, per-entry, and compression-ratio settings apply to archive extraction. The archive free-space reserve applies when the agent creates a retrieval archive or extracts an archive.

The values can be raised or lowered to match endpoint capacity and product requirements. Larger limits can use substantially more disk space, memory, transfer time, and job runtime. Restart the agent after changing its local configuration.

Windows tray communication

Windows tray commands use local named pipes and cannot be accepted from another computer. Each pipe permits SYSTEM and only the user SID assigned to its target interactive session. Before exchanging a command, the agent checks the tray process ID, token SID, Windows session ID, and executable path. The tray performs the corresponding checks for the SYSTEM agent process in session 0. A connection is rejected when any identity detail cannot be resolved or does not match.

Each connection carries one service-to-tray command and one correlated tray-to-service reply. Both messages include the current protocol version, an explicit direction, and a new random nonce. Replayed replies, replies from another connection, messages in the wrong direction, and serialized messages larger than 64 KiB are rejected.

Prompt-window and job-activity state is published atomically. SYSTEM and Administrators have full access; the exact accounts for active interactive sessions have read access. These files describe the current endpoint-wide tray state and are not separate per-session histories. All active interactive sessions can therefore read the same current state while they remain active. If the agent cannot resolve the exact active-session SIDs, it does not broaden access to Authenticated Users or local Users, and the affected tray update or prompt can be unavailable.

The Windows shutdown handoff uses a new service-instance event name each time the service starts. Only SYSTEM can access the event, and the runtime child receives its name directly from the service host. The service does not start the runtime child when this protected handoff cannot be initialized.

Instruction replay synchronization

On each agent connection, Ordyn reconciles the endpoint's signed instruction sequence before the agent accepts new instructions. This normally completes automatically. While synchronization is in progress, the endpoint stays connected but instruction controls are unavailable. The endpoint page shows that instruction delivery is paused.

The agent reports its endpoint-bound sequence, its replay-state health, durable executions, and up to 64 payload-free acceptance receipts. Each receipt contains the instruction ID, sequence, capability, timestamps, and whether dispatch had started. The agent stores a receipt before dispatch and clears it after responsibility for the instruction is durably recorded. If the 64-receipt limit is reached, further instructions are rejected until receipts can be reconciled.

The initial synchronization waits up to 30 seconds and can hold at most 64 incoming JSON or text messages with a combined encoded size of 64 MiB. A missing response, an invalid signed response, or a message buffer that exceeds either limit closes the connection so the agent can reconnect and try again. Missing, empty, corrupt, or endpoint-mismatched replay state is not trusted as an instruction baseline. Ordyn supplies its signed server baseline automatically when no issued instruction has an ambiguous outcome.

Restoring an enrolled device from a virtual-machine snapshot or filesystem backup can also restore an older replay sequence that is still structurally valid. The agent can synchronize automatically from that older value. Until it accepts a newly issued instruction with a higher sequence, an earlier signed instruction above the restored sequence could be accepted again if it is delivered again before its signed expiration time. Unsigned, modified, and expired instructions remain rejected. Avoid restoring enrolled agent state from snapshots or backups; re-enroll the device before resuming instruction delivery when this limited replay window is unacceptable.

Ordyn can automatically retry a generated preparation step when replay synchronization finds that its outcome is ambiguous or when the reconnected agent reports that a restart interrupted it. This recovery applies to package downloads, staged package archive extraction, OS image downloads, and generated Windows desktop-readiness waits. These operations share a limit of three recovery attempts within 30 minutes. The replacement instruction is delivered only after the current connection has completed replay synchronization.

If another issued instruction remains ambiguous, or the automatic retry limit is reached, the endpoint page shows Replay recovery required and keeps instruction delivery paused. A user with the Update endpoints permission can select Recover replay protection. The confirmation shows how many ambiguous issued instructions will be failed. Recovery records each still-issued ambiguous instruction as failed with agent_replay_state_recovery_forced, sends the current signed baseline to the same agent connection, and waits for that connection to acknowledge it before instruction delivery resumes.

Manual recovery does not rerun an ambiguous instruction and does not lower a healthy agent sequence. Review the affected job and instruction history before recovering because an external side effect may already have occurred.

Instruction supervision and restart recovery

Ordinary background instructions use the expiration time in the signed instruction as their execution limit. For job work, Ordyn derives that expiration from the effective configured task timeout; instructions without a task-specific timeout use the applicable server-side instruction timeout. An instruction that is already expired when the agent is ready to start it does not run.

When the signed expiration time is reached, the agent requests cancellation and allows ten seconds for the task to stop. If the task remains active after that grace period, the agent reports task_timeout but keeps the execution quarantined until its underlying work stops. Ordyn records the job task as timed out and applies its normal continue-on-error and failure-follow-up behavior; otherwise, the target is also timed out.

While an execution is quarantined, the agent continues treating the endpoint as busy for primary work, or the affected capability as busy for parallel control work. The agent reports the active execution as terminating_after_failure and does not start conflicting work on the endpoint. A late result or late progress update from the execution is discarded, so the instruction still has one terminal result. The same behavior applies after an accepted instruction.cancel; a task that remains active after ten seconds reports task_cancellation_grace_exceeded and stays quarantined until it stops. An unexpected task panic is converted to a failed result with task_panicked; panic details are not included in the instruction result.

The agent stores a small execution lease before an ordinary task starts. If the agent process stops after the lease is stored but before the task is finalized, the next startup reports the instruction as failed with agent_runtime_restarted and does not rerun that instruction itself. An acceptance receipt left before dispatch reports agent_runtime_restarted_before_execution; a receipt left after dispatch began reports agent_runtime_restarted_during_dispatch. Ordyn can issue a replacement instruction for the generated preparation steps listed above after replay synchronization; other interrupted tasks follow normal failure handling. If the process stops again before a recovered failure is durably cleared, the failure report can be sent again with the same instruction ID. Scripts and APT updates that were explicitly submitted with durable handoff settings use their separate durable runner and result spool instead of ordinary-task restart recovery. Before durable execution starts, the agent rechecks the signed instruction's signature, target, payload hash, and expiration. Expired, modified, or unsupported handoff data fails without running the payload.

Cancellation cannot guarantee that an external side effect is reversible. A command, installer, remote API call, detached child process, or blocking operation that does not observe cancellation may already have completed work or may continue after the terminal result is reported. Quarantine prevents conflicting agent work from overlapping it, but it does not forcibly stop work outside the agent's process-containment controls.

Local state persistence

Identity, certificate-transition, execution-lease, pending-upgrade, cleanup, and shutdown-workflow changes use an acknowledged persistence barrier. The agent does not start ordinary instruction work until its execution lease has crossed that barrier. Replay sequence state uses its own acknowledged store.

Connection timestamps, message previews, local instruction-history updates, tray activity, and diagnostics are volatile state. The agent coalesces these updates for up to 250 milliseconds and checkpoints them without creating a new recovery generation. A crash or power loss can therefore lose the newest volatile update without losing the last acknowledged identity or workflow state.

Acknowledged identity and workflow changes are committed into an immutable numbered recovery generation. Each generation contains a complete state snapshot with SHA-256 hashes, and the agent publishes it only after every file is complete. Volatile checkpoints are used only with the recovery generation for which they were recorded; an invalid or mismatched checkpoint is ignored in favor of that generation's snapshot. A reader that overlaps publication retries for up to approximately one second. The agent retains the current and previous valid generations. A complete generation that was written but not published is ignored and cleaned up when the agent next obtains the state writer lock.

If the selected generation is incomplete or corrupt, state-loading commands fail with agent_state_generation_corrupt and exit code 78. The agent does not automatically select a different generation. This keeps recovery explicit when the previous generation may omit a recently acknowledged execution lease, identity change, or workflow update.

Stop the agent service before inspecting or repairing generations. List the retained generations and their validity:

ordyn-agent repair-state

Review the current, valid, endpoint_id, and created_at values in the JSON output. The output also includes replay_state, including its endpoint identity, health, high-water marks, and pending payload-free acceptance receipts. Promote a retained valid generation only when its endpoint identity is correct and losing state recorded after that generation is acceptable:

ordyn-agent repair-state --generation 42

The command refuses to promote an invalid generation. It also refuses promotion while replay state is missing, empty, corrupt, or belongs to another endpoint. If state-generation recovery must proceed before replay state can be trusted, use:

ordyn-agent repair-state --generation 42 --allow-untrusted-replay-state

This option permits only the selected state-generation promotion. It does not mark replay state as trusted, reset the instruction sequence, or allow instructions to bypass connection synchronization. After restart, Ordyn supplies a signed baseline automatically when reconciliation is unambiguous. If issued instructions remain ambiguous, use Recover replay protection on the endpoint page after reviewing them.

Restart the service after a successful promotion. If no retained generation is valid, restore a matching state-directory backup or re-enroll the endpoint.

Only one agent runtime, enrollment operation, or state reset can hold the state-directory writer lock. A second writer exits without changing state. Read-only status inspection remains available. A stale lock file after a crash is harmless because ownership is enforced by the operating system, not by the file contents.

Capability availability

The agent accepts only capabilities in its built-in registry. The registry fixes each capability's platform availability, scheduling class, cancellation support, payload decoder, and safe failure metadata for that agent version. Unknown capabilities and capabilities for another operating system fail before execution.

Platform service providers are created once and reused for the lifetime of the agent process. A local configuration change that affects provider construction takes effect after the agent restarts.

Agent downgrade

Agent state is forward-only. Downgrading an installed agent while reusing its existing state directory is unsupported. Restore the matching agent version or enroll with a new state directory when downgrade recovery is required.

Related pages

• Enrollment
• Jobs
• Scripts
• Package workflow steps
• OS image workflow steps