Skip to content

GhostScience Configuration ​

This page documents the environment variables and admin settings for GhostScience (PhD Mode), Federated Clean Rooms, and the PhD sandbox.

Enabling GhostScience ​

Set these environment variables in your .env file or deployment configuration:

bash
PHD_MODE_ENABLED=true
SANDBOX_ENABLED=true

Both must be true for GhostScience tools to appear in chat and for the /api/phd endpoints to accept requests. When PHD_MODE_ENABLED is false, the API returns 403.

PhD Mode Settings ​

VariableTypeDefaultDescription
PHD_MODE_ENABLEDboolfalseMaster toggle for all GhostScience features
PHD_SANDBOX_IMAGEstringghostai-phd-sandbox:latestDocker image for CPU PhD sandbox
PHD_SANDBOX_GPU_IMAGEstringghostai-phd-sandbox-gpu:latestDocker image for GPU PhD sandbox (CUDA 12.2 + JAX)
PHD_SANDBOX_TIMEOUTint300Maximum execution time per computation (seconds)
PHD_SANDBOX_MEMORY_LIMITstring4gDocker memory limit per container
PHD_SANDBOX_CPU_LIMITfloat2.0CPU cores per container
PHD_PARALLEL_MAXint4Maximum concurrent PhD executions
PHD_GPL_FREEboolfalseWhen true, excludes GPL-licensed libraries (Slycot, Octave, FEniCSx) from the sandbox; see LICENSE_AUDIT.md in the sandbox image source
PHD_MAX_SESSIONS_PER_USERint3Max persistent PhD sessions per user
PHD_MAX_SESSIONS_PER_ORGint20Max persistent PhD sessions per organization
PHD_SESSION_TTL_HOURSint24Persistent session expiry

Clean Room Settings ​

VariableTypeDefaultDescription
CLEAN_ROOM_ENABLEDboolfalseMaster toggle for federated clean rooms
CLEAN_ROOM_MAX_PARTICIPANTSint10Maximum organizations per clean room
CLEAN_ROOM_RESULT_TTL_HOURSint168Escrowed result expiry (7 days)
CLEAN_ROOM_REQUIRE_ATTESTATIONbooltrueRequire all orgs to attest before execution

Clean Room also requires PHD_MODE_ENABLED=true and SANDBOX_ENABLED=true.

GPU Batch Settings ​

For offloading computations to AWS Batch or Lambda with GPU:

VariableTypeDefaultDescription
GPU_BATCH_FUNCTION_NAMEstring""AWS Batch/Lambda function name (optional)
GPU_BATCH_REGIONstringus-east-1AWS region for GPU jobs
GPU_BATCH_JOB_QUEUEstring""AWS Batch job queue name

General Sandbox Settings ​

These apply to both the standard code interpreter and PhD sandbox:

VariableTypeDefaultDescription
SANDBOX_ENABLEDbooltrueMaster toggle for all sandbox execution
SANDBOX_BACKENDstringdockerdocker or lambda
SANDBOX_RUNTIMEstring""OCI runtime override; set to runsc for gVisor
SANDBOX_IMAGEstringghostai-sandbox:latestStandard code interpreter image
SANDBOX_TIMEOUTint120Standard sandbox timeout (seconds)
SANDBOX_CPU_LIMITfloat2.0CPU cores
SANDBOX_MEMORY_LIMITstring4gMemory limit
SANDBOX_NETWORKstringnoneDocker network mode
SANDBOX_MAX_OUTPUTint1000000Max stdout characters
SANDBOX_MAX_CONCURRENTint5Max parallel standard executions
SANDBOX_RATE_LIMITint20Executions per user per window
SANDBOX_RATE_WINDOWint60Rate limit window (seconds)
SANDBOX_ROLLOUT_PERCENTint100Gradual rollout percentage (0-100)
DOCKER_HOSTstring""Docker daemon URL (empty = local socket)

Example Configuration ​

Minimal (CPU only) ​

bash
PHD_MODE_ENABLED=true
SANDBOX_ENABLED=true
PHD_SANDBOX_IMAGE=ghostai-phd-sandbox:latest

Production (GPU + gVisor + Clean Room) ​

bash
PHD_MODE_ENABLED=true
SANDBOX_ENABLED=true
SANDBOX_RUNTIME=runsc
PHD_SANDBOX_IMAGE=ghostai-phd-sandbox:latest
PHD_SANDBOX_GPU_IMAGE=ghostai-phd-sandbox-gpu:latest
PHD_SANDBOX_TIMEOUT=600
PHD_SANDBOX_MEMORY_LIMIT=16g
PHD_SANDBOX_CPU_LIMIT=4.0
PHD_PARALLEL_MAX=8
CLEAN_ROOM_ENABLED=true
CLEAN_ROOM_MAX_PARTICIPANTS=10
CLEAN_ROOM_RESULT_TTL_HOURS=168

Audit Events ​

GhostScience operations are recorded in the audit log:

EventDescription
phd.computePhD tool execution
phd.reproduceComputation reproduction attempt
phd.exportComputation export
clean_room.createClean room created
clean_room.inviteOrganization invited
clean_room.acceptInvitation accepted
clean_room.template_setComputation template updated
clean_room.attestOrganization attestation submitted
clean_room.releaseResult release decision
workspace.createWorkspace created
workspace.cell.runWorkspace cell executed

SOC 2 Type II Certified | BAA Available | HIPAA-Ready