Designing the Agent's Environment: Workspace, Runtime, and Directories<br>← Facundo<br>June 20, 2026<br>Designing the Agent's Environment: Workspace, Runtime, and Directories

This is the first in a series of documents where I work through the architecture of an agent-orchestration library I'm building. This first one is about the environment in which the agent runs.

The problem with one workspace is that it forces very different kinds of things to live in the same place: the code the agent works on, the artifacts it produces that I want to look at, and the secrets I hand it.

For this I defined three directories:

code]:bg-transparent [&>code]:px-0 [&>code]:py-0 [&>code]:rounded-none">.artifacts/<br>agents/<br>common/<br>.secrets/<br>agents/<br>common/<br>.workspaces/<br>--/

With this split each kind of thing gets treated the way it actually needs to be, and the workspace is free to be whatever the agent needs without dragging secrets and artifacts along with it.<br>Secrets can be made read only, so the agent can use them but not modify or delete them. Artifacts live on their own, separate from the workspace, so I can track them, diff them, or look at just what the agent produced without wading through every edit it made to get there.

Having a separate secrets directory makes credential handling simple. Secrets now have a known home, getting a credential to an agent is just a matter of putting the file in the right place, and the runtime knows where to look for it.

In practice it works like this:

An init --copy-credentials subcommand reads the credentials I already have on my machine, the ones each tool writes to its own spot in my home directory (~/.claude/.credentials.json, ~/.codex/auth.json, ~/.config/gh/hosts.yml, and so on), and stages copies in the common secrets directory so they're shared across agents.

When an agent starts in a container, the image looks for credentials first in /secrets/agent, then in /secrets/common, and copies whatever it finds back to the path the tool expects. So authentication just happens, without me logging in inside every container I spawn.

There's also a doctor subcommand that checks for this and tells me when something's missing, like a provider with no auth file or no GitHub PAT.

The same mechanism handles environment variables. Drop an .env file in the secrets directory and the runtime reads it and exports the values into the agent's session.

Agent Identifiers

I wanted a quick way to tell whether a branch or workspace is owned by an agent at all, and if so, which one.

constant aiagent-: A branch or directory that starts with aiagent- is an agent's. I can spot it at a glance, filter for it (git branch | grep aiagent-), or clean up agent workspaces by the prefix alone, without it ever being confused with a branch a person made.

name : Names are readable and you choose them, which makes them the part you actually recognize when scanning a list. But I wanted something more, like an id.

letter : unique and auto-incremented, starting from a, and never reused. Once you pass z it rolls over to aa, ab, and so on. The letter does two things the name can't:

It is guaranteed unique, so it disambiguates two agents that happen to share a name. It is short, which matters once it shows up in branch names, directory names, and everywhere else an agent gets referenced.

Letters are handed out in order, so a higher letter means a more recently created agent.

Put together, the id is:

code]:bg-transparent [&>code]:px-0 [&>code]:py-0 [&>code]:rounded-none">aiagent--

The same three parts name the agent's branch, with / instead of -, since that's how git namespaces branches:

code]:bg-transparent [&>code]:px-0 [&>code]:py-0 [&>code]:rounded-none">aiagent//

So every agent branch lives under aiagent/, which is what makes the "is this branch an agent's?" check trivial: it's any branch under that prefix.

Inside the agent directories the prefix is dropped, since everything there is already an agent's:

code]:bg-transparent [&>code]:px-0 [&>code]:py-0 [&>code]:rounded-none">workspace: .agents/.workspaces/-/<br>artifacts: .agents/.artifacts/agents/-/<br>secrets: .agents/.secrets/agents/-/

The prefix only earns its place where agent work sits next to human work, like git branches. In a directory that already holds nothing but agents, aiagent- would just be noise.

Agent Environment

workspace: where the code lies

runtime: where the agent lies

Workspace

The workspace is the part that makes sure there is somewhere for the agent to work. In practice that means a few steps:

Directories: create the workspace and wire up the artifacts and secrets directories from before.

Git: clone or set up a worktree, create the branch, and so on.

Skills wiring: skills are just files, so they get linked into the agent's environment. I'll go into this in a later document.

on_provision: a hook for any custom commands the user wants to run when the workspace is set up.

Step 1: Artifacts and Secrets

The artifacts and secrets live...