Workspaces

A workspace is a named directory grant. It identifies files an agent's workspace-aware tools may access. A workdir selects the current working location inside an existing grant.

Names and logical paths

A workspace named repo can refer to your project directory. The logical path repo://src identifies its src directory, even when the physical path differs between the host and a container.

Tools can use logical paths, paths relative to the workdir, or absolute paths inside an authorized workspace. Path resolution prevents traversal and symlinks from escaping the grant.

Changing the workdir selects among accessible locations; it does not grant a new directory. The client's current directory and the .too source directory are also separate from the runtime workdir.

Lab and grants

Every agent has an implicit lab, a Toolang-managed workspace for its work. Additional grants come from configuration or invocation options. Temporary grants apply to that invocation without becoming saved configuration.

A root run captures its workspace grants and passes them to child runs. Editing configuration does not add new directory access to already accepted work. Concurrent instances of the same local script can share lab contents even when their execution records are separate.

Attachments and isolation

An @file input supplies captured content to a request. Attaching a document does not grant tools access to its containing directory.

Workspace checks protect tools that use those checks. A shell command runs with the process's operating system permissions; directory grants alone do not isolate arbitrary commands. Sandboxes define the process environment and its mounted directories.

See Manage workspaces for adding grants and choosing a workdir.