# Template 03 — Environment Config Templates (5 Use Cases)

An environment defines the cloud container where your agent runs: which packages are pre-installed, and which network hosts the container can reach. You create an environment once and reference its ID each time you start a session. Every session gets its own isolated container instance — sessions do not share file system state.

This template gives you five ready-to-paste environment configurations for the most common agent use cases. Each config includes a JSON block for the API, the equivalent CLI command, and commentary explaining the tradeoffs and when to use it.

---

## How to Use This Template

1. Find the use case that best matches your agent's needs.
2. Copy the JSON or CLI block and replace the `[FILL IN: ...]` placeholders.
3. Run the CLI command or call the API to create the environment. Save the returned environment ID.
4. Reference the environment ID when creating a session (`environment_id: YOUR_ENV_ID`).

**Key fields reference:**

| Field | What it does |
|---|---|
| `name` | Required. Must be unique within your workspace. |
| `config.type` | Always `"cloud"` for Managed Agents. |
| `config.packages` | Pre-installs packages via pip, npm, apt, etc. before the agent starts. |
| `config.networking.type` | `"unrestricted"` = full outbound access (with safety blocklist); `"limited"` = only approved hosts. |
| `config.networking.allowed_hosts` | List of HTTPS-prefixed domains the container can reach (limited mode only). |
| `config.networking.allow_package_managers` | Allows pip/npm/etc. registry access in limited mode. Default: `false`. |
| `config.networking.allow_mcp_servers` | Allows outbound connections to configured MCP server URLs in limited mode. Default: `false`. |

---

## Config A — Safe Read-Only Research Agent

**Use this when:** The agent only needs to read uploaded files or web pages via `web_fetch`/`web_search`. No code execution, no writes to external services. Suitable for summarization, analysis, or classification tasks where the input comes in as a file.

**Tradeoffs:** Maximum safety — no shell access, no unrestricted networking. The agent cannot install packages or reach hosts outside your list. Slightly slower to set up because you must enumerate every domain the agent needs.

### JSON

```json
{
  "name": "[FILL IN: e.g., read-only-research]",
  "config": {
    "type": "cloud",
    "networking": {
      "type": "limited",
      "allowed_hosts": [
        "[FILL IN: https://your-data-host.example.com]",
        "[FILL IN: https://another-approved-domain.com — add more or delete]"
      ],
      "allow_package_managers": false,
      "allow_mcp_servers": false
    }
  }
}
```

### CLI

```bash
ant beta:environments create <<'YAML'
name: [FILL IN: read-only-research]
config:
  type: cloud
  networking:
    type: limited
    allowed_hosts:
      - [FILL IN: https://your-data-host.example.com]
      - [FILL IN: https://another-approved-domain.com]
    allow_package_managers: false
    allow_mcp_servers: false
YAML
```

**Note:** The `allowed_hosts` list controls container-level networking only. It does not restrict the `web_search` or `web_fetch` tools' allowed domains — those are controlled separately in your agent's tool configuration or system prompt.

---

## Config B — Content Writer with Web Search

**Use this when:** The agent browses the web to gather information and writes output files (articles, reports, social posts). It needs unrestricted read access to the web but should not be able to reach internal or sensitive hosts.

**Tradeoffs:** Unrestricted networking is convenient but means the container code could theoretically reach any public host. Safe as long as your system prompt restricts `web_search` and `web_fetch` to relevant domains, and you don't enable `bash`.

### JSON

```json
{
  "name": "[FILL IN: e.g., content-writer]",
  "config": {
    "type": "cloud",
    "networking": {
      "type": "unrestricted"
    }
  }
}
```

### CLI

```bash
ant beta:environments create <<'YAML'
name: [FILL IN: content-writer]
config:
  type: cloud
  networking:
    type: unrestricted
YAML
```

**Why no packages?** The built-in container already has all the utilities a content writer needs (file read/write via the agent tools). Only add packages if the agent needs to process specific file formats (e.g., `python-docx` for DOCX output).

**Optional: add a pre-installed skill for structured output:**

```bash
ant beta:environments create <<'YAML'
name: content-writer-with-docx
config:
  type: cloud
  packages:
    pip:
      - python-docx
  networking:
    type: unrestricted
YAML
```

---

## Config C — Data Analysis with Python + pandas

**Use this when:** The agent runs Python code to analyze uploaded CSV, JSON, or Excel files — computing statistics, generating visualizations, or transforming data.

**Tradeoffs:** Pre-installing `pandas`, `numpy`, and `matplotlib` adds a few seconds to environment startup but saves the agent from having to `pip install` at runtime. The `limited` networking ensures the container cannot exfiltrate data to external services while still being able to reach PyPI to install ad-hoc packages if needed.

### JSON

```json
{
  "name": "[FILL IN: e.g., data-analysis]",
  "config": {
    "type": "cloud",
    "packages": {
      "pip": [
        "pandas",
        "numpy",
        "matplotlib",
        "scikit-learn",
        "openpyxl",
        "[FILL IN: any additional pip package — or delete this line]"
      ]
    },
    "networking": {
      "type": "limited",
      "allowed_hosts": [
        "[FILL IN: https://any-external-data-source.example.com — or delete]"
      ],
      "allow_package_managers": true,
      "allow_mcp_servers": false
    }
  }
}
```

### CLI

```bash
ant beta:environments create <<'YAML'
name: [FILL IN: data-analysis]
config:
  type: cloud
  packages:
    pip:
      - pandas
      - numpy
      - matplotlib
      - scikit-learn
      - openpyxl
      - [FILL IN: additional package or delete]
  networking:
    type: limited
    allowed_hosts:
      - [FILL IN: https://your-data-source.example.com or delete]
    allow_package_managers: true
    allow_mcp_servers: false
YAML
```

