Deploying your environment

Deploying runs your server in a sandbox, an isolated machine or set of containers that the framework starts for it. This page deploys the EmailEnv from Creating your own environment. You register the environment once, and then deploy it as often as you need. Each deploy is a new env instance, with its own id, its own inbox and its own URLs.

Package itCopy Anchor Link

Start Docker before continuing; this tutorial builds and runs containers locally.

The framework deploys container images, so the first step is a Dockerfile next to server.py:

FROM python:3.12-slim
WORKDIR /app
RUN pip install --no-cache-dir agentenv-framework-protocol "mcp>=1.25,<2"
COPY server.py .
CMD ["python", "server.py"]

Register itCopy Anchor Link

Registering builds the image and stores it as an artifact, a stored object that the framework versions. It then stores the env, a document that points at that artifact, under an id you choose. These pages use the id email:

agent-env env mcp-server put --id email --dockerfile email/Dockerfile

Derived environment_name='email' from the environment card.
Building MCP server Docker image...
Creating DockerImageArtifact...
Created artifact: id=mcp-server-email version=1
Creating MCPServerEnv...
Created MCPServerEnv: id=email version=1 environment_name=email env_provider_type=gateway

The first line of the output is the command reading the name email from @environment_card in your source; The environment card explains what the name is for. env_provider_type is the topology from Choose the environment's topology. Each put of the same id stores a new version and leaves the older ones unchanged.

Deploy itCopy Anchor Link

Before your first deploy, the default topology needs default-db and default registered in your current registry. Run each command below only if that env is missing; agent-env up may have registered it already:

agent-env env service-db put --id default-db
agent-env env gateway put --id default

With those envs and email registered, one command deploys it:

agent-env env deploy --id email

Sandbox backend: config default
Fetching env: id=email version=latest...
Found env: id=email version=1 type=mcp_server
Deploying (ttl=10800s, gateway_mode=performance, disk=10.0GB)...
Deployed!
Instance ID: email-mmtflq6t
Env MCP Url: http://localhost:61655/mcp
Env Gateway Url: http://localhost:61655
Env DB Web Url: http://localhost:61656/
Env DB MCP Url: http://localhost:61657/mcp
Expires At (UTC): 2026-09-29 09:23 UTC

Env MCP Url is how an agent uses your environment's tools: an agent connected there can call email_search and send.

Where the instance runs depends on the sandbox. The default is local, where each part of the instance is a container on your machine's Docker. --sandbox picks another built-in, such as modal_vm, or a provider you register under [sandbox.providers.<name>] in config.toml.

The framework records every instance. agent-env env get-instance --id email-mmtflq6t reads the record back: the env id and the exact version it deployed, the instance's URLs, the sandbox it runs in and when it expires. The record also stores the card the instance served, which The Environment Card shows.

Use itCopy Anchor Link

An agent uses your environment through the interfaces the instance's card declares. The card's MCP interface gives the URL to connect to, and its name the MCP server the agent sees: env4276 at http://localhost:61655/mcp. In a task, a deploy_agent step reads both from the instance's record and hands them to the agent, which lists the tools the card advertises and calls them.

Other interfaces are declared the same way, as extensions on the card, and the framework uses one only when the card lists it. Behind the gateway, urn:agentenv:step/v1 adds /step, which lists and calls the same tools over REST, and a server that serves an interface manifest adds urn:agentenv:get-interfaces/v1, from which agent-env env mcp-server create-cli builds a command-line tool. The environment card covers every field.

Tear it downCopy Anchor Link

Deploying again starts another instance with another id, and the env itself never changes. An instance runs until its TTL runs out, which you set with --ttl-seconds, or until you close it. You close an instance from Python by its id:

import asyncio

from agent_env.env import Env


async def main() -> None:
    env = await Env.from_instance_id("email-mmtflq6t")
    await env.close()


asyncio.run(main())

Env.from_instance_id reconnects to the instance's sandbox and close() stops it. In a task, a deploy_env step and a teardown_sandboxes step deploy and close instances for you.

Every instance on this page ran behind a gateway, the default topology. Choose the environment's topology covers the other shapes an instance can take.