Skip to content

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 Flags

The service uses a pluggable backend architecture:

BackendWhen to useConfig value
DockerLocal dev, Docker Composedocker
LambdaAWS ECS Fargate, Kubernetes / Helmlambda

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) ​

ControlValue
Filesystemread_only=True
Temp spacetmpfs /tmp (256 MB, noexec)
WorkspaceBind-mounted, writable
User1000:1000 (non-root)
Networknone (no network access)
Process limitpids_limit=100
Privilegesno-new-privileges:true
Capabilitiescap_drop=["ALL"]
MemoryConfigurable (default 4 GB)
CPUConfigurable (default 2 cores)
TimeoutConfigurable (default 120 s)
SeccompDocker 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_interpreter feature (Team plan and above)
  • Rate limiting: 20 executions per user per 60-second window (configurable)
  • Gradual rollout: SANDBOX_ROLLOUT_PERCENT controls what percentage of eligible users see the feature

Configuration ​

VariableDefaultDescription
SANDBOX_ENABLEDtrueMaster toggle
SANDBOX_BACKENDdockerdocker or lambda
SANDBOX_RUNTIME(empty)OCI runtime; runsc for gVisor
SANDBOX_IMAGEghostai-sandbox:latestDocker image name
SANDBOX_TIMEOUT120Max execution seconds
SANDBOX_CPU_LIMIT2.0CPU cores (Docker)
SANDBOX_MEMORY_LIMIT4gRAM limit (Docker)
SANDBOX_NETWORKnoneDocker network mode
SANDBOX_MAX_OUTPUT1000000Max stdout characters
SANDBOX_MAX_CONCURRENT5Max parallel executions
SANDBOX_RATE_LIMIT20Executions per user per window
SANDBOX_RATE_WINDOW60Rate limit window (seconds)
SANDBOX_ROLLOUT_PERCENT100Gradual rollout percentage
DOCKER_HOST(empty)Docker daemon URL
SANDBOX_LAMBDA_FUNCTION(empty)Lambda function name/ARN
SANDBOX_LAMBDA_REGIONus-west-2AWS region
SANDBOX_S3_BUCKET(empty)S3 bucket for file transfer
SANDBOX_S3_PREFIXsandbox-exec/S3 key prefix

Deployment Matrix ​

EnvironmentBackendNotes
Local bare-metaldockerRequires Docker Desktop; setup wizard builds image
Docker ComposedockerSocket mounted read-only
AWS ECS FargatelambdaLambda + S3; Terraform module provided
Kubernetes/HelmlambdaLambda ARN in Helm values
On-prem (hardened)docker + runscgVisor 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" ​

  1. Check SANDBOX_ENABLED=true in .env
  2. For Docker backend: verify Docker is running and DOCKER_HOST is set correctly (macOS Docker Desktop: unix:///Users/<you>/.docker/run/docker.sock)
  3. Verify the image exists: docker images ghostai-sandbox
  4. For Lambda backend: verify SANDBOX_LAMBDA_FUNCTION and SANDBOX_S3_BUCKET are 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_interpreter feature
  • 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.

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