Condor Sandbox & Builder — Docker Workspace + Low-Code Agentic Definitions

Condor Sandbox & Builder — Docker Workspace + Low-Code Agentic Definitions

Two subsystems of the Condor engine: the Sandbox (a Docker-backed workspace/computer the agent can operate — filesystem + terminal + exec) and the Builder (a low-code CRUD surface for the agentic definitions the engine composes: agents, tools, workflows, processors, predicate/tool kernels, context schemas, memory).

Sandbox subsystem — sandbox/

SandboxModule (condor-parity 21, security-reviewed 2026-06-09) gives the Condor agent a real, isolated compute environment.

Wiring

• SandboxRegistryModule (driver/) provides the Postgres-backed slot registry, a tarn pool, and the shared DockerSandbox driver (dockerode).
• SandboxService is the orchestration brain (ownership + exec + restart).
• Three controllers expose the HTTP surface under @Controller('ai/condor/sandbox/sessions/:id'):
  • SandboxController — status / exec / restart
  • SandboxFsController — workspace filesystem reads
  • SandboxPtyController — NDJSON terminal stream (manual @Res, NOT @Sse/WS)

Security model (hardened)

• The ONLY APP_GUARD is the global GatewayAuthGuard (validates X-API-Key + builds req.user from X-Gateway-* — AuthN). On top, all three controllers add an explicit ROLE gate (@UseGuards(RolesGuard) + @Roles(DOCTOR, NURSE, CLINIC_ADMIN, ORG_ADMIN, SUPER_ADMIN)) — a PATIENT/non-clinical principal is 403'd.
• Ownership is enforced per-session inside SandboxService (unconditional, no service bypass).
• Container isolation is the ultimate boundary for exec: read-only rootfs, cap-drop ALL, no-new-privileges, Internal: true (no network egress), resource limits.
• Deps: AiModule exports PrismaAiService (ddx_api_ai — SandboxSlot / SandboxEvent models). The stream-hub uses a dedicated redis pub/sub client (sandbox:exec:* channel).

The layers are sequential gates, not alternatives — a request must clear all four before a command reaches the container, and slot acquisition is de-duplicated per session so concurrent callers share one recovery:

Inode-safe writes (known trap)

Filesystem tools must write in-place (flag: 'w'), never tmp+rename — a rename swaps the inode and detaches the macOS Docker bind mount, losing the mounted sandbox folder. (See the fs-patch / fs-find-replace inode-safe-write helper.)

Builder subsystem — builder/

The low-code CRUD surface for Condor agentic definitions, exposed under @Controller('admin/builder/*') (admin-scoped):

BuilderService + builder-crud.base.ts provide the shared CRUD base (BuilderCrudControllerBase, gated by BUILDER_ADMIN_ROLES).

Writer / reader split — the version machine

BuilderModule is the writer half (version machine + CRUD); MastraRegistryModule is the reader half. They are siblings by design, not a dependency (mastra-registry.module.ts:1-25). Definitions do not become live by being saved — only a PUBLISHED version is hydrated, and the run path pulls it rather than the registry pushing into a Mastra singleton:

A $transaction wraps publish/archive — a partial publish would corrupt the version machine. The compiler consumes the already-hydrated def; there is no setEditor() integration with a Mastra singleton, because Mastra's Editor namespaces do not cover this six-kind registry.

Related Topics

• Condor Engine — the runtime that consumes these definitions and drives the sandbox.
• Agent Templates — the configurable agent-factory concept the builder generalizes for Condor.