Environments and Containers

Every Managed Agents session executes inside a container. You do not manage the container runtime — Anthropic does. But you configure the environment it runs against: where execution happens, what the agent can reach on the network, and what credentials the agent's traffic can carry.

Environment configuration is where least-privilege discipline actually matters. An agent with an overly permissive environment is not just a security risk — it is a reliability risk. An agent that can reach any URL, run any binary, and access any key is an agent that is harder to reason about, harder to audit, and harder to debug when something goes wrong.

What an Environment Is

An environment is a standalone resource — created once, referenced by ID when you start sessions. Its config declares where execution happens (cloud on Anthropic's infrastructure, or self_hosted in your own) and what the network policy is:

import anthropic

client = anthropic.Anthropic()

environment = client.beta.environments.create(
    config={
        "type": "cloud",
        "networking": {
            "type": "limited",
            "allowed_hosts": ["s3.amazonaws.com", "api.company.com"],
            "allow_package_managers": True,
            "allow_mcp_servers": False
        }
    }
)

session = client.beta.sessions.create(
    agent={"type": "agent", "id": agent.id},
    environment_id=environment.id
)

The environment is not embedded in the agent definition. The same agent can run in different environments — a locked-down production environment and a permissive development one — and the same environment can serve many agents.

Networking: unrestricted vs limited

The networking config has two modes:

unrestricted — the sandbox can reach any host. Appropriate for development and for research agents whose whole job is the open web.

limited — outbound traffic is restricted to the hosts you allow:

"networking": {
    "type": "limited",
    "allowed_hosts": [
        "api.openmetadata.org",
        "data.company.com"
    ],
    "allow_package_managers": True,
    "allow_mcp_servers": False
}

• allowed_hosts — the explicit list of hosts the agent's bash scripts and web_fetch calls can reach. A connection to anything else is rejected.
• allow_package_managers — whether the agent can reach package registries (pip, npm) to install dependencies at runtime. If your agent installs packages during the session, pin versions in your setup instructions — an unpinned install gets the latest version at session time, which may change between sessions and is an invisible source of regression.
• allow_mcp_servers — whether the sandbox can reach attached MCP servers.

Be deliberate about breadth. Allowing api.company.com is a scalpel; allowing every host your agent might conceivably need is the same mistake as granting every tool.

File System: Ephemeral by Default

A Managed Agents session file system is ephemeral. Files written during a session are available within that session but do not persist after it ends. The next session starts with a clean file system.

This is correct behavior for most pipeline use cases — each session is independent and self-contained.

For data that must survive across sessions, the mechanism is memory stores — workspace-scoped resources attached at session creation and mounted into the sandbox's file system. They are covered in depth in the memory lesson. There is no per-environment persistent volume.

For most agents, the right pattern is: read inputs from the session input, do work in the ephemeral file system, write outputs to an external system (S3, database, API) before the session ends. Reach for memory stores only when the task genuinely requires cross-session state.

Secrets: Vaults and Egress Substitution

Secrets are managed through vaults. A vault holds credentials — environment_variable, static_bearer, or mcp_oauth types — that you create once and reference from sessions. Do not put secrets in the system prompt — they will appear in session logs. Do not pass them in session input content — they will appear in event streams.

The critical design property: the sandbox never sees the real secret. Inside the container, the credential appears as an opaque placeholder. When the agent's outbound request leaves the sandbox, the platform substitutes the real value at network egress. An agent that runs echo $API_KEY prints the placeholder, not the key. Even a fully compromised or prompt-injected agent cannot exfiltrate the raw credential from inside the session — the secret only exists in transit to the host you authorized.

This is the opposite of the naive env-var model, and it changes the threat model: you are no longer trusting the agent with the secret, only authorizing specific egress traffic to carry it.

Least Privilege in Practice

Configure each agent's environment for exactly its task:

A research and reporting agent that searches the web and writes Markdown reports needs:

• Networking: unrestricted if its job is the open web, otherwise limited to the specific APIs it calls
• No memory store — each report is a standalone session output
• No vault credentials unless it calls an authenticated API

A data pipeline agent that reads from S3, transforms data, and writes back needs:

• Networking: limited with AWS S3 endpoints in allowed_hosts, allow_package_managers on if it installs pandas/boto3 at runtime (pinned)
• Vault credentials: AWS credentials, substituted at egress
• Possibly a memory store if it maintains a processing checkpoint

A code analysis agent that clones repositories and runs analysis tools needs:

• Networking: limited with GitHub/GitLab API endpoints and the package registry for the target language
• Vault credentials: repository access token
• No memory store — analysis is per-session