Workspaces, runners and environments

A workspace owns file access. A runner owns process execution. An environment combines resources and lifecycle for a session. The model requests tools; the application chooses the environment and its authority.

Start with one bounded workspace

For repository work, use the maintained coding preset:

uvx cayu new repo-agent --preset coding

The generator checks required Git, rg and secure local-workspace primitives before creating the project. Read the generated instructions for your host and selected adapters. Keep workspace construction in environments/, tools in tools/, and their admission rules in policies/.

Choose the root explicitly. Test traversal, symlinks, oversized reads and commands outside the allowed toolchain. Host-process Python tools remain trusted application code; a local workspace is not an operating-system sandbox for arbitrary Python.

Add isolation at the execution boundary

Use a suitable runner and environment when the agent must execute untrusted commands. Configure the image, resource limits, network policy, credentials and shutdown behavior before exposing a terminal tool. An environment ID does not itself authorize access to another environment.

Record artifacts and useful results before cleanup. After a crash, a process may be gone while an external container or workspace still exists. Recovery must reconcile its recorded lifecycle; cancellation alone does not prove that cleanup completed.

Verify the lifecycle

Run a small harmless command, inspect its exit status, produce one bounded artifact, interrupt execution, and confirm the selected environment’s cleanup evidence. Repeat with allocation failure and delayed cleanup. Keep remote provider qualification separate from deterministic application tests.

Reference: environments, workspaces, runners and resources.