An API to push local files into an actor sandbox

[eliranw]

Summary

We need a way to write a client’s own files into a running actor. Other sandbox platforms have this: E2B’s Sandbox.files.write, Anthropic’s container_upload block, Fly Machines’ config.files.

Motivation

A sandboxed code runner should be able to run code on the caller’s files in a fresh isolated sandbox and hand back the result.

Today there’s no way to get the caller’s files into a running actor. An actor runs whatever workload image it was built from, reached over the workload’s own HTTP server, so the only options are:

1. Bake the files into the image. But images are digest-pinned, so rebuilding on every change is slow and throws away snapshot/warm-start.
2. Have the workload itself expose an upload endpoint on its HTTP server, so every template author builds and secures the same thing by hand.

Either way there’s no platform-level file ingress: CreateActorRequest is just {actor_id, template_ns, template_name}, the data plane only carries WorkloadSpec{containers}, an ActorTemplate is image + command + env, and the ategcs object store only holds runsc checkpoints today.

One option that would cover this: a files map (path to bytes) written into the actor’s filesystem. From the outside it looks like it could sit on the actor, next to the exec channel proposed in #185, so a running actor could both receive files and run commands through one handle. I don’t know the internals well enough to say where it actually belongs, so this is just a starting point, not a recommendation.

I’m mainly filing this to surface the use case and the gap. Happy to help with an implementation once there’s a direction.

Open Questions

• A standalone file-write operation on the actor, or folded into the Feature: Add an Exec channel to run commands inside a running actor (E2B-style sandbox exec) #185 exec channel as one “exec with files” call?
• Where should the files land?
• What’s a reasonable size limit, and should large payloads go through the object store instead of riding in the request?

[EItanya]

I've been thinking about this a lot. Another similar feature would be ssh. Is this the sort of thing we want to add directly to substrate, or leave users the ability to add their own "daemon/agent" into.

[eliranw]

I've been thinking about this a lot. Another similar feature would be ssh. Is this the sort of thing we want to add directly to substrate, or leave users the ability to add their own "daemon/agent" into.

I’d lean toward building it in as it’s a core feature for most other sandbox providers (Modal, AgentCore, Daytona), not something bolted on. And if it’s CRI compliant, it can work like kubectl cp/kubectl exec, so it feels familiar to anyone who’s used Kubernetes instead of every template author rolling their own.

[BenTheElder]

kubectl cp has a long history of issues, especially with security. I think if you proposed it in Kubernetes today as a new feature the current approach would be rejected.

[...] And if it’s CRI compliant, it can work like kubectl cp/kubectl exec, so it feels familiar to anyone who’s used Kubernetes instead of every template author rolling their own.

CRI doesn't actually specify anything like this. Copy is done by abusing the exec API and requiring tar to be present and trusted in the container.

To be clear: I'm just adding some context :-)

I think there's an open scoping question about this sort of API that needs further thought / discussion.