**Suggested tools to enable for this agent:** `bash` (for running Python scripts), `read`, `write`, `edit`. Disable `web_fetch` and `web_search` unless the analysis requires live data.

**Important:** Database servers (PostgreSQL, Redis) are NOT running in the container by default. If the agent needs to query an external database, add the host to `allowed_hosts` and connect via the pre-installed `psql` or `redis-cli` clients through a `bash` call.

---

## Config D — GitHub Code Reviewer

**Use this when:** The agent clones a repository, reads source files, and produces a code review. It needs to reach GitHub's servers but nothing else. Optionally connects to the GitHub MCP server for posting review comments.

**Tradeoffs:** The `allow_mcp_servers: true` flag is required if you want the agent to post PR comments via the GitHub MCP. Remove it if the agent only reads code locally and outputs a review file. The `authorization_token` for the repo is passed at session creation, not in the environment config.

### JSON

```json
{
  "name": "[FILL IN: e.g., github-code-reviewer]",
  "config": {
    "type": "cloud",
    "networking": {
      "type": "limited",
      "allowed_hosts": [
        "https://github.com",
        "https://api.github.com",
        "https://api.githubcopilot.com"
      ],
      "allow_package_managers": false,
      "allow_mcp_servers": true
    }
  }
}
```

### CLI

```bash
ant beta:environments create <<'YAML'
name: [FILL IN: github-code-reviewer]
config:
  type: cloud
  networking:
    type: limited
    allowed_hosts:
      - https://github.com
      - https://api.github.com
      - https://api.githubcopilot.com
    allow_package_managers: false
    allow_mcp_servers: true
YAML
```

**At session creation**, attach the repository as a resource:

```python
session = client.beta.sessions.create(
    agent=agent.id,
    environment_id=environment.id,
    resources=[
        {
            "type": "github_repository",
            "url": "https://github.com/[FILL IN: org/repo]",
            "mount_path": "/workspace/repo",
            "authorization_token": "[FILL IN: ghp_your_token]",
        },
    ],
)
```

**Suggested tools to enable:** `read`, `glob`, `grep`, `write`. Enable `bash` only if the agent needs to run tests or linters.

---

## Config E — Full-Power Developer Agent

**Use this when:** You are building or testing a complex development workflow and need maximum capability: unrestricted networking, all major runtimes, database clients, and build tools.

**Tradeoffs:** This is the most permissive configuration. Do not use it for production customer-facing deployments. Use it for your own development work, prototyping, or agents that run in a fully trusted environment. Because networking is unrestricted, a prompt injection attack on this agent would have more blast radius. Harden before shipping.

### JSON

```json
{
  "name": "[FILL IN: e.g., full-power-dev]",
  "config": {
    "type": "cloud",
    "packages": {
      "pip": [
        "requests",
        "httpx",
        "pydantic",
        "pytest",
        "[FILL IN: additional Python packages or delete]"
      ],
      "npm": [
        "typescript",
        "eslint",
        "[FILL IN: additional Node packages or delete]"
      ],
      "apt": [
        "[FILL IN: system packages — e.g., ffmpeg, postgresql-client, or delete]"
      ]
    },
    "networking": {
      "type": "unrestricted"
    }
  }
}
```

### CLI

```bash
ant beta:environments create <<'YAML'
name: [FILL IN: full-power-dev]
config:
  type: cloud
  packages:
    pip:
      - requests
      - httpx
      - pydantic
      - pytest
      - [FILL IN: additional package or delete]
    npm:
      - typescript
      - eslint
      - [FILL IN: additional package or delete]
    apt:
      - [FILL IN: e.g., postgresql-client or delete]
  networking:
    type: unrestricted
YAML
```

**Suggested tools to enable:** All 8 — `bash`, `read`, `write`, `edit`, `glob`, `grep`, `web_fetch`, `web_search`. Consider setting `bash` to `always_ask` permission policy for an extra confirmation step on shell commands.

**Before moving to production:** Switch from `unrestricted` to `limited` networking, enumerate only the hosts your agent actually needs, and disable any tools that aren't required for the specific task.

---

## Quick Reference — Which Config to Choose

| Your agent does... | Recommended config |
|---|---|
| Reads uploaded files, no web | Config A (limited, no allowed_hosts needed) |
| Browses the web, writes content | Config B (unrestricted) |
| Runs Python data analysis on files | Config C (limited + pandas stack) |
| Reviews GitHub code, posts PR comments | Config D (limited, GitHub hosts only) |
| General dev work, prototyping | Config E (unrestricted, full stack) |

---

## Worked Example — E-Commerce Price Monitor

*Fictional business: Bellwood Shop, a 3-person Shopify store. Owner Jaime wants an agent that checks competitor product prices twice a week and saves a comparison spreadsheet.*

**Chosen config:** Config B (Content Writer with Web Search) — the agent needs to browse multiple competitor product pages but only writes output locally. No code execution or external API calls are needed.

```bash
ant beta:environments create <<'YAML'
name: bellwood-price-monitor
config:
  type: cloud
  networking:
    type: unrestricted
YAML
```

**Why unrestricted?** The competitors' pricing pages are spread across 5-6 different domains that change occasionally as Jaime adds new competitors. Enumerating them all in `allowed_hosts` would require environment updates too frequently. Because the agent only uses `web_search`, `web_fetch`, and `write` (no `bash`), the risk of unrestricted networking is acceptable — there's no code execution path that could exfiltrate data.

**Tools enabled on the agent:** `web_search`, `web_fetch`, `write`. All others disabled via the whitelist pattern.