How jeffreyzhou-harvard/crucible_agentenvironment works
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: routes.py HTTP and WS API · orchestrator.py Lifecycle orchestrator · useTrace.ts Trace stream hook · runner.py Experiment runner
Components 24
User experience
- Landing page
frontend/src/pages/Landing.tsx - Workspace console
frontend/src/pages/Console.tsx - Workspace view
frontend/src/components/WorkspaceView.tsx - Experiment dashboard
frontend/src/components/experiment/ExperimentDashboard.tsx - API client
frontend/src/lib/api.ts - Trace stream hook
frontend/src/hooks/useTrace.ts
Workspace lifecycle
- HTTP and WS API
src/agent_workspaces/api/routes.py - Lifecycle orchestrator
src/agent_workspaces/orchestrator.py - Scheduler and pool
src/agent_workspaces/control - Intent warming
src/agent_workspaces/control/intent.py - Agent execution
src/agent_workspaces/execution/agent.py - Sandbox runtime
src/agent_workspaces/execution/runtime.py
Safety and data
- Data branching
src/agent_workspaces/data/branching.py - Dataset provisioner
src/agent_workspaces/data/provisioner.py - Security plane
src/agent_workspaces/security - Egress proxy
src/agent_workspaces/security/proxy_server.py - Egress audit
src/agent_workspaces/security/audit.py
Experiments
- Experiment runner
src/agent_workspaces/experiment/runner.py - Task definitions
src/agent_workspaces/experiment/tasks.py - Held-out grader
src/agent_workspaces/experiment/grader.py
Trace and audit
- Trace recorder
src/agent_workspaces/trace/recorder.py - Trace event bus
src/agent_workspaces/trace/bus.py
Other components
- User
- Model provider
Connections 29
- 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