Skip to content
Faber Faber

Run a sequence of steps in one sandbox

POST
/execute

Accepts two request shapes:

  • Envelope (ExecuteRequest): { "steps": [...], "cache": ..., "stop_on_failure": ... }. The response is an ExecuteResponse. SDKs always use this form.
  • Legacy list (StepList): a bare array of steps. The response is a bare StepResultList. When the server cache is enabled, every step of a legacy request is treated as cacheable.

Steps run in order in a shared workspace mounted at /faber. Files written by one step are visible to later steps; /tmp is shared too but is not part of cached layers. Each task gets its own PID namespace, cgroup and seccomp filter.

A step result has the same shape as its step: an object for a single task, an array (in the same order) for a parallel step.

Authorizations

Section titled “Authorizations ”

Request Body required

Section titled “Request Body required ”
One of:
object
steps
required
Array
>= 1 items
One of:
object
cmd
required

Program to run. Resolved through PATH inside the sandbox unless it contains a /.

string
args
Array<string>
env
object
key
additional properties
string
stdin

Written to the task’s standard input, which is then closed

string
files

Workspace-relative path (normalized, no .., no leading /) to file

object
key
additional properties
One of:
string
working_dir

Absolute directory inside the sandbox to start in. Defaults to the workspace /faber.

string
sandbox_profile

Versioned seccomp policy. v2 profiles are allowlists (an unlisted syscall fails with ENOSYS); v1 profiles are denylists. compile_* tasks may create processes and namespace-scoped sockets (compilers, interpreters, build tools); native_* tasks may do neither (running a compiled submission). A denied syscall kills the task with SIGSYS and outcome policy_violation.

string
Allowed values: compile_v2 native_v2 compile_v1 native_v1
cache

Declares the task deterministic so its step may be stored in and replayed from the step cache. A step is cacheable only when every task in it is. Overrides the request-level cache default.

boolean
cache

Default for tasks that do not set cache. Only a leading run of cacheable steps is ever cached: a step after a non-cacheable step depends on state that may differ between runs, so it is always executed. Ignored when the server cache is disabled.

boolean
stop_on_failure

When a step has a task that did not exit with status 0, report the remaining steps as not_started instead of running them.

boolean
Examples

Compile once (cached), then run two test cases in parallel

{
  "stop_on_failure": true,
  "steps": [
    {
      "cmd": "gcc",
      "args": [
        "-O2",
        "-o",
        "main",
        "main.c"
      ],
      "cache": true,
      "files": {
        "main.c": "#include <stdio.h>\nint main(void){int a,b;scanf(\"%d %d\",&a,&b);printf(\"%d\\n\",a+b);return 0;}\n"
      }
    },
    [
      {
        "cmd": "./main",
        "stdin": "1 2\n",
        "sandbox_profile": "native_v2"
      },
      {
        "cmd": "./main",
        "stdin": "40 2\n",
        "sandbox_profile": "native_v2"
      }
    ]
  ]
}

Responses

Section titled “ Responses ”

200

Section titled “200 ”

Every step ran or was skipped. Task failures (non-zero exit, timeouts, OOM, policy violations) are reported per task inside the body, not as HTTP errors.

One of:
object
steps
required
Array
One of:
One of:

The task’s process was created; its exit status and output are reported. A cmd that cannot be executed (not found, not executable) is reported here too: exit_code is 127 and stderr starts with a faber: line saying why.

object
stdout
required
string
stderr
required
string
exit_code
required

Exit status; 128 + signal number when killed by a signal

integer
stats
required
object
memory_peak_bytes
required
integer format: int64
cpu_usage_usec
required
integer format: int64
cpu_nr_throttled
integer format: int64
cpu_throttled_usec
integer format: int64
pids_peak
required
integer format: int64
execution_time_ms
required
integer format: int64
stdout_truncated
required
boolean
stderr_truncated
required
boolean
outcome
required

How the task ended

string
Allowed values: exited signaled timed_out out_of_memory ancestor_out_of_memory pids_limit output_limit policy_violation not_started infrastructure_failure
termination_signal

Signal number that ended the task, if any

integer | null
oom_kill_count
integer format: int64
pids_limit_hit_count
integer format: int64
cleanup_succeeded
boolean
cached

Replayed from the step cache; stats are those of the original run

boolean
cache
required
object
enabled
required

Whether the server’s step cache is enabled

boolean
hits
required

Steps replayed from the cache instead of executed

integer
stored
required

Steps executed by this request and written to the cache

integer

400

Section titled “400 ”

Malformed request body or parameters (invalid_request)

object
error
required

Human-readable message

string
code
required

Stable machine-readable error code. Clients should treat unknown codes as internal_error.

string
Allowed values: invalid_request unauthorized not_found file_not_found payload_too_large limits_exceeded profile_not_allowed capacity_exhausted rate_limited shutting_down cancelled deadline_exceeded sandbox_setup_failed cache_disabled internal_error
Example
{
  "error": "Failed to deserialize the JSON body into the target type: missing field `cmd`",
  "code": "invalid_request"
}

401

Section titled “401 ”

Missing or wrong API key (unauthorized)

object
error
required

Human-readable message

