Environment gateway topology

Gateway topologyCopy Anchor Link

The gateway topology is the default: an instance runs a gateway in front of its servers unless its env was registered with another --env-provider-type. The gateway gives agents one MCP endpoint for every server, and adds a virtual clock, triggers, per-role tool access and a consistency mode that your servers don't have to implement.

A gateway instance of company, a multi env of 16 MCP envs built like office in Composing environments, runs the gateway MCP server, one container per MCP env in the multi env, and a Postgres database for managing env state. The gateway serves every server's tools at one /mcp, sends each call to the server that owns the tool, and records it in the trajectory at /trajectory.

The virtual clockCopy Anchor Link

The clock is off until PUT /clock/set-time arms it with a start time and a speed, from 0, frozen, to 86400 virtual seconds per real second. Once armed, it advances on its own, agents get a get_time tool, and the trajectory stamps each call with the virtual time:

curl -sS -X PUT http://localhost:61854/clock/set-time -H 'content-type: application/json' \
  -d '{"virtual_time": "2026-10-05T09:00:00Z", "virtual_seconds_per_real_second": 60}'

Servers that advertise sync_time under urn:agentenv:clock/v1 can follow the clock too. The sync_env_clock task step arms it and hands them its URL, so every run starts at the same virtual moment. Virtual Clock covers it in full.

TriggersCopy Anchor Link

A trigger fires on a virtual time, an action, a tool call that matches conditions, or a state of the world, and then calls a tool, changes a role's tool access with a permission, or hands an nl instruction to an executor agent. This one gives the agent send once it has looked up Sam:

{
  "triggers": [{
    "id": "unlock-send",
    "when": {"type": "action", "tool": "contacts_lookup", "where": {"args.name": {"regex": "Sam"}}},
    "actions": [{"type": "permission", "action": "enable", "role": "default", "tools": ["send"]}],
    "barrier": {"at": "provoking_call"}
  }]
}

The barrier holds the lookup's answer until the trigger has fired, so the agent's next step already sees send. Triggers watch the roles in watch_roles, default unless you say otherwise, and the register_env_triggers task step registers them. Triggers covers every condition and action.

Per-role tool accessCopy Anchor Link

curl -sS -X POST http://localhost:61854/tools/disable -H 'content-type: application/json' \
  -d '{"role": "assistant", "tools": ["send"]}'

RBAC covers roles, how rules combine and the modify_env_tool_access step.

Consistency modeCopy Anchor Link

In performance, the default, the gateway routes concurrent tool calls from many agents to their servers side by side, as fast as they arrive. In consistent, it runs them one at a time for serializable consistency, so every call sees the state the calls before it left:

agent-env env deploy --id company --gateway-mode consistent