Workspaces and terminals — explanation

What is this about?

An agent works in a folder: its instructions (AGENTS.md), its skills, what it writes. Seeing that folder, fixing an instruction or running a command there should not require a Finder window and a terminal opened by hand — least of all for someone who is not a developer. The Agents panel therefore shows each agent's folder, with an editor and a terminal, wherever the agent runs. This page explains the choices behind it; the decisions are in ADR 0007, the exact behaviour in the reference.

One idea of a workspace, several places

An agent may run on this computer, in a Docker container, or in a Docker sandbox. Each place is reached differently — the disk directly, docker exec or sbx exec — but the tree, the editor and the terminal should not care. Sidekicks hides the difference behind a single notion of workspace: list a folder, read, write, delete, follow changes, open a shell. The same tests run against a local folder, a real container and a real sandbox, so all three behave alike.

The container side only uses commands that tiny images also have (busybox find, stat, cat). A workspace that works only with a full Linux distribution would surprise users of the small images agents are often packaged in.

Sandboxes came last. sbx is not available where Sidekicks is built, so rather than guessing, the sandbox side waited for the owner to describe sbx exec and run the test suite on a real sandbox. It turned out to mirror docker exec, and Sidekicks reaches both the same way, using only the options the two share.

Editing next to an agent that is working

The agent and the user may touch the same file. Two rules keep that safe. First, a file is always replaced in one step (written beside, then moved over): the agent never reads half a file. Second, a save remembers which version of the file was opened; if the agent changed it meanwhile, nothing is overwritten silently — the user chooses between their version and the agent's.

Deleting without regret

A deletion from a graphical tool is expected to be reversible. On this computer, deleted files go to the system trash. A container or a sandbox has no trash, so the confirmation says the deletion is final rather than pretending otherwise.

Terminals that leave nothing behind

A terminal is a real shell behind a pseudo-terminal, so full-screen programs work and the size follows the panel. Closing it must end what was started from it — including programs sent to the background, which a simple "kill the shell" misses. In a container there is a trap: stopping the docker exec client leaves the shell running inside the container. Sidekicks therefore ends the shell's whole session on the container's side too. Both cases were found by testing, not by reading.

How it relates to the rest

Channels and what each agent knows: the conversation is the main way to work with an agent; the workspace is where to look when something needs checking.
Memory and local models: opening a workspace or a terminal does not start the agent.
Architecture: internal/workspace reaches the folders, internal/app exposes them to the interface.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31


# Workspaces and terminals — explanation

## What is this about?

An agent works in a folder: its instructions (`AGENTS.md`), its skills, what it writes. Seeing that folder, fixing an instruction or running a command there should not require a Finder window and a terminal opened by hand — least of all for someone who is not a developer. The Agents panel therefore shows each agent's folder, with an editor and a terminal, wherever the agent runs. This page explains the choices behind it; the decisions are in [ADR 0007](../../adr/0007-agent-workspaces.md), the exact behaviour in the [reference](../reference/agents-and-events.md#workspaces-milestone-m4).

## One idea of a workspace, several places

An agent may run on this computer, in a Docker container, or in a Docker sandbox. Each place is reached differently — the disk directly, `docker exec` or `sbx exec` — but the tree, the editor and the terminal should not care. Sidekicks hides the difference behind a single notion of workspace: list a folder, read, write, delete, follow changes, open a shell. The same tests run against a local folder, a real container and a real sandbox, so all three behave alike.

The container side only uses commands that tiny images also have (busybox `find`, `stat`, `cat`). A workspace that works only with a full Linux distribution would surprise users of the small images agents are often packaged in.

Sandboxes came last. `sbx` is not available where Sidekicks is built, so rather than guessing, the sandbox side waited for the owner to describe `sbx exec` and run the test suite on a real sandbox. It turned out to mirror `docker exec`, and Sidekicks reaches both the same way, using only the options the two share.

## Editing next to an agent that is working

The agent and the user may touch the same file. Two rules keep that safe. First, a file is always replaced in one step (written beside, then moved over): the agent never reads half a file. Second, a save remembers which version of the file was opened; if the agent changed it meanwhile, nothing is overwritten silently — the user chooses between their version and the agent's.

## Deleting without regret

A deletion from a graphical tool is expected to be reversible. On this computer, deleted files go to the system trash. A container or a sandbox has no trash, so the confirmation says the deletion is final rather than pretending otherwise.

## Terminals that leave nothing behind

A terminal is a real shell behind a pseudo-terminal, so full-screen programs work and the size follows the panel. Closing it must end what was started from it — including programs sent to the background, which a simple "kill the shell" misses. In a container there is a trap: stopping the `docker exec` client leaves the shell running inside the container. Sidekicks therefore ends the shell's whole session on the container's side too. Both cases were found by testing, not by reading.

## How it relates to the rest

- [Channels and what each agent knows](channels-and-context.md): the conversation is the main way to work with an agent; the workspace is where to look when something needs checking.
- [Memory and local models](memory-and-local-models.md): opening a workspace or a terminal does not start the agent.
- [Architecture](architecture.md): `internal/workspace` reaches the folders, `internal/app` exposes them to the interface.