Skip to main content

Execution environments

An execution environment keeps a session's file operations and shell commands in one workspace. Choose the default profile for workspace tasks or no-fs for sessions that need no local file access.

Availability​

The default profile is available in mecated, mecak8s, mecatui's embedded server, and engine embeddings. A session can instead select the no-fs profile for research, coordination, or remote deployments that must not expose a local filesystem.

Default workspace​

Create a default session with a workspace root. Read, ListDir, Write, Edit, Copy, Move, Remove, Grep, Glob, and Shell all use that root. The workspace requires a read before overwriting an existing file. Edits use exact, unique matches, and writes fail if the file changed after the read. Removal is non-recursive, copy accepts only regular files, and copy and move refuse an existing destination.

A new run or process may require another Read before Edit or an existing-file Write because the version record belongs to the live environment. This fail-safe check does not mean file data was lost.

The no-filesystem profile​

Create a no-filesystem session by setting profile: "no-fs":

curl -s -X POST http://127.0.0.1:8081/v1/sessions \
  -d '{"profile":"no-fs"}'

The profile requires an empty workspace. Any other profile value is rejected; there is no silent fallback. A no-FS catalog removes Read, ListDir, Write, Edit, Copy, Move, Remove, Grep, Glob, Shell, ShellStatus, Parallel, and SkillDraft. It retains web tools, memory, MCP tools, skills, Subagent, and Team; children use the same file-less tool set and cannot create a shell or fork a workspace.

The profile is fixed at session creation. The model cannot switch it during a run. See Core tools for the complete catalog.

Child environments​

Different delegation modes use different environment strategies:

  • Read-only Subagent and team members get a child environment. When the workspace is trusted, the harness can use a worktree so child changes are isolated. An untrusted workspace withholds the read-only child shell because creating a worktree requires operating on the repository's .git.
  • Parallel branches use hardened force-copy environments. The initial copy does not invoke Git; each branch then works in its own copied namespace.
  • Mutating members and direct-write Subagents use the parent environment and modify the real workspace. They are serialized against sibling tool calls; there is no merge-back step.

All agent-facing shells use a secret-scrubbed environment. Provider keys, MECATL_* credentials, cloud credentials, and other secret-shaped variables are removed before a command runs.

Persistence and reattachment​

The environment identity is persisted with a session snapshot. Mecatl reconstructs local and no-FS environments. A non-local identity can be reattached only when the deployment supplies an EnvironmentResolver; a missing resolver, mismatched identity, or nil workspace returns an error instead of using a local workspace.

Live qualification (experimental)​

The repository keeps real-provider qualification separate from the default mock suite. It is explicit opt-in, uses an already-owned retained Kind cluster, and is not part of task test:

MECATL_EXECUTION_CREDENTIAL_FILE=/absolute/path/to/provider-key \
MECATL_EXECUTION_QUAL_STATE=/absolute/path/to/owned-state \
task e2e:k8s:execution:live

The credential file must be a private regular file (no group or other access). A trusted helper loads it only at runtime and creates a run-scoped Kubernetes Secret through the API; it never renders the value into a manifest or reads the Secret back. Only the mecak8s harness container receives the OpenRouter key. The execution provider, controller, OIDC fixture, and executor workloads do not. The task first runs the deterministic mock qualification, then runs one bounded real-model coding smoke against https://openrouter.ai/api/v1. It verifies positive token usage, required file and shell tool calls, file contents, and a successful go test independently through the typed gRPC execution service. Finally it restores the mock deployment and removes only its run-scoped Secret; the owned cluster and execution workspaces remain for inspection.

Limitations​

  • No-FS sessions cannot use local file tools, shell commands, workspace forks, or parallel branches.
  • Read-only child shells depend on project trust; this is separate from the parent's ability to run its own shell.
  • Direct-write children can leave partial edits if cancelled or interrupted; the parent workspace and Git are the rollback boundary.
  • Remote environment reattachment requires an explicit resolver.

Next steps​