Sandbox & Code Execution — docs.gipity.ai

code_execute

Run JavaScript, Python, or Bash in a sandboxed Docker container. No network access.

File I/O Contract - "sandbox = your project"

/work/ mirrors your project files. Input paths are preserved: an input_files entry of data/foo.csv lands at /work/data/foo.csv.
Write files at any relative path under /work/ (or the cwd, which is /work/). Anything you create or modify is written back to the project at the same path.
If you write to a path that already exists, the project file is versioned (not overwritten destructively). Users and agents can roll back with file_version_restore, so it's safe to transform files in place.
Unchanged input files are NOT round-tripped (we compare sha256 before returning them). You only pay the VFS write when you actually changed a file.
Python users: os.makedirs('thumbnails', exist_ok=True) before writing to a new subdir. ffmpeg and most CLI tools auto-create parent dirs.
Max file size: 512 KB. No network. 30s default / 600s max timeout.
output_files is an optional assertion: list paths you expect to produce, and you'll get a warning if any are missing. It does not filter - all new/modified files are returned regardless.

Pre-installed Runtimes

Node.js 20 - full standard library
Python 3 - pandas, numpy, matplotlib, scipy, sympy, pillow, openpyxl, xlsxwriter, xlrd, python-docx, python-pptx, reportlab, cairosvg, seaborn, qrcode, python-barcode, requests, bs4, lxml, pyyaml, Jinja2, tabulate, csvkit (+ agate-dbf, agate-excel, agate-sql, dbfread), pyfiglet, pytesseract, python-dateutil, python-slugify, Pygments, faker, wordcloud, networkx, SQLAlchemy, Markdown, babel, fonttools
Perl 5.36 - full install
GCC/G++, mingw-w64 (cross-compile to Windows .exe via x86_64-w64-mingw32-gcc / -g++ / -windres)

CLI Tools (prefer one-liners over scripts)

FFmpeg - transcode, trim, extract frames/audio, generate thumbnails (ffmpeg, ffprobe, ffplay)
ImageMagick (convert/mogrify/identify/composite) - resize, crop, composite, format-convert
Graphviz (dot, neato, sfdp, fdp, twopi, circo) - diagrams from DOT
gnuplot - CLI plotting
sox - audio processing (convert, trim, mix, effects); play/rec also available
jq - JSON query/transform
sqlite3 - ad-hoc queries on .sqlite/.db
PDF toolkit - pdftotext, pdfimages, pdfinfo, pdfhtml, pdftoppm (PDF→PNG/PPM), pdftocairo (PDF→PNG/SVG), pdfunite (merge), pdfseparate (split), pdfattach/pdfdetach, pdfsig, pdffonts
ghostscript (gs), ps2pdf/pdf2ps/ps2epsi/eps2eps/dvipdf - PostScript ↔ PDF
qpdf - merge, split, encrypt, linearize PDFs
pandoc - convert markdown/HTML/docx/epub/rst/latex
LibreOffice (soffice --headless, lowriter, localc, loimpress, lodraw, loweb) - docx/xlsx/pptx → PDF or HTML
wkhtmltopdf / wkhtmltoimage - render HTML files to PDF or PNG
exiftool, mediainfo - read/write file metadata
potrace, mkbitmap - bitmap → SVG (mkbitmap preprocesses for potrace)
optipng, gifsicle - image optimization; gifdiff, gifview
WebP toolkit - cwebp (encode), dwebp (decode), gif2webp, img2webp, webpmux, webpinfo
diffimg - pixel-diff two images
xmlstarlet - query/edit XML
datamash, miller (mlr) - tabular stats and CSV/JSON transforms
tesseract - OCR (Python: pytesseract.image_to_string)
qrencode - generate QR code images
fc-list, fc-match - fontconfig: list/match fonts on the system
lp_solve - linear programming solver (LP/MIP)
openssl - hashes, x509, keygen, encrypt/decrypt
gpg (+ gpgsm) - sign, encrypt, verify
bc - arbitrary-precision calculator for bash
tree - recursive directory listing
p7zip (7z), unzip/zip (zipinfo, zipsplit, zipcloak), unrar
hunspell, figlet/toilet, dos2unix/unix2dos, sed/awk/mawk/perl

Discovering tools

If unsure whether a tool or package is available, probe before using it - the sandbox has no network, so a fast check is cheaper than a failed run:

CLI: command -v ffmpeg (exits 0 with path, 1 if missing)
Python: python3 -c "import foo; print(foo.__version__)" or pip show foo
Node: node -e "console.log(require.resolve('foo'))"

Worked Examples

1. FFmpeg - transcode MP4 → WebM

input_files: ["videos/clip.mp4"]
language: bash
code: ffmpeg -y -i videos/clip.mp4 -c:v libvpx-vp9 -b:v 1M -c:a libopus videos/clip.webm

Returns: project gains videos/clip.webm. The .mp4 is unchanged, so it is not re-written.

2. FFmpeg - extract 10 frames from a video

input_files: ["videos/clip.mp4"]
language: bash
code: |
  mkdir -p frames
  ffmpeg -y -i videos/clip.mp4 -vf "fps=10/$(ffprobe -v error -show_entries format=duration -of csv=p=0 videos/clip.mp4)" frames/frame_%03d.jpg

Returns: frames/frame_001.jpg … frames/frame_010.jpg.

3. ImageMagick - resize + convert format

input_files: ["images/photo.jpg"]
language: bash
code: |
  mkdir -p thumbnails
  convert images/photo.jpg -resize 400x400 -quality 85 thumbnails/photo.webp

Returns: thumbnails/photo.webp.

4. Python pandas - filter/aggregate a CSV

input_files: ["data/sales.csv"]
language: python
code: |
  import pandas as pd
  df = pd.read_csv('data/sales.csv')
  q4 = df[df['quarter'] == 'Q4'].groupby('region')['amount'].sum().reset_index()
  q4.to_csv('data/sales_q4.csv', index=False)
  print(q4.to_string(index=False))

Returns: data/sales_q4.csv plus a printed preview on stdout.

5. Python matplotlib - chart a JSON metric series → PNG

input_files: ["data/metrics.json"]
language: python
code: |
  import json, os
  import matplotlib
  matplotlib.use('Agg')
  import matplotlib.pyplot as plt
  d = json.load(open('data/metrics.json'))
  os.makedirs('charts', exist_ok=True)
  plt.plot(d['labels'], d['values'])
  plt.xticks(rotation=45); plt.tight_layout()
  plt.savefig('charts/metrics.png', dpi=120)

Returns: charts/metrics.png (inline in the reply).

6. Bash + poppler - PDF → plain text

input_files: ["docs/manual.pdf"]
language: bash
code: |
  mkdir -p docs
  pdftotext -layout docs/manual.pdf docs/manual.txt
  wc -l docs/manual.txt

Returns: docs/manual.txt plus the line count on stdout.

Audio/Music Generation - use dedicated tools

Do NOT use code_execute with sox/ffmpeg to generate music or sound effects. Use:

music_generate - AI-generated music
sound_generate - AI-generated sound effects
speech_generate - AI-generated voice narration

These produce higher-quality results and handle file saving automatically.