Can a Claude Agent SDK Worker Survive Replacement?

Choose sandbox-runtime, Docker, gVisor, or a VM based on the workload boundary. Then measure whether Claude Agent SDK SessionStore restores the same transcript and workspace on a replacement worker, and price the full drill.

Test a routine file boundary with synthetic markers

Start with the least expensive isolation candidate that meets your deployment requirements. The Claude documentation describes sandbox-runtime as lightweight, Docker isolation as setup dependent, and gVisor and VMs as stronger options when configured correctly. Turn those distinctions into a staging test using the same image contents and two harmless marker files. Mount one marker in the intended workspace and leave the other outside the worker's configured workspace mounts. From the normal job entry point, check that the worker can read the first marker and record the expected absence of the second. Repeat after replacing the worker and save the runtime identity alongside the result. If the permitted marker disappears after replacement, diagnose workspace provisioning before interpreting the isolation check. If the outside marker appears, inspect the actual mounts before running customer jobs.

Securely deploying AI agents - Claude Code Docs

Measure when restored work becomes usable

Use SessionStore to mirror transcript entries and provision the same working directory on the replacement worker. Test transcript recovery and repository recovery with separate assertions. In a disposable job, ask the agent to record a synthetic ticket ID in the conversation and create a small work product in the workspace. Record the expected ticket ID and file checksum in the test runner. After the normal persistence acknowledgement, replace the worker and attempt to resume. Stop the recovery timer only when the resumed session returns the ticket ID and the file checksum matches. A correct ticket ID with a missing file points to workspace restoration, while a correct file with missing context points to transcript restoration or session identity. Record the billed time for both workers, including provisioning and overlap, to estimate what a recoverable job actually costs.

Persist sessions to external storage - Claude Code Docs

Choose the boundary around the worker

Run the Claude Agent SDK application inside the worker boundary, as Anthropic describes for isolated deployments. Keep job admission and workspace provisioning credentials in a separate service. Give the worker only its assigned checkout and the access it needs to return a result. Configure the worker per job or tenant according to which data and credentials can safely coexist.

For an illustrative first deployment, assume a Python repository worker needs unit tests and no Docker daemon. Pilot a container and verify that it can write test artifacts to the assigned workspace while a dummy file outside the assigned mount stays inaccessible. If the production job requires its own kernel or a Docker daemon, run the same test in a VM candidate and include the workload's actual startup and integration tests.

Securely deploying AI agents - Claude Code Docs

Verify denials before shipping

Use SDK permission rules to decide which tools can act automatically and which require review. For an invariant such as keeping a designated fixture read-only, add a PreToolUse hook that denies a write to it. Anthropic documents that hooks can deny outright and that deny and ask rules still run when a hook allows a call. Exercise the policy through the deployed worker with two harmless requests, one that writes a test report and one that tries to change the protected fixture.

Require the report to appear, the denied action to be visible in the job record, and the fixture checksum to stay unchanged. Verify network and filesystem restrictions independently at the worker boundary using controlled test destinations and dummy files. A passing tool-permission check alone gives no evidence about those controls.

Configure permissions - Claude Code Docs

Resume on a replacement host

Use a SessionStore if a Claude Agent SDK conversation needs to resume after its worker is replaced. Anthropic documents mirroring the transcript to an external backend and resuming from another host with a matching working directory. Save the repository revision and required workspace artifacts through your own job system. Restore them before opening the resumed session.

In an illustrative drill, a worker writes a test report and records a follow-up task before being retired. On a clean replacement, restore the checkout at the expected directory, recover the report, and resume the conversation. Pass the drill only when the agent can use the prior conversation and open the original report. If the conversation returns but the report is missing, inspect workspace restoration and artifact persistence before changing the transcript adapter.

Persist sessions to external storage - Claude Code Docs

Reconcile model and worker charges

Log the SDK's model cost estimates by job and collect the host's compute and storage usage for the same pilot. Anthropic describes the SDK cost fields as client-side estimates that can diverge from billing. Use provider billing records over the same interval before setting a production budget, and include retry usage even when the original attempt produced nothing usable.

For illustrative arithmetic, suppose 100 attempts produce 80 accepted results, the model invoice attributable to the pilot is $12, and worker charges total $8. The combined cost is $0.25 per accepted result. Verify the host's billing units, minimums, and retained storage charges for the chosen plan, and check which model or tool fees appear on the provider invoice. If the container and VM both pass the acceptance tests, compare their cost per accepted result and recovery times.

Track cost and usage - Claude Code Docs

Sources