Port

Processes

Open an Erlang port from a program.

spawn takes a port from a port module (lines or feed) so the command is tied to that module. Return it from init. Incoming ports are subscriptions (lines GotLine); outgoing ports are commands (feed text). Subscribe with onExit to learn the OS exit status (requires exitStatus in the spawn settings).

On the Erlang target, update runs commands before the next subscription sync. A short-lived child can exit in that window. The runtime buffers the exit status until onExit attaches, so this pattern is safe:

1. Set a running flag and return Port.spawn from the same update 2. Gate Port.onExit (and the port's data sub) on that flag in subscriptions

Subscribing to onExit before any successful Port.spawn for that module still fails with port_not_spawned.

For an external MCP server over stdio, use Mcp. To be an MCP server in this process, use Mcp.Server. For ACP agents over stdio (agent acp, acp-bridge, …), use Acp. Prefer those over framing JSON-RPC by hand on a raw port.

When a port is stopped (unsubscribe / replace / ACP·MCP disconnect), the runtime SIGTERM/SIGKILL’s the OS process **tree** on Unix — not only the direct child — so wrappers like uvx do not leave orphan grandchildren.

Types

Setting

type Setting = Setting

One open_port setting.

Examples

Port.line 1024

Values

spawn

spawn : a -> String -> List Setting -> Cmd msg

Open command for the port module that declares portFun.

Examples

Port.spawn lines "/usr/bin/wc" [ Port.args [ "-l" ], Port.exitStatus ]

onExit

onExit : a -> (Int -> msg) -> Sub msg

Subscribe to the OS exit status of a spawned port. Uses the same port function as spawn to identify the module; does not open a second process. Pass exitStatus in the spawn settings or the status never arrives.

If the OS process exits before this subscription attaches (commands flush before subscription sync), the runtime still delivers exactly one exit for that spawn once onExit is subscribed.

Examples

Port.onExit lines GotExit

binary

binary : Setting

Deliver port data as binaries.

Examples

Port.binary

stream

stream : Setting

A stream of bytes. This is the default.

Examples

Port.stream

packet

packet : Int -> Setting

Packet framing of 1, 2, or 4 length bytes.

Examples

Port.packet 4

line

line : Int -> Setting

Deliver one line at a time, up to max bytes.

Examples

Port.line 1024

exitStatus

exitStatus : Setting

Ask the OS process for an exit status.

Examples

Port.exitStatus

eof

eof : Setting

Send a message when the port reaches end of file.

Examples

Port.eof

useStdio

useStdio : Setting

Use stdin and stdout. This is the default.

Examples

Port.useStdio

noUseStdio

noUseStdio : Setting

Do not use stdin and stdout.

Examples

Port.noUseStdio

stderrToStdout

stderrToStdout : Setting

Fold the OS process stderr into stdout.

Examples

Port.stderrToStdout

input

input : Setting

Open the port for input.

Examples

Port.input

output

output : Setting

Open the port for output.

Examples

Port.output

hide

hide : Setting

Hide the OS process window.

Examples

Port.hide

overlap

overlap : Setting

Allow overlapping port_command calls.

Examples

Port.overlap

cd

cd : String -> Setting

Working directory for the OS process.

Examples

Port.cd "/tmp"

env

env : List (String, String) -> Setting

Environment variables for the OS process.

Examples

Port.env [ ("LANG", "C") ]

args

args : List String -> Setting

Arguments for the OS process.

Examples

Port.args [ "-l", "README.md" ]

arg0

arg0 : String -> Setting

argv[0] for the OS process.

Examples

Port.arg0 "wc"