commands

Start a background process: a server, a watcher, a long build, an interactive program.

Returns at once with the process. stdinMode 'pipe' keeps standard input open for :write; pty gives it a terminal (and implies input). At most 16 run at once per sandbox.

post/v1/sandboxes/{id}/processes

Request

  • Base URL: https://api.withruntime.com
  • URL: https://api.withruntime.com/v1/sandboxes/{id}/processes
  • Auth: HTTP bearer

Path parameters

idstring required

Resource identifier (UUID).

Headers

Idempotency-Keystring

Replaying the same key with the same request within 24 hours returns the first result and never repeats the effect. A refusal is not kept: a request refused before it ran (no_capacity, busy, a limit) runs afresh when sent again with its key. The SDKs send one automatically; the server makes one when absent and returns it in the idempotency-key response header.

Request body

commandstring

A shell command, run as bash -c "<command>": pipes, &&, redirection and globs work.

argvstring[]

Or the program and its arguments, run without a shell.

cwdstring

Working directory. Default /workspace.

envobject

Environment for this command, merged over the sandbox's. Put secrets here, never in the command line: env is never echoed back.

stdinstring

Text given to the command's standard input, which is then closed.

stdinBase64string

Bytes for standard input, base64.

user'sandbox' | 'root'

Who runs it: the sandbox user (uid 1000, HOME=/workspace), or root, through the sandbox's passwordless sudo with the same environment and PATH and HOME=/root. Saves prefixing every command with sudo.

timeoutMsinteger

Kill it after this long. Default: runs until it exits or the sandbox stops.

stdinMode'closed' | 'pipe'
outputEncoding'utf8' | 'base64'

Response

Success

idstring required
kind'process' required
state'running' | 'exited' | 'killed' | 'timed_out' | 'unknown' required
exitCodeinteger nullable required
commandstring required
user'sandbox' | 'root'

Who it runs as.

cwdstring
ptyboolean
outputEncoding'utf8' | 'base64'
stdinOpenboolean

Input is still open for :write.

stdinOffsetinteger

Bytes of input accepted so far.

startedAtstring date-time required
endedAtstring date-time nullable
timeoutMsinteger nullable
outputBytesinteger
firstOffsetinteger

The oldest byte still kept.

replayedboolean

Changes

No recorded changes to this operation across all 1 revision of this API.