Files & artifacts

Store task inputs

Files live in the Environment's persistent /workspace RootFS. The public API supports directory listing, byte upload, base64 readback, and deletion; see the generated file operations for their exact paths, parameters, media types, and size limits. Parent directories must exist. File operations need an initial checkpoint and cannot proceed while a Run or rollback holds the lifecycle lock. Paths must be canonical and inside /workspace; protected Sandpi state, Git metadata, symlinks, and directories are not accepted as file targets. Bytes stay in Sandbox0, not PostgreSQL.

Workspace access and conflicts

File-access conflicts return HTTP 409 with a reason-specific error code documented in the API details. A Run being queued or executed, checkpoint capture, rollback, initialization, and pause/resume transitions are distinct from generic lock contention; failed checkpoints are reported separately. A ready Run checkpoint can be visible before the worker finishes its subsequent memory pause and releases the lifecycle lock. Clients should wait for active work to finish and retry transient transitions; persistent checkpoint failures require operator investigation. No file operation bypasses the lock.

Reference existing files

Runs can reference regular Environment files that already exist. The worker checks paths just before starting the harness. An optional digest detects content changes; without one, a queued Run reads the file as it exists at execution time. Runs execute serially, so earlier work can alter files before a later Run begins. A rollback can remove or restore referenced files; a later Run checks its paths against the restored Workspace. The harness receives file paths in its prompt and reads them using native tools.

Inspect file changes

The Run file diff reports regular file additions, changes, and deletions under /workspace with before and after SHA-256 identities. Sandpi state, Git metadata, and generated caches are excluded. A large Workspace can fail diff computation without failing the Run or its checkpoint.

curl -X PUT \
    "https://api.sandpi.ai/v1/environments/$ENVIRONMENT_ID/file?path=%2Fworkspace%2Fexample.md" \
    -H "Authorization: Bearer $SANDPI_API_TOKEN" \
    -H "Content-Type: application/octet-stream" \
    --data-binary @example.md

"<binary bytes>"

{
  "data": {
    "path": "",
    "sizeBytes": -9007199254740991,
    "sha256": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa"
  }
}

{
  "error": {
    "code": "platform_balance_insufficient",
    "message": "Top up Platform credits before submitting a Run.",
    "requestId": "req_example"
  }
}

Read artifacts

List the output directory after execution and its checkpoint settle. File reads return base64 content, size and a SHA-256 digest. Decode the content in your client; it is not a raw download body.

curl \
    "https://api.sandpi.ai/v1/environments/$ENVIRONMENT_ID/files?path=%2Fworkspace%2Fexample.md" \
    -H "Authorization: Bearer $SANDPI_API_TOKEN"

{
  "data": {
    "path": "",
    "entries": [
      {
        "path": "",
        "name": "",
        "kind": "file"
      }
    ]
  }
}

{
  "error": {
    "code": "platform_balance_insufficient",
    "message": "Top up Platform credits before submitting a Run.",
    "requestId": "req_example"
  }
}

curl \
    "https://api.sandpi.ai/v1/environments/$ENVIRONMENT_ID/file?path=%2Fworkspace%2Fexample.md" \
    -H "Authorization: Bearer $SANDPI_API_TOKEN"

{
  "data": {
    "path": "",
    "sizeBytes": -9007199254740991,
    "sha256": "",
    "encoding": "base64",
    "content": ""
  }
}

{
  "error": {
    "code": "platform_balance_insufficient",
    "message": "Top up Platform credits before submitting a Run.",
    "requestId": "req_example"
  }
}

Pin a Run input

Include the path in the Run’s files array. Use the digest returned by a read when you need to ensure the worker sees those same bytes. The Run API details supplies the exact file-reference contract. Uploading a file alone does not attach it to a Run.

Remove a file

Deletion changes the live workspace. Existing checkpoints can still contain the file, and rollback can restore it. For whole-Environment cleanup, use retention and deletion.

curl -X DELETE \
    "https://api.sandpi.ai/v1/environments/$ENVIRONMENT_ID/file?path=%2Fworkspace%2Fexample.md" \
    -H "Authorization: Bearer $SANDPI_API_TOKEN"

{
  "error": {
    "code": "platform_balance_insufficient",
    "message": "Top up Platform credits before submitting a Run.",
    "requestId": "req_example"
  }
}