File transfer

POST/sandboxes/{id}/files

Extracts a tar stream (the request body, application/octet-stream) beneath ?path in the guest filesystem; the `crucible cp` push path. Rejects entries that escape the destination.

File transfer between host and guest is one-way bulk copy, so there is no frame protocol.

Push

POST /sandboxes/{id}/files?path=<dest> takes a tar stream as the request body. The daemon streams it straight to the guest agent (nothing buffered whole); the agent creates <dest> and extracts each entry beneath it, rejecting any entry whose resolved path escapes the destination (absolute paths, .., or symlinks pointing outside). Returns 200 {"files":N,"bytes":M}. Gated as an exec-class operation.

This backs crucible cp (push) and the MCP write_files tool.

Read

GET /sandboxes/{id}/files?path=<file>&max_bytes=<n> returns the raw bytes of a single guest file, capped by max_bytes; a directory is a 400. Gated as read. It backs the MCP read_file tool.

path parameters

object

idstringrequired

Sandbox ID, e.g. sbx_ab12cd34.

query parameters

object

pathstringrequired

Guest destination directory the tar is extracted beneath.

Responses

200 OKOK

WireFilesPutResult

bytesintegerint64

filesinteger

400 Bad requestBad Request

ErrorResponse

errorstring

404 Not foundNot Found

ErrorResponse

errorstring

Authentication

bearerAuthHTTP bearer. Daemon API key. Omit on a keyless loopback daemon.