# jeffreyzhou-harvard/crucible_agentenvironment architecture

> Architecture diagram of the GitHub repository jeffreyzhou-harvard/crucible_agentenvironment, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-26). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/jeffreyzhou-harvard/crucible_agentenvironment
- Repository: https://github.com/jeffreyzhou-harvard/crucible_agentenvironment

## Overview

Crucible provides disposable, isolated workspaces for agent code and Best-of-N experiments that compare visible and held-out scores. Users launch runs from the web console or API; the orchestrator coordinates sandbox acquisition, data branching, security setup, execution, trace recording, and cleanup. Separate branches expose warm-pool and intent controls, experiment evaluation, and trace replay. The README documents these capabilities; sampled excerpts confirm the API, composition root, lifecycle, proxy, and runtime, while some internal wiring is represented only at the subsystem level.

Main entry points: [`src/agent_workspaces/api/routes.py`](https://github.com/jeffreyzhou-harvard/crucible_agentenvironment/blob/main/src/agent_workspaces/api/routes.py) (HTTP and WS API), [`src/agent_workspaces/orchestrator.py`](https://github.com/jeffreyzhou-harvard/crucible_agentenvironment/blob/main/src/agent_workspaces/orchestrator.py) (Lifecycle orchestrator), [`frontend/src/hooks/useTrace.ts`](https://github.com/jeffreyzhou-harvard/crucible_agentenvironment/blob/main/frontend/src/hooks/useTrace.ts) (Trace stream hook), [`src/agent_workspaces/experiment/runner.py`](https://github.com/jeffreyzhou-harvard/crucible_agentenvironment/blob/main/src/agent_workspaces/experiment/runner.py) (Experiment runner)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_product["User experience"]
  node_landing["Landing page<br/>[Landing.tsx]"]
  node_console["Workspace console<br/>[Console.tsx]"]
  node_workspace_view["Workspace view<br/>[WorkspaceView.tsx]"]
  node_experiment_dashboard["Experiment dashboard"]
  node_frontend_api["API client<br/>[api.ts]"]
  node_trace_hook["Trace stream hook<br/>[useTrace.ts]"]
end

subgraph group_lifecycle["Workspace lifecycle"]
  node_api["HTTP and WS API<br/>[routes.py]"]
  node_orchestrator["Lifecycle orchestrator<br/>[orchestrator.py]"]
  node_control["Scheduler and pool"]
  node_intent["Intent warming<br/>[intent.py]"]
  node_execution["Agent execution<br/>[agent.py]"]
  node_runtime["Sandbox runtime<br/>[runtime.py]"]
end

subgraph group_safety["Safety and data"]
  node_data["Data branching<br/>[branching.py]"]
  node_provisioner["Dataset provisioner<br/>[provisioner.py]"]
  node_security["Security plane"]
  node_proxy["Egress proxy<br/>[proxy_server.py]"]
  node_audit[("Egress audit<br/>[audit.py]")]
end

subgraph group_evaluation["Experiments"]
  node_experiment_api["Experiment runner<br/>[runner.py]"]
  node_tasks["Task definitions<br/>[tasks.py]"]
  node_grader["Held-out grader<br/>[grader.py]"]
end

subgraph group_observability["Trace and audit"]
  node_trace[("Trace recorder<br/>[recorder.py]")]
  node_trace_bus["Trace event bus<br/>[bus.py]"]
end

node_user(("User"))
node_agent_provider(("Model provider"))

node_user -->|"opens"| node_landing
node_user -->|"launches"| node_console
node_landing -->|"navigates"| node_console
node_console -->|"submits requests"| node_frontend_api
node_frontend_api -->|"calls"| node_api
node_api -->|"starts lifecycle"| node_orchestrator
node_api -->|"starts experiment"| node_experiment_api
node_console -.->|"signals intent"| node_api
node_api -->|"warms sandbox"| node_intent
node_orchestrator -->|"acquires sandbox"| node_control
node_orchestrator -->|"branches datasets"| node_data
node_data -->|"provisions data"| node_provisioner
node_orchestrator -->|"secures sandbox"| node_security
node_security -->|"configures egress"| node_proxy
node_proxy -->|"records decisions"| node_audit
node_orchestrator -->|"runs agent"| node_execution
node_execution -->|"executes commands"| node_runtime
node_execution -.->|"requests completions"| node_agent_provider
node_experiment_api -->|"loads task"| node_tasks
node_experiment_api -->|"scores candidates"| node_grader
node_experiment_api -->|"records run"| node_trace
node_orchestrator -->|"records lifecycle"| node_trace
node_trace -->|"publishes events"| node_trace_bus
node_frontend_api -->|"subscribes stream"| node_trace_hook
node_trace_hook -->|"opens WebSocket"| node_api
node_trace_hook -->|"supplies events"| node_workspace_view
node_trace_hook -->|"supplies events"| node_experiment_dashboard
node_api -->|"replays trace"| node_trace
node_api -->|"reads audit"| node_audit

click node_landing "https://github.com/jeffreyzhou-harvard/crucible_agentenvironment/blob/main/frontend/src/pages/Landing.tsx"
click node_console "https://github.com/jeffreyzhou-harvard/crucible_agentenvironment/blob/main/frontend/src/pages/Console.tsx"
click node_workspace_view "https://github.com/jeffreyzhou-harvard/crucible_agentenvironment/blob/main/frontend/src/components/WorkspaceView.tsx"
click node_experiment_dashboard "https://github.com/jeffreyzhou-harvard/crucible_agentenvironment/blob/main/frontend/src/components/experiment/ExperimentDashboard.tsx"
click node_frontend_api "https://github.com/jeffreyzhou-harvard/crucible_agentenvironment/blob/main/frontend/src/lib/api.ts"
click node_trace_hook "https://github.com/jeffreyzhou-harvard/crucible_agentenvironment/blob/main/frontend/src/hooks/useTrace.ts"
click node_api "https://github.com/jeffreyzhou-harvard/crucible_agentenvironment/blob/main/src/agent_workspaces/api/routes.py"
click node_orchestrator "https://github.com/jeffreyzhou-harvard/crucible_agentenvironment/blob/main/src/agent_workspaces/orchestrator.py"
click node_control "https://github.com/jeffreyzhou-harvard/crucible_agentenvironment/tree/main/src/agent_workspaces/control"
click node_intent "https://github.com/jeffreyzhou-harvard/crucible_agentenvironment/blob/main/src/agent_workspaces/control/intent.py"
click node_execution "https://github.com/jeffreyzhou-harvard/crucible_agentenvironment/blob/main/src/agent_workspaces/execution/agent.py"
click node_runtime "https://github.com/jeffreyzhou-harvard/crucible_agentenvironment/blob/main/src/agent_workspaces/execution/runtime.py"
click node_data "https://github.com/jeffreyzhou-harvard/crucible_agentenvironment/blob/main/src/agent_workspaces/data/branching.py"
click node_provisioner "https://github.com/jeffreyzhou-harvard/crucible_agentenvironment/blob/main/src/agent_workspaces/data/provisioner.py"
click node_security "https://github.com/jeffreyzhou-harvard/crucible_agentenvironment/tree/main/src/agent_workspaces/security"
click node_proxy "https://github.com/jeffreyzhou-harvard/crucible_agentenvironment/blob/main/src/agent_workspaces/security/proxy_server.py"
click node_audit "https://github.com/jeffreyzhou-harvard/crucible_agentenvironment/blob/main/src/agent_workspaces/security/audit.py"
click node_experiment_api "https://github.com/jeffreyzhou-harvard/crucible_agentenvironment/blob/main/src/agent_workspaces/experiment/runner.py"
click node_tasks "https://github.com/jeffreyzhou-harvard/crucible_agentenvironment/blob/main/src/agent_workspaces/experiment/tasks.py"
click node_grader "https://github.com/jeffreyzhou-harvard/crucible_agentenvironment/blob/main/src/agent_workspaces/experiment/grader.py"
click node_trace "https://github.com/jeffreyzhou-harvard/crucible_agentenvironment/blob/main/src/agent_workspaces/trace/recorder.py"
click node_trace_bus "https://github.com/jeffreyzhou-harvard/crucible_agentenvironment/blob/main/src/agent_workspaces/trace/bus.py"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_landing,node_console,node_workspace_view,node_experiment_dashboard,node_frontend_api,node_trace_hook,node_user toneBlue
class node_api,node_orchestrator,node_control,node_intent,node_execution,node_runtime toneAmber
class node_data,node_provisioner,node_security,node_proxy,node_audit toneMint
class node_experiment_api,node_tasks,node_grader toneRose
class node_trace,node_trace_bus,node_agent_provider toneIndigo
```

## Components

### User experience

- [Landing page](https://github.com/jeffreyzhou-harvard/crucible_agentenvironment/blob/main/frontend/src/pages/Landing.tsx): `frontend/src/pages/Landing.tsx`
- [Workspace console](https://github.com/jeffreyzhou-harvard/crucible_agentenvironment/blob/main/frontend/src/pages/Console.tsx): `frontend/src/pages/Console.tsx`
- [Workspace view](https://github.com/jeffreyzhou-harvard/crucible_agentenvironment/blob/main/frontend/src/components/WorkspaceView.tsx): `frontend/src/components/WorkspaceView.tsx`
- [Experiment dashboard](https://github.com/jeffreyzhou-harvard/crucible_agentenvironment/blob/main/frontend/src/components/experiment/ExperimentDashboard.tsx): `frontend/src/components/experiment/ExperimentDashboard.tsx`
- [API client](https://github.com/jeffreyzhou-harvard/crucible_agentenvironment/blob/main/frontend/src/lib/api.ts): `frontend/src/lib/api.ts`
- [Trace stream hook](https://github.com/jeffreyzhou-harvard/crucible_agentenvironment/blob/main/frontend/src/hooks/useTrace.ts): `frontend/src/hooks/useTrace.ts`

### Workspace lifecycle

- [HTTP and WS API](https://github.com/jeffreyzhou-harvard/crucible_agentenvironment/blob/main/src/agent_workspaces/api/routes.py): `src/agent_workspaces/api/routes.py`
- [Lifecycle orchestrator](https://github.com/jeffreyzhou-harvard/crucible_agentenvironment/blob/main/src/agent_workspaces/orchestrator.py): `src/agent_workspaces/orchestrator.py`
- [Scheduler and pool](https://github.com/jeffreyzhou-harvard/crucible_agentenvironment/tree/main/src/agent_workspaces/control): `src/agent_workspaces/control`
- [Intent warming](https://github.com/jeffreyzhou-harvard/crucible_agentenvironment/blob/main/src/agent_workspaces/control/intent.py): `src/agent_workspaces/control/intent.py`
- [Agent execution](https://github.com/jeffreyzhou-harvard/crucible_agentenvironment/blob/main/src/agent_workspaces/execution/agent.py): `src/agent_workspaces/execution/agent.py`
- [Sandbox runtime](https://github.com/jeffreyzhou-harvard/crucible_agentenvironment/blob/main/src/agent_workspaces/execution/runtime.py): `src/agent_workspaces/execution/runtime.py`

### Safety and data

- [Data branching](https://github.com/jeffreyzhou-harvard/crucible_agentenvironment/blob/main/src/agent_workspaces/data/branching.py): `src/agent_workspaces/data/branching.py`
- [Dataset provisioner](https://github.com/jeffreyzhou-harvard/crucible_agentenvironment/blob/main/src/agent_workspaces/data/provisioner.py): `src/agent_workspaces/data/provisioner.py`
- [Security plane](https://github.com/jeffreyzhou-harvard/crucible_agentenvironment/tree/main/src/agent_workspaces/security): `src/agent_workspaces/security`
- [Egress proxy](https://github.com/jeffreyzhou-harvard/crucible_agentenvironment/blob/main/src/agent_workspaces/security/proxy_server.py): `src/agent_workspaces/security/proxy_server.py`
- [Egress audit](https://github.com/jeffreyzhou-harvard/crucible_agentenvironment/blob/main/src/agent_workspaces/security/audit.py): `src/agent_workspaces/security/audit.py`

### Experiments

- [Experiment runner](https://github.com/jeffreyzhou-harvard/crucible_agentenvironment/blob/main/src/agent_workspaces/experiment/runner.py): `src/agent_workspaces/experiment/runner.py`
- [Task definitions](https://github.com/jeffreyzhou-harvard/crucible_agentenvironment/blob/main/src/agent_workspaces/experiment/tasks.py): `src/agent_workspaces/experiment/tasks.py`
- [Held-out grader](https://github.com/jeffreyzhou-harvard/crucible_agentenvironment/blob/main/src/agent_workspaces/experiment/grader.py): `src/agent_workspaces/experiment/grader.py`

### Trace and audit

- [Trace recorder](https://github.com/jeffreyzhou-harvard/crucible_agentenvironment/blob/main/src/agent_workspaces/trace/recorder.py): `src/agent_workspaces/trace/recorder.py`
- [Trace event bus](https://github.com/jeffreyzhou-harvard/crucible_agentenvironment/blob/main/src/agent_workspaces/trace/bus.py): `src/agent_workspaces/trace/bus.py`

### Other components

- **User**
- **Model provider**

## Connections

- User → Landing page: opens
- User → Workspace console: launches
- Landing page → Workspace console: navigates
- Workspace console → API client: submits requests
- API client → HTTP and WS API: calls
- HTTP and WS API → Lifecycle orchestrator: starts lifecycle
- HTTP and WS API → Experiment runner: starts experiment
- Workspace console → HTTP and WS API: signals intent
- HTTP and WS API → Intent warming: warms sandbox
- Lifecycle orchestrator → Scheduler and pool: acquires sandbox
- Lifecycle orchestrator → Data branching: branches datasets
- Data branching → Dataset provisioner: provisions data
- Lifecycle orchestrator → Security plane: secures sandbox
- Security plane → Egress proxy: configures egress
- Egress proxy → Egress audit: records decisions
- Lifecycle orchestrator → Agent execution: runs agent
- Agent execution → Sandbox runtime: executes commands
- Agent execution → Model provider: requests completions
- Experiment runner → Task definitions: loads task
- Experiment runner → Held-out grader: scores candidates
- Experiment runner → Trace recorder: records run
- Lifecycle orchestrator → Trace recorder: records lifecycle
- Trace recorder → Trace event bus: publishes events
- API client → Trace stream hook: subscribes stream
- Trace stream hook → HTTP and WS API: opens WebSocket
- Trace stream hook → Workspace view: supplies events
- Trace stream hook → Experiment dashboard: supplies events
- HTTP and WS API → Trace recorder: replays trace
- HTTP and WS API → Egress audit: reads audit