Guides
Run a process
Execute an argv based command and consume ordered output.
The sandbox must be ready. OpenMetal runs processes asynchronously and persists ordered stdout and stderr events.
const process = await metal.processes.create(sandbox.id, {
command: ["node", "app.js", "--port", "8080"],
cwd: "/workspace",
environment: { NODE_ENV: "production" },
timeout_seconds: 300,
max_output_bytes: 10 * 1024 * 1024,
});
for await (const event of metal.processes.events(sandbox.id, process.id)) {
if (event.type === "stdout" || event.type === "stderr") {
const bytes = Uint8Array.from(atob(event.data.data_base64), (value) => value.charCodeAt(0));
// Route bytes to the matching local stream.
}
}Resume output
Events have contiguous positive sequence numbers. Save the last handled sequence and resume from it.
openmetal process events <sandbox-id> <process-id> --after 42The SDK event iterator reconnects finite SSE batches and stops after a terminal event. Process states are queued, running, cancelling, succeeded, failed, cancelled, and timed_out.
Cancel a process
Cancellation depends on provider support:
await metal.processes.cancel(sandbox.id, process.id);openmetal process cancel <sandbox-id> <process-id> --yesRuntime boundary
OpenMetal executes argv arrays. It does not provide an interactive terminal, streaming stdin, SSH, WebSocket, or a general connection API.
See process endpoints and common errors.