Ephemeral Agent Sandboxes Start Empty: Giving Them Context

Decide what must survive a fresh sandbox

Consider a worker created to fix a billing test. Its image contains the runtime and test tools; its checkout contains the failing code. Neither tells it that the team recently changed invoice rounding or where the approved release checklist lives. Rebuilding yesterday's worker image to carry today's decision couples context updates to image deployment.

Keep the image responsible for executables and dependencies. Keep repository instructions with the checkout. Fetch changing team decisions, personal preferences where appropriate, and reviewed skills after the scheduler assigns the job. This is a proposed bootstrap design: the sandbox can disappear while those records remain in an external store.

Define “fresh” precisely. E2B's persistence documentation says pausing can preserve filesystem and memory state, including running processes. Resuming that sandbox differs from provisioning a replacement. For this guide, assume a new worker with an empty home directory, a clean checkout and no restored volume. A successful resume does not prove that this worker can reconstruct its context.

Fetch a bounded bootstrap bundle before launching the agent

Have the trusted launcher bind the job to a workspace, calling identity and repository revision before retrieving context. Derive that identity from the scheduler's assignment. Do not let a remembered workspace name choose which tenant's records the worker receives.

Use your context service's documented API or an MCP client to retrieve a small bundle. The following is an application contract to implement, rather than an MCP feature:

1. Read the current project summary and an index of relevant memories.
2. Select reviewed skills permitted for this job and record their revisions.
3. Validate workspace ownership, allowed file destinations and size limits.
4. Write the validated summary to /run/agent-context/bootstrap.txt and materialize selected skills before starting the client.

As an initial budget, try 6,000 UTF-8 bytes for the summary and index; treat that as a tuning choice. Include retrieval time, record identifiers and revisions in launcher diagnostics without copying private memory text. Anthropic's context-engineering guidance supports combining a small initial context with references that the agent follows when needed. An invoice task can fetch the rounding decision immediately and leave unrelated deployment history in the store. For more budgeting detail, see choosing what to load at session start.

Connect the running client to the same context store

The bootstrap file gives the first model turn useful context. A remote connection lets later turns retrieve details without recreating the worker. For Claude Code running inside a Linux sandbox, place this configuration in the checkout's root .mcp.json:

{
  "mcpServers": {
    "context": {
      "type": "http",
      "url": "${CONTEXT_MCP_URL}",
      "headers": {
        "Authorization": "Bearer ${CONTEXT_MCP_TOKEN}"
      }
    }
  }
}

Claude Code's MCP documentation defines type: "http" and supports environment expansion in both URLs and headers. Set CONTEXT_MCP_URL to your actual HTTPS MCP endpoint and inject a job-appropriate bearer credential as CONTEXT_MCP_TOKEN at launch. Require both variables to be nonempty in the launcher. The configuration contains references; the process still receives a real credential.

Review the destination before injecting that credential. In unattended claude -p runs, project MCP servers can load without an approval prompt, so do not assume an interactive trust dialog will protect the job. Verify connection and authorization before assigning work that requires remote context. Adding a server makes tools available; your bootstrap routine or agent instructions must still request the relevant records.

Deliver the first summary and install skills before discovery

For this Claude Code example, the launcher creates the bootstrap file before invoking the CLI. Add the following to the project's .claude/settings.json, merging with any existing settings:

{
  "hooks": {
    "SessionStart": [
      {
        "matcher": "startup",
        "hooks": [
          {
            "type": "command",
            "command": "cat /run/agent-context/bootstrap.txt",
            "timeout": 2
          }
        ]
      }
    ]
  }
}

Claude Code's hooks reference documents SessionStart, its startup matcher and plain-text stdout being added to context. The two-second timeout bounds this local read. Keep the file plain text with a descriptive first line, and label remembered facts as recorded observations with provenance. Put only the validated bundle there: everything printed becomes model-visible context.

This hook does not enforce bootstrap success. The documented event has no blocking control. If the project summary is required, make the launcher refuse to start when retrieval or validation fails. If optional memories are unavailable, write an explicit availability note and permit the job to continue under its normal repository instructions.

For native skill discovery, place reviewed files at .claude/skills/<name>/SKILL.md before launch. Claude Code documents this project location and loading skill bodies when used. Validate the skill's frontmatter and supporting files, and pin the selected revision for the run. A remote catalog entry alone is not an installed native skill. Other harnesses need their own delivery adapter; the shared store can retain the same source material.

Save useful outcomes before the worker disappears

Choose a persistence boundary that the scheduler can observe. After the billing worker finishes, a candidate memory might record the confirmed rounding rule and link to its test or reviewed change. Save code changes and test artifacts through the normal job artifact path; a memory entry is no substitute for the patch.

Make the launcher wait for an acknowledged context write before destroying a worker whose new memory must survive. Give each proposed write a stable job identifier so retrying finalization does not create duplicate records. These are requirements for your persistence adapter, not guarantees supplied by MCP.

Never depend entirely on a shutdown callback: forced termination may leave it no chance to finish. For longer jobs, checkpoint approved findings at meaningful task boundaries. Keep shared-memory writes separately authorized from reads, and prevent arbitrary transcripts from becoming instructions for the next worker. Treat local context files as sensitive job artifacts. Revoking remote access cannot withdraw text already fetched into a sandbox, so do not reuse that sandbox across identities. The sandbox credential guide covers the credential lifecycle in more detail.

Loading sandbox context with SPYN3

Enable “Memory & skills” in workspace Settings, then connect the sandbox to https://api.spyn3.com/agent/mcp. SPYN3 provides context tools for any MCP client; its Claude Code and Codex plugin loads a profile, memory index and skill catalog at SessionStart, capped at 9,500 bytes. Context reads need call:tools; writes need the separate write:memory permission. Upstream credentials stay in the workspace; the agent holds a SPYN3 credential. Automatic capture is separately opt-in and requires the workspace's own model key.

Prove reconstruction with disposable-worker checks

Test the design by discarding the worker, including its home directory and caches. Provision another from the same base image and checkout. Ask it which rounding rule applies and where the release skill came from. Check the fetched record and skill revisions against the launcher manifest; a plausible answer alone cannot establish successful restoration.

• Change only the context store. Update a test memory and confirm that a newly provisioned worker receives it without an image rebuild.
• Break retrieval. Confirm that missing required context prevents launch, while optional recall produces the intended availability note.
• Change identity. Start a second workspace's job and verify that the first workspace's memory identifiers and local files are absent.
• Interrupt finalization. Retry an acknowledged write and check that the next worker sees one retained finding.

Measure bootstrap duration, bytes delivered and whether the first task action used the required decision. Keep this fixture in the provisioning checks so changes to images, client versions or context adapters exercise a genuinely empty start.