Process Runtime

The agent-native process runtime lets you spawn, attach to, and manage long-lived remote processes directly on target hosts. Unlike SSH-based nefia exec (which runs one-shot commands), the process runtime provides persistent process handles that survive operator disconnects and support interactive features like PTY allocation and stdin piping.

When to Use the Process Runtime

Prerequisites

The process runtime requires nefia-agent with runtime support enabled. The runtime server listens on port 7222 (TCP) on the VPN-local address and is only reachable through the WireGuard tunnel.

CLI Usage

All nefia proc commands require either --host or --session to identify the target.

Spawning a Process

# Run a long build in the background
nefia proc spawn --host build-server --detach -- make -j8 all
 
# Spawn with PTY for interactive use
nefia proc spawn --host dev-box --tty -- bash -l
 
# Set working directory and environment
nefia proc spawn --host web-1 --cwd /var/www/app --detach -- npm run build

Flags:

Listing Processes

# List all processes on a host
nefia proc list --host build-server
 
# Filter by state
nefia proc list --host build-server --state running

Output shows process ID, PID, state, control mode, TTY flag, and command.

Inspecting a Process

nefia proc inspect --host build-server proc_01H...

Returns full metadata including buffered stdout/stderr (last 256 KB per stream), exit code, and timing information.

Attaching to Output

# Read current buffered output
nefia proc attach --host build-server proc_01H...
 
# Follow output in real-time until process exits
nefia proc attach --host build-server --follow proc_01H...
 
# Follow with a timeout
nefia proc attach --host build-server --follow --wait 5m proc_01H...

Sending Input

# Write data to stdin
nefia proc stdin --host dev-box proc_01H... --data "yes\n"
 
# Close stdin (signals EOF to the process)
nefia proc stdin --host dev-box proc_01H... --close

Sending Signals

# Graceful termination
nefia proc signal --host build-server proc_01H... --signal term
 
# Force kill
nefia proc signal --host build-server proc_01H... --signal kill

Supported signals: term, kill, int, hup (Unix); term, kill, int, break (Windows). On Windows, int/break use a 3-stage fallback: CTRL_BREAK_EVENT via console attach, then \x03 to stdin, then error. For ConPTY processes, \x03 is translated to CTRL_C_EVENT natively.

Waiting for Completion

# Block until the process exits
nefia proc wait --host build-server proc_01H...
 
# Wait with timeout
nefia proc wait --host build-server --timeout 10m proc_01H...

Resizing TTY

nefia proc resize --host dev-box proc_01H... --rows 50 --cols 120

Deleting Process Metadata

nefia proc delete --host build-server proc_01H...

Removes metadata for an exited process. Running processes cannot be deleted.

MCP Tools

The process runtime exposes 9 MCP tools for AI agent integration:

AI Agent Workflow Example

{
  "tool": "nefia.proc.spawn",
  "arguments": {
    "host_id": "build-server",
    "command": "make -j8 release",
    "cwd": "/home/deploy/app",
    "detach": true
  }
}

{
  "tool": "nefia.proc.attach",
  "arguments": {
    "host_id": "build-server",
    "process_id": "proc_01H...",
    "stdout_offset": 0
  }
}

{
  "tool": "nefia.proc.wait",
  "arguments": {
    "host_id": "build-server",
    "process_id": "proc_01H..."
  }
}

{
  "tool": "nefia.proc.delete",
  "arguments": {
    "host_id": "build-server",
    "process_id": "proc_01H..."
  }
}

Process States

Each process transitions through these states:

Control Modes

After an agent restart, processes may transition to a reduced control mode:

Output Buffering

The runtime retains the last 256 KB of stdout and stderr per process in a ring buffer. When the buffer overflows, older data is dropped and the dropped_bytes field in attach responses indicates how much was lost.

Use offset-based reading to avoid re-reading data:

{
  "tool": "nefia.proc.attach",
  "arguments": {
    "host_id": "build-server",
    "process_id": "proc_01H...",
    "stdout_offset": 65536,
    "stderr_offset": 0
  }
}

For TTY-backed processes, stdout contains the merged terminal stream and stderr is empty.

Spool File Caps

Process output is written to spool files on disk (separate from the in-memory ring buffer). The max_spool_bytes parameter limits spool growth per stream:

When a spool file exceeds the cap, the runtime compacts it by keeping the most recent 75% of data. Compaction is best-effort — the file may briefly exceed the limit between writes.

Resource Limits

Spawned processes can be constrained with OS-level resource limits via the limits parameter on proc.spawn. Limits are enforced using setrlimit on Unix and Job Objects on Windows.

Merge semantics: 0 = use agent default, -1 = explicitly unlimited (overrides agent default), > 0 = use specified value.

# CLI: resource limits are configured at the agent level
# MCP: per-spawn override via the limits parameter

{
  "tool": "nefia.proc.spawn",
  "arguments": {
    "host_id": "build-server",
    "command": "make -j8",
    "limits": {
      "max_memory_bytes": 1073741824,
      "max_cpu_seconds": 300
    },
    "max_spool_bytes": 536870912
  }
}

Process Retention

Exited process metadata is retained for 24 hours by default. After the retention window, the garbage collector removes the process and its buffered output. Running processes are never garbage collected.

Security

• Network isolation — The runtime listener binds only to the VPN-local address. It is never reachable from LAN or public networks.
• HMAC-SHA256 authentication — Each connection performs a nonce-based handshake using a shared key derived from the VPN trust relationship.
• Policy enforcement — proc.spawn, proc.stdin, proc.signal, and proc.delete are subject to the operator-side policy engine. Role-based rules can allow proc.list but deny proc.spawn.
• Audit logging — All process operations (proc_spawn, proc_attach, proc_stdin, proc_signal, proc_wait, proc_exit) are recorded in the append-only audit log.
• Approval workflow — When MCP approval is enabled, proc.spawn, proc.stdin, proc.signal, proc.resize, and proc.delete require human approval.

Related