Files

Cella's file API ships and pulls tarballs through the sandbox's main container. The implementation is kubectl exec tar over the same SPDY exec subresource as /commands, so you don't need a second port or sidecar to move bytes.

Export

POST /v1/sandboxes/{id}/files/export
Authorization: Bearer <jwt>
Content-Type: application/json

{
  "src_dir": "/workspace",
  "paths":   ["./build", "./report.json"]
}

The body is optional. Empty body tars all of /workspace. Response is the raw tar stream:

Content-Type: application/x-tar
Content-Disposition: attachment; filename="sb-01J6....tar"

paths are passed to tar after a --, but path values starting with - are still rejected by the server defensively. The argv looks like:

tar -C <src_dir> -cf - -- <paths...>

read:sandbox is required.

Import

POST /v1/sandboxes/{id}/files/import
Authorization: Bearer <jwt>
Content-Type: multipart/form-data; boundary=…

--…
Content-Disposition: form-data; name="dest"

/workspace
--…
Content-Disposition: form-data; name="tarball"; filename="payload.tar"
Content-Type: application/x-tar

<binary tar bytes>
--…--

The server pipes the tarball into tar -C <dest> -xf - inside the main container.

{ "imported": "payload.tar", "bytes": 4096, "dest": "/workspace" }

Constraint	Value
Max upload	1 GiB per request (MaxBytesReader enforced).
Default dest	/workspace
Required form field	tarball
Required scope	write:sandbox

If the import would exceed the PVC's free space, tar fails with a non-zero exit and the partial extraction stays on disk. Future revisions will reject before extraction.

CLI examples

# Pull a directory out as a tarball
latere cella export my-workspace ./build -o build.tar

# Push a tarball in
tar -cf - ./src | latere cella import my-workspace --dest /workspace

Why tar over kubectl exec

• No second port to expose, secure, or rate-limit.
• No additional sidecar to deploy.
• Works through the same NetworkPolicy default-deny posture as /commands.
• tar already speaks streaming — large transfers don't buffer the whole archive in sandboxd.

The downside is no resume on broken transfers. A future spec covers signed-URL spillover to object storage for multi-GB exports — drafted but not yet implemented.