Appearance
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=trueBoth 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
| Variable | Type | Default | Description |
|---|---|---|---|
PHD_MODE_ENABLED | bool | false | Master toggle for all GhostScience features |
PHD_SANDBOX_IMAGE | string | ghostai-phd-sandbox:latest | Docker image for CPU PhD sandbox |
PHD_SANDBOX_GPU_IMAGE | string | ghostai-phd-sandbox-gpu:latest | Docker image for GPU PhD sandbox (CUDA 12.2 + JAX) |
PHD_SANDBOX_TIMEOUT | int | 300 | Maximum execution time per computation (seconds) |
PHD_SANDBOX_MEMORY_LIMIT | string | 4g | Docker memory limit per container |
PHD_SANDBOX_CPU_LIMIT | float | 2.0 | CPU cores per container |
PHD_PARALLEL_MAX | int | 4 | Maximum concurrent PhD executions |
PHD_GPL_FREE | bool | false | When true, excludes GPL-licensed libraries (Slycot, Octave, FEniCSx) from the sandbox; see LICENSE_AUDIT.md in the sandbox image source |
PHD_MAX_SESSIONS_PER_USER | int | 3 | Max persistent PhD sessions per user |
PHD_MAX_SESSIONS_PER_ORG | int | 20 | Max persistent PhD sessions per organization |
PHD_SESSION_TTL_HOURS | int | 24 | Persistent session expiry |
Clean Room Settings
| Variable | Type | Default | Description |
|---|---|---|---|
CLEAN_ROOM_ENABLED | bool | false | Master toggle for federated clean rooms |
CLEAN_ROOM_MAX_PARTICIPANTS | int | 10 | Maximum organizations per clean room |
CLEAN_ROOM_RESULT_TTL_HOURS | int | 168 | Escrowed result expiry (7 days) |
CLEAN_ROOM_REQUIRE_ATTESTATION | bool | true | Require 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:
| Variable | Type | Default | Description |
|---|---|---|---|
GPU_BATCH_FUNCTION_NAME | string | "" | AWS Batch/Lambda function name (optional) |
GPU_BATCH_REGION | string | us-east-1 | AWS region for GPU jobs |
GPU_BATCH_JOB_QUEUE | string | "" | AWS Batch job queue name |
General Sandbox Settings
These apply to both the standard code interpreter and PhD sandbox:
| Variable | Type | Default | Description |
|---|---|---|---|
SANDBOX_ENABLED | bool | true | Master toggle for all sandbox execution |
SANDBOX_BACKEND | string | docker | docker or lambda |
SANDBOX_RUNTIME | string | "" | OCI runtime override; set to runsc for gVisor |
SANDBOX_IMAGE | string | ghostai-sandbox:latest | Standard code interpreter image |
SANDBOX_TIMEOUT | int | 120 | Standard sandbox timeout (seconds) |
SANDBOX_CPU_LIMIT | float | 2.0 | CPU cores |
SANDBOX_MEMORY_LIMIT | string | 4g | Memory limit |
SANDBOX_NETWORK | string | none | Docker network mode |
SANDBOX_MAX_OUTPUT | int | 1000000 | Max stdout characters |
SANDBOX_MAX_CONCURRENT | int | 5 | Max parallel standard executions |
SANDBOX_RATE_LIMIT | int | 20 | Executions per user per window |
SANDBOX_RATE_WINDOW | int | 60 | Rate limit window (seconds) |
SANDBOX_ROLLOUT_PERCENT | int | 100 | Gradual rollout percentage (0-100) |
DOCKER_HOST | string | "" | 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:latestProduction (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=168Audit Events
GhostScience operations are recorded in the audit log:
| Event | Description |
|---|---|
phd.compute | PhD tool execution |
phd.reproduce | Computation reproduction attempt |
phd.export | Computation export |
clean_room.create | Clean room created |
clean_room.invite | Organization invited |
clean_room.accept | Invitation accepted |
clean_room.template_set | Computation template updated |
clean_room.attest | Organization attestation submitted |
clean_room.release | Result release decision |
workspace.create | Workspace created |
workspace.cell.run | Workspace cell executed |
Related
- GhostScience -- feature overview
- PhD Sandbox Deployment -- Docker image build and setup
- Code Interpreter -- standard sandbox configuration