Appearance
Code Interpreter
The Code Interpreter gives GhostAI the ability to execute Python code generated by LLMs in a secure, isolated sandbox. Users can analyze uploaded CSVs, generate charts, run statistical models, and process data without leaving the chat.
Architecture
User ─► Chat Router ─► CodeSandboxService ─► Backend (Docker | Lambda)
│
├── PII Tokenization on output
├── Tool Validation on input
└── Rate Limiting / Feature FlagsThe service uses a pluggable backend architecture:
| Backend | When to use | Config value |
|---|---|---|
| Docker | Local dev, Docker Compose | docker |
| Lambda | AWS ECS Fargate, Kubernetes / Helm | lambda |
Security Model
Pre-execution (tool_validator.py)
Blocked before code reaches the sandbox:
eval(),exec(),compile(),importlib__import__(),__subclasses__(),getattr(__builtins__...)os.system(),os.popen(),subprocess
Runtime (entrypoint.py)
Inside the sandbox, Python's builtins are replaced with a restricted set:
- Blocked builtins:
eval,exec,compile,breakpoint,exit,quit,__import__ - Import allowlist: Only data science packages (pandas, numpy, matplotlib, scipy, sklearn, nltk, etc.) and a safe subset of the standard library are importable.
Container hardening (Docker backend)
| Control | Value |
|---|---|
| Filesystem | read_only=True |
| Temp space | tmpfs /tmp (256 MB, noexec) |
| Workspace | Bind-mounted, writable |
| User | 1000:1000 (non-root) |
| Network | none (no network access) |
| Process limit | pids_limit=100 |
| Privileges | no-new-privileges:true |
| Capabilities | cap_drop=["ALL"] |
| Memory | Configurable (default 4 GB) |
| CPU | Configurable (default 2 cores) |
| Timeout | Configurable (default 120 s) |
| Seccomp | Docker default profile (active) |
Kernel isolation (optional)
The Docker backend supports an optional OCI runtime override via SANDBOX_RUNTIME. Setting this to runsc enables gVisor, which interposes a userspace kernel between the sandboxed process and the host kernel. This near-eliminates container escape risk from kernel CVEs while adding minimal overhead for CPU-bound data science workloads.
See Container Security Architecture for the full trade-off analysis and setup instructions.
Lambda backend isolation
- /tmp cleanup: Previous execution data removed on every cold/warm start
- Minimal IAM: Only S3 read/write on the sandbox prefix + CloudWatch Logs
- No function URL: Invoked only from the backend service
- VPC isolation: Deployed in subnets with no NAT gateway (no outbound internet)
- S3 encryption: KMS server-side encryption, public access blocked
- Ephemeral data: 1-day lifecycle policy on the S3 bucket
Access Control
- Feature flag: Gated behind
code_interpreterfeature (Team plan and above) - Rate limiting: 20 executions per user per 60-second window (configurable)
- Gradual rollout:
SANDBOX_ROLLOUT_PERCENTcontrols what percentage of eligible users see the feature
Configuration
| Variable | Default | Description |
|---|---|---|
SANDBOX_ENABLED | true | Master toggle |
SANDBOX_BACKEND | docker | docker or lambda |
SANDBOX_RUNTIME | (empty) | OCI runtime; runsc for gVisor |
SANDBOX_IMAGE | ghostai-sandbox:latest | Docker image name |
SANDBOX_TIMEOUT | 120 | Max execution seconds |
SANDBOX_CPU_LIMIT | 2.0 | CPU cores (Docker) |
SANDBOX_MEMORY_LIMIT | 4g | RAM limit (Docker) |
SANDBOX_NETWORK | none | Docker network mode |
SANDBOX_MAX_OUTPUT | 1000000 | Max stdout characters |
SANDBOX_MAX_CONCURRENT | 5 | Max parallel executions |
SANDBOX_RATE_LIMIT | 20 | Executions per user per window |
SANDBOX_RATE_WINDOW | 60 | Rate limit window (seconds) |
SANDBOX_ROLLOUT_PERCENT | 100 | Gradual rollout percentage |
DOCKER_HOST | (empty) | Docker daemon URL |
SANDBOX_LAMBDA_FUNCTION | (empty) | Lambda function name/ARN |
SANDBOX_LAMBDA_REGION | us-west-2 | AWS region |
SANDBOX_S3_BUCKET | (empty) | S3 bucket for file transfer |
SANDBOX_S3_PREFIX | sandbox-exec/ | S3 key prefix |
Deployment Matrix
| Environment | Backend | Notes |
|---|---|---|
| Local bare-metal | docker | Requires Docker Desktop; setup wizard builds image |
| Docker Compose | docker | Socket mounted read-only |
| AWS ECS Fargate | lambda | Lambda + S3; Terraform module provided |
| Kubernetes/Helm | lambda | Lambda ARN in Helm values |
| On-prem (hardened) | docker + runsc | gVisor for kernel isolation; see security whitepaper |
Observability
- Prometheus metrics:
ghostai_code_execution_total{status},ghostai_code_execution_duration_seconds,ghostai_code_execution_errors_total{error_type} - CloudWatch alarms (Lambda): error rate, p99 duration, throttles
- Prometheus alerts: high error rate (>25%), high latency (p95 >60 s), timeout spikes
Troubleshooting
"Code interpreter is not available"
- Check
SANDBOX_ENABLED=truein.env - For Docker backend: verify Docker is running and
DOCKER_HOSTis set correctly (macOS Docker Desktop:unix:///Users/<you>/.docker/run/docker.sock) - Verify the image exists:
docker images ghostai-sandbox - For Lambda backend: verify
SANDBOX_LAMBDA_FUNCTIONandSANDBOX_S3_BUCKETare set and the Lambda function exists
"Code button missing from prompt box"
The code button is only shown when:
SANDBOX_ENABLED=true- The sandbox backend is reachable (Docker daemon or Lambda function)
- The user's plan includes the
code_interpreterfeature - The user is within the rollout percentage
Timeout errors
Increase SANDBOX_TIMEOUT or optimize the code to process data in chunks. For Lambda, ensure the Lambda timeout is set higher than SANDBOX_TIMEOUT.