security(agent-server): isolate builder tools from process secrets and sibling projects

[alexanderkreidich]

Problem

agent-server 0.2.1 hosts every project in one process and gives each Pi session the default read, bash, edit, and write tools. These tools execute in the outer container:

• bash inherits the whole agent-server process environment, including AGENT_SERVER_TOKEN and LITELLM_API_KEY;
• file tools accept absolute paths, so a project session can read sibling workspaces and .pi-global;
• every project shares one rootless Podman socket/store, so podman can inspect or mutate sibling app resources;
• unrestricted network access lets generated commands reach arbitrary Internet/private/metadata endpoints.

OpenOrange's HTTP proxy authorizes projects correctly, but that does not form a tenant boundary once one authorized session can escape through the shared builder shell.

Concrete trigger

An owner sends a prompt asking the builder to run commands equivalent to:

env | grep -E '^(AGENT_SERVER_TOKEN|LITELLM_API_KEY)='
find /workspace -maxdepth 2 -type f
podman ps -a

The tool subprocess inherits the process env and operates against the shared workspace/store.

Required properties

• provider credentials and the server bearer token must not exist in tool subprocess environments;
• all file tools must be confined to the current project root, including symlink/canonical-path checks;
• project shell/container operations must not be able to address sibling projects/resources;
• egress must have an enforceable policy that blocks private/link-local/cloud-metadata targets while retaining package/image/model access required to build apps;
• regression tests should prove a malicious prompt/tool call cannot read process secrets, sibling workspace/session files, sibling Podman resources, or private-network targets.

Prompt instructions such as “never print secrets” are not a security boundary.

[alexanderkreidich]

Implementation proposal: Pi isolation extension + scoped Podman access

Pi gives us the right seams to implement every required property without forking the agent. The key mechanisms are documented in pi-coding-agent (docs/extensions.md "Remote Execution", docs/containerization.md, examples/extensions/gondolin/, examples/extensions/sandbox/).

1. In-process isolation extension per project

ProjectRuntime already passes config.extensionFactories into createAgentSessionServices(). We add an isolation extension as an in-process factory closed over projectDir — it is compiled into agent-server, so project content or prompts can never disable or replace it.

2. File tools: realpath confinement

Registering a tool with a built-in name (read, write, edit, grep, find, ls) replaces the built-in. We use Pi's factories with custom operations:

const writeTool = createWriteTool(projectDir, { operations: confinedOps(projectDir) });
pi.registerTool(writeTool);

Every operation canonicalizes the target at I/O time:

const abs = await realpath(resolve(projectDir, inputPath));
if (abs !== projectRoot && !abs.startsWith(projectRoot + sep))
  throw new Error("path escapes project root");

This blocks absolute paths into sibling workspaces, ../ traversal, and symlink escapes (realpath resolves the link target, and doing it inside the operation avoids TOCTOU). A tool_call handler alone is not sufficient — it checks a string before execution, not the filesystem at execution time.

3. Bash: route into the per-project builder container

Bash executes arbitrary code, so no string-level check is a boundary. Instead the extension overrides bash with createBashTool(projectDir, { operations }) where BashOperations.exec runs the command via podman exec inside the project's builder container:

• only /workspace/{projectId} is bind-mounted — sibling workspaces and .pi-global do not exist in the container's mount namespace;
• env is built from an explicit allowlist (PATH, HOME, LANG, …) via spawnHook; exposeSessionEnvironment: false — AGENT_SERVER_TOKEN / LITELLM_API_KEY never enter the subprocess;
• user_bash (! commands) is routed through the same operations.

This is the same pattern as Pi's Gondolin example, with podman exec instead of a micro-VM.

4. Podman socket isolation

The shared rootless socket is the tenant-boundary hole. Do not mount the host Podman socket into builder containers. Options, in order of preference:

1. No socket at all inside the builder container; app-container lifecycle stays a control-plane concern of agent-server (it already owns appContainers.ts).
2. If builder sessions legitimately need container ops: a socket proxy (e.g. a small filtering proxy in front of the Podman API) that scopes requests to resources labeled appx.project={id} and rejects everything else.
3. Alternatively separate rootless users / podman system service instances per project — stronger but operationally heavier.

5. Egress policy

Attach builder containers to a network whose only route is a filtering forward proxy (or pasta/slirp4netns port rules): allowlist package/image/model registries, deny RFC1918, link-local, and 169.254.169.254. Enforced at the network layer, not in prompts.

6. Process secret hygiene

agent-server reads AGENT_SERVER_TOKEN / LITELLM_API_KEY at boot into config and then deletes them from process.env. Defense in depth: even a hypothetical tool escape finds nothing to inherit.

7. Regression tests

Drive real prompts/tool calls through agent-server and assert:

• env | grep -E '(AGENT_SERVER_TOKEN|LITELLM_API_KEY)' → empty;
• read/write/edit with absolute, ../, and symlinked paths into a sibling workspace → blocked;
• find /workspace -maxdepth 2 from bash → only the own project;
• podman ps -a from bash → command unavailable or scoped to own project;
• curl http://169.254.169.254/ and RFC1918 targets → refused; npm ping → succeeds.

Summary

Threat	Boundary
File tools escaping project root	realpath-confined operations in the isolation extension
Bash reading process secrets	env allowlist + secrets scrubbed from process.env at boot
Bash reaching sibling workspaces	container mount namespace (only own workspace mounted)
Podman cross-tenant access	no socket in builder container / label-scoped socket proxy
Private-network / metadata egress	container network policy with registry allowlist

The extension is the routing layer; the actual boundaries are the container mount/network namespaces and the scoped socket — consistent with Pi's own guidance that in-process checks are not a sandbox.

[alexanderkreidich]

Runtime flow of the isolation boundaries

Companion sequence diagram for the proposal above — what actually happens when a malicious prompt tries the three escape classes from the issue:

1. Path escape — write ../other/.env reaches the isolation extension's overridden file tool; the operation canonicalizes the path with realpath and refuses it before any I/O (symlink/TOCTOU safe, since the check runs inside the operation at execution time).
2. Secret hunt — bash: env | grep TOKEN is routed via podman exec into the project's builder container with an explicit env allowlist; the output is empty because AGENT_SERVER_TOKEN / LITELLM_API_KEY never enter the container (and are scrubbed from process.env at boot).
3. Metadata egress — curl 169.254.169.254 runs inside the container, but all egress passes the filtering proxy, which denies private/link-local/metadata ranges while registry domains still resolve.

The Pi session only ever sees tool results (blocked, empty output, connection refused) — the boundaries are the confined operations, the container mount/env namespaces, and the network policy, not the model's cooperation.