Sandboxes

A sandbox determines where and how an agent's runtime process launches. Toolang supports host and Docker sandboxes.

Sources and execution environments

Source placement and sandbox choice are separate. A local agent, a fetched shared agent, or a local script can use an execution environment independently of where its source came from.

The same runnables, drivers, and run history concepts apply in either environment. A sandbox changes the process environment, installed resources, and physical paths available to execution.

Workspaces and isolation

A Docker sandbox mounts configured workspaces into the guest. Logical workspace paths retain their meaning even when host and guest paths differ. Mounted directories expose their contents to the guest; writes to a writable mount affect those files on the host.

The host sandbox uses host process permissions. Workspace grants constrain workspace-aware tools, but do not provide operating system isolation for shell commands. Docker's boundary also depends on its mounts and configuration.

Lifecycle

serve runs in the foreground; start launches a background runtime and returns after it is ready. Server lifetime also depends on how it was acquired: leaving a client does not always stop the agent. See Agents.

Changes to container mounts require a restart. Stopping a sandbox is different from canceling one run: an agent runtime can host several independent activities.

See Create and run agents and Configuration for sandbox selection.