Skip to main content

Start a background process

Without callbacks, background commands start through the REST exec endpoint and return once the guest process has a PID. The command continues running inside the machine until it exits, is killed, or the machine is paused or destroyed.

Fetch logs and stop

Background command objects also expose kill():
BackgroundCommand also supports:
  • server.get_logs() to fetch stdout, stderr, interleaved output, and optional exit_code.
  • server.wait() to block until exit. If there is no live WebSocket attached, it polls the process list and then fetches logs.
  • server.disconnect() to close a live stream without killing the process.
  • Iteration over (stdout_chunk, stderr_chunk, None) tuples; this polls logs for new output.

Live background output

Pass callbacks with background=True when you want the process to keep running and stream output immediately:
This path uses the exec WebSocket to start the process and attach a reader to the returned PID. Live background streaming is not a plain REST call: it runs over GET /v1/machines/{id}/ws?channel=exec, so there is no curl equivalent. Use the REST GET /v1/machines/{id}/processes/{pid}/logs endpoint to fetch captured output after the process has started.

Use with preview URLs

For web servers, bind to 0.0.0.0 inside the machine so preview URLs can reach the process.