Skip to content
Faber Faber

Quick start

This starts the published image on your machine, bound to localhost, and runs a command in a sandbox.

Before you start

Section titled “Before you start”
  • A Linux host with cgroup v2. Check with stat -fc %T /sys/fs/cgroup; it must print cgroup2fs.
  • Rootful Docker. Rootless Docker cannot grant the mount and namespace operations Faber needs.
  • curl and, for reading responses, jq.

Run it

Section titled “Run it”

  1. Generate an API key. Every route except /health and the OpenAPI document requires it.

    Terminal window
    export API_KEY="$(openssl rand -hex 32)"

  2. Start the container. The latest image includes GCC, G++ and Make.

    Terminal window
    docker run -d --name faber --init \
      --privileged --cgroupns=host \
      -v /sys/fs/cgroup:/sys/fs/cgroup:rw \
      --read-only --tmpfs /tmp:size=64m \
      --memory 8g --memory-swap 8g --pids-limit 4096 \
      -e API_KEY="$API_KEY" \
      -p 127.0.0.1:3000:3000 \
      vgfractal/faber:latest

    --privileged, --cgroupns=host and the read-write /sys/fs/cgroup mount are required: Faber creates namespaces and cgroups for every task. The other flags are hardening and a memory backstop; Docker deployment explains each one.

  3. Check that it is up.

    Terminal window
    curl -s http://localhost:3000/api/v1/health
    {"status":"ok","version":"0.3.0"}

  4. Run a command.

    Terminal window
    curl -s http://localhost:3000/api/v1/execute \
      -H "Authorization: Bearer $API_KEY" \
      -H "Content-Type: application/json" \
      -d '{"steps": [{"cmd": "echo", "args": ["Hello from the sandbox"]}]}' | jq
    {
      "steps": [
        {
          "stdout": "Hello from the sandbox\n",
          "stderr": "",
          "exit_code": 0,
          "cached": false,
          "stats": {
            "memory_peak_bytes": 290816,
            "cpu_usage_usec": 1210,
            "pids_peak": 1,
            "execution_time_ms": 4,
            "stdout_truncated": false,
            "stderr_truncated": false,
            "outcome": "exited",
            "termination_signal": null,
            "oom_kill_count": 0,
            "pids_limit_hit_count": 0,
            "cleanup_succeeded": true
          }
        }
      ],
      "cache": { "enabled": false, "hits": 0, "stored": 0 }
    }

    The response has one result per step, in the same order and the same shape as the step. Stats are trimmed here; the full list is in the API reference.

  5. See what this instance allows.

    Terminal window
    curl -s http://localhost:3000/api/v1/info -H "Authorization: Bearer $API_KEY" | jq

    /info reports the limits every task runs under, the sandbox profiles you may choose, whether the step cache is on, and the toolchains in the image.

Clean up

Section titled “Clean up”
Terminal window
docker rm -f faber

Next

Section titled “Next”