string
code
required

Stable machine-readable error code. Clients should treat unknown codes as internal_error.

string
Allowed values: invalid_request unauthorized not_found file_not_found payload_too_large limits_exceeded profile_not_allowed capacity_exhausted rate_limited shutting_down cancelled deadline_exceeded sandbox_setup_failed cache_disabled internal_error
Example
{
  "error": "Missing or invalid API key",
  "code": "unauthorized"
}

Headers

Section titled “Headers ”
WWW-Authenticate
string

404

Section titled “404 ”

A file_id referenced by a task is not in the file store (code = file_not_found)

object
error
required

Human-readable message

string
code
required

Stable machine-readable error code. Clients should treat unknown codes as internal_error.

string
Allowed values: invalid_request unauthorized not_found file_not_found payload_too_large limits_exceeded profile_not_allowed capacity_exhausted rate_limited shutting_down cancelled deadline_exceeded sandbox_setup_failed cache_disabled internal_error
Example
{
  "error": "File not found: 9f86d081884c7d659a2feaa0c55ad015a3bf4f1b2b0b822cd15d6c15b0f00a08",
  "code": "file_not_found"
}

413

Section titled “413 ”

The body exceeds the configured size limit (payload_too_large)

object
error
required

Human-readable message

string
code
required

Stable machine-readable error code. Clients should treat unknown codes as internal_error.

string
Allowed values: invalid_request unauthorized not_found file_not_found payload_too_large limits_exceeded profile_not_allowed capacity_exhausted rate_limited shutting_down cancelled deadline_exceeded sandbox_setup_failed cache_disabled internal_error
Example
{
  "error": "The request body is larger than the configured limit",
  "code": "payload_too_large"
}

422

Section titled “422 ”

The request is well-formed but not allowed: too many steps or parallel tasks, or uploaded files referenced by its tasks that together exceed the workspace size (limits_exceeded), or a sandbox profile the service does not allow (profile_not_allowed).

object
error
required

Human-readable message

string
code
required

Stable machine-readable error code. Clients should treat unknown codes as internal_error.

string
Allowed values: invalid_request unauthorized not_found file_not_found payload_too_large limits_exceeded profile_not_allowed capacity_exhausted rate_limited shutting_down cancelled deadline_exceeded sandbox_setup_failed cache_disabled internal_error
Examples

Too many steps or parallel tasks

{
  "error": "Task group exceeds configured execution limits",
  "code": "limits_exceeded"
}

429

Section titled “429 ”

The API key has used up its requests (rate_limited). Sent only when the service enables per-key rate limiting (RATE_LIMIT_PER_MINUTE). Retry after the Retry-After header.

object
error
required

Human-readable message

string
code
required

Stable machine-readable error code. Clients should treat unknown codes as internal_error.

string
Allowed values: invalid_request unauthorized not_found file_not_found payload_too_large limits_exceeded profile_not_allowed capacity_exhausted rate_limited shutting_down cancelled deadline_exceeded sandbox_setup_failed cache_disabled internal_error
Example
{
  "error": "Rate limit exceeded for this API key",
  "code": "rate_limited"
}

Headers

Section titled “Headers ”
Retry-After
integer

Seconds until the key may make another request

500

Section titled “500 ”

Sandbox setup or internal failure (sandbox_setup_failed, internal_error)

object
error
required

Human-readable message

string
code
required

Stable machine-readable error code. Clients should treat unknown codes as internal_error.

string
Allowed values: invalid_request unauthorized not_found file_not_found payload_too_large limits_exceeded profile_not_allowed capacity_exhausted rate_limited shutting_down cancelled deadline_exceeded sandbox_setup_failed cache_disabled internal_error
Examples

Sandbox could not be set up

{
  "error": "Sandbox setup failed",
  "code": "sandbox_setup_failed"
}

503

Section titled “503 ”

No execution slots are free (capacity_exhausted), the service is shutting down (shutting_down), or the request was cancelled (cancelled). Retry after the Retry-After header when present.

object
error
required

Human-readable message

string
code
required

Stable machine-readable error code. Clients should treat unknown codes as internal_error.

string
Allowed values: invalid_request unauthorized not_found file_not_found payload_too_large limits_exceeded profile_not_allowed capacity_exhausted rate_limited shutting_down cancelled deadline_exceeded sandbox_setup_failed cache_disabled internal_error
Examples

No free execution slots

{
  "error": "Execution capacity is currently exhausted",
  "code": "capacity_exhausted"
}

Headers

Section titled “Headers ”
Retry-After
integer

Seconds to wait before retrying

504

Section titled “504 ”

The request overran its overall deadline and was killed (deadline_exceeded)

object
error
required

Human-readable message

string
code
required

Stable machine-readable error code. Clients should treat unknown codes as internal_error.

string
Allowed values: invalid_request unauthorized not_found file_not_found payload_too_large limits_exceeded profile_not_allowed capacity_exhausted rate_limited shutting_down cancelled deadline_exceeded sandbox_setup_failed cache_disabled internal_error
Example
{
  "error": "Execution exceeded the overall deadline of 30000 ms and was killed",
  "code": "deadline_exceeded"
}