Empirical Sandbox Execution

Readiness and execution contract for the empirical notebook sandbox.

GET/POST /api/labs/empirical/sandbox/execute

This endpoint is an authenticated workbench route for the empirical notebook sandbox. It is not a public PAT endpoint. It uses the signed-in web session, applies plan and rate-limit checks, and only runs code when hosted execution is available for the current environment.

Readiness

GET /api/labs/empirical/sandbox/execute

The readiness response reports whether execution can be requested in the current environment.

{
  "executable": false,
  "backend": {
    "status": "disabled",
    "message": "Remote notebook execution is disabled for this environment."
  },
  "policy": {
    "schemaVersion": "macro-by-mark/empirical-notebook-runtime-policy/v1",
    "language": "python",
    "executionMode": "sandboxed-python"
  }
}

The readiness response is intentionally limited to user-facing availability and policy fields. It does not expose internal infrastructure locations, credentials, storage paths, or infrastructure state.

Request A Run

POST /api/labs/empirical/sandbox/execute
Content-Type: application/json

{
  "language": "python",
  "code": "import pandas as pd\nprint(pd.Series([1, 2, 3]).mean())",
  "requestedPackages": ["pandas"],
  "manifest": {
    "schemaVersion": "macro-by-mark/empirical-notebook-export/v1"
  }
}

Fields:

Field	Required	Notes
`language`	optional	Only `python` is accepted.
`code`	required	Python source, capped by the server request schema.
`requestedPackages`	optional	Extra package names requested by the notebook. They must be supported by the sandbox policy.
`manifest`	optional	The notebook export manifest. The route treats it as metadata and rebuilds the runtime policy from `code`.

Package Policy

The sandbox supports a reviewed Python scientific stack for empirical work. Imports outside the supported policy are rejected before execution.

{
  "error": "Notebook imports are outside the sandbox package allowlist.",
  "rejectedImports": ["requests"]
}

Unavailable Runner

When hosted execution is unavailable, the route returns 503:

{
  "executable": false,
  "status": "not_configured",
  "message": "Remote notebook execution is disabled for this environment."
}

Saved Executions

Accepted runs may be saved for the signed-in user. The execute response can include persistence metadata:

{
  "persistence": {
    "status": "saved",
    "labResultId": "lab-result-1",
    "artifactBlobCount": 1,
    "artifactObjectCount": 0,
    "artifactStorageStatus": "skipped"
  }
}

The browser response contains artifact metadata and signed, user-scoped download links when saved artifacts are available. It does not expose raw storage locations or cross-user artifact access.

GET /api/labs/empirical/sandbox/executions/{labResultId}
GET /api/labs/empirical/sandbox/artifacts/{labResultId}/{artifactIndex}

The saved execution route returns the normalized result, persistence metadata, and artifact download links. The artifact route streams one saved artifact with private no-store caching after checking the signed-in user's access.