Run commands

Use run for bounded tasks. It returns the command’s exit code, stdout, stderr, and duration.

Run a script

curl --fail-with-body -sS \
  -H "Authorization: Bearer $WISPS_TOKEN" \
  -H 'Content-Type: application/json' \
  "$WISPS_URL/v1/wisps/$WISP_NAME/run" \
  -d '{"script":"echo hello","timeout_seconds":60}'

Use cmd for an argument array, such as ["python3", "main.py"], or script for /bin/sh -c. Use dir to choose a working directory relative to the user’s home, and env to supply environment variables.

Read the result

A command’s nonzero exit code is still a successful HTTP 200 response. Check exit_code, timed_out, stdout_truncated, and stderr_truncated in your application.

An invalid request or a program that cannot start returns HTTP 400. An ambiguous connection failure does not establish whether a command ran; check its effects before retrying.

Time and output limits

The default command timeout is 60 seconds; the standard maximum is 900 seconds. The default output limit is 1 MiB per stream, with a standard maximum of 16 MiB. Your provider may configure different ceilings.

At the timeout, the command is killed and the result sets timed_out. Output beyond the cap is dropped. Use encoding: "base64" for binary output. Disconnecting a run request kills the command.

Stream output

Send Accept: text/event-stream to receive stdout and stderr events followed by exit. The SDKs expose RunStream (Go), run_stream (Python), and runStream (TypeScript).

For a terminal or detachable background work, use sessions.