Credentials in Agent Sandboxes and VMs: Do Not Ship the Keys

Draw the credential boundary around the whole VM

Suppose an agent needs to inspect a support ticket and query an orders database while fixing a bug. Copying your developer home directory into its VM might also supply a database password, cloud credentials and cached OAuth sessions. The guest now has authority unrelated to the bug, even if its filesystem is perfectly isolated from the host.

Start with a launch inventory: image contents, mounted directories, inherited environment variables, bootstrap scripts and restored state. For each credential, record which process needs it and whether the task actually requires direct access to the upstream service. Keep model-provider authentication separate from company-tool access; replacing upstream tool secrets does not remove every credential an agent needs.

Anthropic's sandboxing documentation illustrates why the boundary matters: Claude Code's built-in sandbox covers shell commands, while MCP servers, hooks and built-in file tools run outside it. Its documented defaults also inherit environment secrets and allow reads of credential files unless restricted. A VM around the whole client is a different boundary, but anything deliberately placed inside that VM still needs its own access policy.

Exchange upstream secrets for permission to call tools

Use this arrangement for the ticket-and-orders task: the guest authenticates to a remote gateway; the gateway checks its permissions; a connector outside the guest uses the ticket token or database credential. Return the requested records, never the connector credentials. The sandbox's key should authorize only the sources and operations needed for that run.

This is a recommended deployment pattern, not a property that MCP supplies automatically. An endpoint that accepts an unrestricted administrator key merely moves the same broad authority behind another URL. Enforce source restrictions and operation permissions on the server, independently of the tool list the client displays.

The MCP security best-practices guide explicitly prohibits token passthrough: accepting client tokens without validating that they were issued for the MCP server and forwarding them downstream. Keep the gateway credential and upstream authorization separate. For an OAuth implementation, validate the intended token audience rather than accepting an upstream API token as gateway identity.

Issue a distinct credential to each sandbox so one revocation does not interrupt unrelated runs. Record its owner, sandbox identifier, permitted sources and intended retirement time outside the guest. The broader allocation policy belongs in one scoped key per agent.

Build and snapshot before injecting credentials

Make the reusable image contain the agent binary, dependencies and configuration templates. Exclude developer credential directories, populated environment files and authenticated CLI profiles. Fetch dependencies before issuing the company-tool key, so package installation does not run with authority intended for the agent's task.

Docker's build-secrets documentation warns against passing build secrets through build arguments or environment variables because they persist in the final image. When a build genuinely needs a private-registry credential, use a BuildKit secret mount for that build instruction. Review the command consuming it too: temporary availability does not prevent that command from copying the value into an output file.

VM snapshots need a separate decision. Firecracker documents that full snapshots contain guest memory alongside machine state, with disk files managed separately. The operational implication is that a snapshot taken after authentication can preserve credential-bearing memory even when no token file exists.

Prefer a snapshot captured before company-tool authentication, then inject a fresh sandbox key after restore. If you retain snapshots of authenticated runs for debugging, treat them as sensitive artifacts, restrict access and retire their credentials. Never clone an authenticated snapshot into a pool and assume each restored guest has a separate identity.

Keep the client configuration free of literal keys

For Claude Code inside the guest, put this template in the project's .mcp.json. Replace the example URL with your actual gateway endpoint. Claude Code's MCP documentation supports the http server type and environment-variable expansion in authentication headers:

{
  "mcpServers": {
    "company-tools": {
      "type": "http",
      "url": "https://tools.example.com/mcp",
      "headers": {
        "Authorization": "Bearer ${AGENT_MCP_KEY}"
      }
    }
  }
}

Have a trusted launcher obtain the sandbox's gateway key and supply AGENT_MCP_KEY to the Claude Code process at startup. The launcher should reject an absent or empty value before starting the client. Keep the literal variable reference in the template; do not render the secret into the JSON file during provisioning.

Environment injection prevents a literal key from being stored in this configuration; it does not conceal the value from the running client or every subprocess. Treat guest compromise as possible gateway-key compromise. Avoid putting the value in command-line arguments, shell history or diagnostic output. Review repository changes to the endpoint and headers before launching with a credential: a configuration template also determines where authentication is sent.

Limit what can leave and what can survive

Apply outbound network policy at the boundary that encloses the whole agent process. Allow the remote tool endpoint and the other destinations the task requires. Do not assume a shell-only sandbox policy also covers the client's MCP requests. Test the actual path from client to gateway and reject direct database access when the task is meant to use tools.

Separate provisioning network access from runtime access. Installing packages may require many hosts; reading an orders tool should not automatically inherit that entire allowlist. Where practical, remove installation credentials and narrow destinations before launching the authenticated agent.

Also define artifact handling before a run starts. Exclude process-environment dumps, credential files, authenticated home directories and unrestricted debugging bundles from exports. Inspect transcripts and crash reports with a disposable test credential rather than exposing a production value while checking for leakage.

The gateway can still return sensitive ticket text or order records. Keeping upstream passwords outside the guest reduces credential distribution; it does not prevent misuse of permitted tools or disclosure of retrieved data. Scope returned information to the task and review what a completed sandbox is allowed to export.

Doing this with SPYN3

SPYN3 keeps upstream credentials in the workspace with envelope encryption; the agent holds only a SPYN3 API key or OAuth token. Point the client at https://api.spyn3.com/agent/mcp. An admin can create a key limited to chosen sources: call:tools reaches tools marked read-only upstream, while writes need call:write_tools. Revoking the key takes effect on the next call, and proxied tool calls are audit-logged. Create a separate source-scoped key for the sandbox and inject it at launch.

Prove revocation survives a running or restored guest

Before using company data, run these checks against a test workspace with disposable credentials. Preserve the sandbox identifier and authorization results, without recording the key itself:

1. Fresh boot: launch without the injected key. Confirm company tools cannot return protected data and the launcher reports missing authentication.
2. Allowed read: inject the sandbox key and read a harmless test record through the gateway. Confirm the audit trail identifies the credential used.
3. Denied operation: attempt a write and access to an excluded source. Verify server-side refusal, including when the client attempts the call directly rather than selecting a displayed tool.
4. Live revocation: revoke the key while the guest remains running. Make a fresh protected call through the same client connection and confirm access is refused.
5. Restore: resume a test snapshot captured while that disposable key was active. Confirm the revoked credential still cannot authorize a new call. Provision a fresh key before continuing legitimate work.
6. Teardown: revoke the run's key, stop the guest, and remove its writable disks and temporary credential material according to your retention policy. Check exported artifacts separately.

Do not count deleting a VM as revocation: a copied key may still exist elsewhere. For a failed revocation test, fix authorization before adding more sandboxes. Continue with assessing a leaked agent key's blast radius to decide which calls and returned data require investigation.