Workspace mode¶

Workspace mode lets an agent run tools in a selected folder on the Backend.AI GO host. It is off by default for each profile. Project assets and user instructions have separate settings, also off by default.

Without workspace mode, a run that has no working directory works in its own folder inside the code execution sandbox folder, and its commands run only inside the sandbox. See Where Files and Commands Run.

Enable a workspace¶

1. Open the saved agent profile you intend to run.
2. Enable its workspace setting and select the host folder.
3. Save the profile and start a new agent run using it.
4. Confirm the active run's Context rail shows the expected workspace path and host-access warning.

The saved profile is the authority for the folder. Supplying a path in a prompt does not grant workspace access. Exporting or importing a profile clears its workspace grant. Published-agent runs do not inherit the saved host workspace. Mobile does not support host workspace mode.

Approve shell commands¶

For a read-only check, ask the agent to run git status --short in a disposable repository. When the approval request appears, review the command and approve it once. A second command requires a new approval, even when the first was approved. Stopping the run cancels its owned command process tree.

Workflow skills can use host commands such as gh and bundled scripts after approval. Those programs must already exist on the host. Credentials come from the host's configuration; do not put credentials in the requested command. Commands containing recognizable literal credentials are refused before approval.

A skill's allowed-tools does not auto-approve host shell calls. Profile denies and enterprise policies still apply. One-shot tool calls cannot acquire workspace shell permission; use an agent run so approval and cancellation belong to a live run.

File boundaries and blocked operations¶

File tools resolve paths below the saved workspace. Reads may also use the active skill directory; writes there are refused. Symbolic links, reparse traversal, and a changed workspace identity are rejected. These file-tool restrictions do not confine an approved host shell.

The shell scanner refuses recognizable disk-formatting, raw-disk, mount, account-management, privilege-elevation, shutdown, and restart commands. It cannot prove an arbitrary script or executable safe. On macOS and Linux, approved commands use /bin/sh; Windows uses the fixed system PowerShell with profiles disabled.

Instruction files¶

In Settings > Tools > Workspace context, enable either scope you want new workspace runs to load:

Both settings are off initially and apply only to runs with an enabled saved host workspace. Turning on user instructions does not make them apply to unrelated runs without a workspace. A setting change takes effect in a new run.

User instructions precede the workspace's CLAUDE.md and AGENTS.md, after the profile instructions. Only the selected root is read; parent and nested folders are not searched for more instruction files. @path imports are not expanded.

Instruction files are read once when the run starts. Each file contributes at most 256 KiB, with 1 MiB total and at most 64 user rule files. The run's Context view records loaded, truncated, skipped, and failed files. Truncation preserves valid UTF-8 boundaries. When the model's context window is known and the resulting request cannot fit, the run reports a context error before sending the request. Use a larger model context or change the inputs and start a new run. If the model window is unknown, the provider validates the request.

Workspace skills and agents¶

Workspace extensions belong to the current run and do not appear as global imports. Review a workspace skill or command from Run workspace context and approve its exact definition for that run. An unapproved skill or command stays out of the model-facing catalog. File changes require another review and approval. Workspace agents are shown as available and do not use definition approval. Definition approval does not approve tool calls. Approval does not override disable-model-invocation. Legacy commands stay out of the model catalog unless their definition explicitly sets it to false.

The runtime resolves same-name items using the external asset precedence. Workspace specificity wins only within the same origin. The view displays the backend's winner and shadowed entries.

Delegated agents inherit the validated workspace and captured instruction settings, then load their own context. They do not inherit the parent's skill approvals. Completed runs display their saved context evidence without reopening files or accepting new approvals.

Headless and mobile behavior¶

For a headless run, the workspace path and user instruction files belong to the server. Host commands use the server account's tools and credentials. Configure a saved profile on that server, start its run through the authenticated agent API or connected UI, and answer tool approvals through that run.

Use the run-local item ID and reviewed hash returned by inspection when reviewing from the CLI:

aigo agent inspect-extension <run-id> <item-id>
aigo agent approve-extension <run-id> <item-id> --reviewed-hash <hash>

Inspection and definition approval are accepted only while that run is active. The completed run keeps presentation evidence for history, but it cannot grant a new approval.

Mobile refuses workspace mode. A profile transported to another installation carries no workspace grant; configure and review the destination host's folder separately.