Manage workspaces

Workspaces give agents access to local directories. You can configure persistent workspaces or grant temporary access, then choose the working directory for execution.

Configure workspaces

Add an existing directory as a workspace for an agent:

mkdir -p project
too eve workspace add ./project --name repo
too eve workspace list

The add command saves the directory's absolute path in the agent's configuration. If --name is omitted, Toolang derives a kebab-case name from the directory.

Remove a configured workspace with:

too eve workspace remove repo

Removing a workspace does not delete its directory or files.

The same commands work with standalone scripts:

too helpers.too workspace add ./project --name repo
too helpers.too workspace list

Workspace listings include applicable root-level overrides. Use too eve info to inspect runtime workspaces, including the Toolang-managed lab workspace, which cannot be replaced.

Grant temporary access

Use -w/--workspace to grant access to a directory without changing persistent configuration:

mkdir -p scratch
too eve chat -w scratch=./scratch

You can specify multiple workspaces by repeating -w. Temporary grants have different lifetimes depending on how the runtime is started:

If a resident agent is already running, stop it before changing its temporary workspace bindings:

too eve stop
too eve chat -w scratch=./scratch

Scripts automatically grant their source directory when no -w option is provided. Explicit workspace grants replace this default.

The start command uses configured workspaces, while chat and serve also accept temporary grants.

Set the working directory

Use -d/--workdir to select where the agent's tools operate:

too eve chat -d repo://

Here, repo:// refers to the root of the configured repo workspace.

You can also grant a temporary workspace and select its working directory in one command:

too eve chat -w scratch=./scratch -d scratch://

Within chat, use :workdir to change the default for later submissions, or /workdir to override it for a single submission:

:workdir repo://

/workdir repo://

A workspace URI selects an existing grant without adding access. Passing a local directory to --workdir also creates a temporary grant.

By default, Toolang selects the last usable workspace as the working directory, starting with lab.

Access and isolation

Workspace grants control access for workspace-aware tools, but they do not isolate shell commands. Shell processes retain the permissions of their host or sandbox.

A file reference such as @README.md includes content from the directory where the command was launched, without granting filesystem access.

Changes to workspace configuration do not affect grants already captured by accepted runs. Docker-hosted agents also need to be restarted when workspace mounts change.