Skip to main content

Overview

An environment is everything a session needs except the conversation: which harness runs, which model it talks to, how big the sandbox is, what the network may reach, which secrets and MCP servers are available, which skills are installed, and which tools are allowed. Create one, then start as many sessions from it as you like. Every edit is a new immutable version. A session pins the version it started with, so changing an environment never alters a running or paused session.

Create one

environment.toml

Fields

The API returns the normalized spec: defaults filled in, hostnames lowercased, duplicate entries removed, skills pinned, and every secret the spec references (including the model’s and each MCP server’s) listed in secrets. That is exactly what the sandbox is built from, and what veri environments get --toml prints.

Egress

Every session runs behind an egress proxy at the edge of its sandbox. It terminates TLS, decides each HTTP request against the environment’s rules, attaches scoped secrets to the hosts they belong to, and records the request on the transcript. In restricted and audited_open the sandbox has no other way out: only ports 80 and 443 exist, and every request on them passes the proxy. Plain HTTP is refused with a 403 (a secret must never travel in the clear). unrestricted needs an Enterprise workspace; creating or updating an environment with it otherwise returns 400 UNRESTRICTED_EGRESS_NOT_ENABLED. The check runs when an environment version is created, so versions that already use unrestricted keep starting sessions.

Presets

The model host, every MCP host (including the Tools servers: backend.composio.dev and the Veri MCP on api.veri.studio) and the approval endpoint are always reachable, whatever the preset and the rules say.

Egress rules

  • host is an exact hostname or one leading wildcard label: *.example.com matches a.example.com and a.b.example.com, never example.com itself. A bare *, inner wildcards and IP addresses are refused.
  • methods are GET, HEAD, OPTIONS, POST, PUT, PATCH, DELETE. GET does not imply HEAD; list both if a tool needs them.
  • paths are prefixes of the URL path, compared before any decoding; end one with / to mean a directory (/repos/my-org also matches /repos/my-org-other). A request whose path contains an encoded /, \ or . (%2F, %5C, %2E) is refused under a path rule.
  • Rules only allow. A request passes when any rule for its host allows its method and its path.
  • A rule (or an allowed_hosts entry) that names a host replaces the preset’s access to that host. The example above makes GitHub’s API read-only under /repos/my-org/ even with the coding preset, which otherwise allows every request to it.
  • At most 200 egress_rules and allowed_hosts together.
A refused request gets a 403 with a JSON body that says why, so the agent (and you, in the transcript) can tell which rule to add:
constraint is host (host not allowed: example.com), method, path, scheme (plain HTTP) or host_header (a Host header that names a different host than the URL). Every request, allowed or refused, is recorded as an agent.egress event.

Certificates in the sandbox

The proxy terminates TLS with a certificate authority that exists only inside the running sandbox. The system trust store (/etc/ssl/certs/ca-certificates.crt) includes it, and the harness’s environment points the common clients at it: NODE_EXTRA_CA_CERTS (Node), REQUESTS_CA_BUNDLE, SSL_CERT_FILE and PIP_CERT (Python, pip, Go and OpenSSL-based tools), CURL_CA_BUNDLE (curl), GIT_SSL_CAINFO (git’s http.sslCAInfo) and DENO_CERT. A tool that ships its own certificate list or pins certificates (a Java keystore, some prebuilt binaries) fails TLS until you point it at the system store, for example keytool -importcert for Java. If you override one of these variables in env, keep it pointing at the system store.

Private endpoints

The sandbox has no static egress IP, so an IP allowlist on your side cannot single it out. To let an agent reach a private service, publish it through Cloudflare Tunnel on a hostname protected by Cloudflare Access with a service token, then store the token as two secrets bound to that hostname:
The agent sends CF-Access-Client-Id: $CF_ACCESS_CLIENT_ID and CF-Access-Client-Secret: $CF_ACCESS_CLIENT_SECRET. The sandbox only ever holds placeholders; the proxy swaps in the real values on requests to internal-api.example.com and nowhere else. A reverse proxy of your own that checks a bearer secret works the same way.

Permissions

Rules name tools either with the harness-neutral names (bash, bash(<command glob>), file.read, file.write, web.fetch, web.search, git.*, mcp, mcp.<server>, mcp.<server>.<tool>, *), which every harness renders into its own config, or with Claude Code’s own syntax (Bash(git *), Read, mcp__server__tool), which claude-code uses as written. The Harnesses page has the full mapping and what each harness supports. On claude-code:
  • default = "allow" runs the harness in Claude Code’s bypassPermissions mode: every tool call that no deny rule matches runs without a prompt. Sessions are unattended, so this is the mode to use when the sandbox and the egress rules are the boundary you rely on.
  • default = "deny" runs it in dontAsk mode: only tools matched by an allow rule run; everything else is refused without a prompt and the agent is told so.
  • deny rules bind in every mode, including bypassPermissions. allow rules only matter under default = "deny".
  • ask stops the session for a human decision. When the agent calls a tool whose last matching rule is ask (or any tool, under default = "ask"), the harness parks the turn before the call runs, the session becomes awaiting_approval, the transcript gets an agent.approval_request and the session.approval_requested webhook fires. Answer with user.approval (veri sessions approve <session> <approval> allow|deny [--message], the session page, or POST /v1/sessions/{id}/events); on allow the call runs and the turn continues, on deny the agent reads your message as the reason and continues without it. If the approval check itself cannot complete, the call is refused, never run. See Approvals. Triggers run with nobody to answer, so an environment that uses ask cannot be triggered.
Rules are a flat list and the last match wins: [{tool = "bash", action = "ask"}, {tool = "bash(git *)", action = "allow"}, {tool = "bash(rm *)", action = "deny"}] asks for every shell command except git ... (allowed) and rm ... (denied). bash(prefix *) matches commands starting with prefix; mcp.server matches every tool of an MCP server; * matches everything. With Claude Code’s syntax, Read(/etc/*) and Edit(*.md) also match the file path (claude-code only). OpenCode supports allow and deny rules but not ask; the custom harness supports no rules (it runs your own process). An environment whose rules its harness cannot enforce is rejected with 400 when you create it. What to expect while a session waits:
  • Nothing bills: the sandbox is snapshotted and stopped the moment the turn parks, and restored when you decide (a few seconds, like a resume).
  • A request expires after permissions.approval_ttl_s seconds without an answer (60 to 86400, default 1800, so 30 minutes) and counts as a deny (the transcript shows user.approval with reason: "timeout"); the turn resumes so the agent can finish without the call. Set it per environment, for example approval_ttl_s = 7200 under [permissions] for a two-hour window.
  • user.message returns 409 until the pending approval is answered. One approval is open at a time; a second ask that fires meanwhile is denied, not queued.
  • ask is best effort, like every rule that governs Bash and file tools: it is enforced by the harness’s own permission system inside the sandbox. deny rules, the egress rules and secret scoping are the hard boundaries. A deny on WebFetch stops the harness’s fetch tool, not curl; to keep the agent away from a host, leave it out of the egress rules.

Versions

POST /v1/environments/{id}/versions with a full spec appends version latest + 1. Deleting an environment hides it and stops new sessions; existing sessions keep their pinned version.