Sandbox de código Python para IA

Stateful Python code-interpreter sandboxes for AI agents

O Runbox dá a um agente de IA um interpretador Python isolado e com estado: o usuário anexa uma planilha, o modelo sobe o arquivo, roda pandas/matplotlib em turnos (as variáveis persistem entre execuções) e recebe gráficos e arquivos de volta como URLs públicas — nunca base64 no contexto do modelo.

Runbox gives an AI agent an isolated, stateful Python interpreter: upload the user's spreadsheet, run pandas/matplotlib across turns (variables persist between runs), and get charts/files back as public URLs — never base64 in the model context.

Base: https://runbox.api.insyde.one — autenticada / authenticated.  ·  Playground  ·  llms.txt (cole numa IA / paste into an AI)

1. Autenticação / Authentication

Token por tenant no formato tenant:hash, via header (ou ?key=):

Per-tenant token in tenant:hash form, via header (or ?key=):

Authorization: Bearer cnn:55abc47c…

2. O fluxo do agente / The agent flow

# 1. uma sessão por conversa (estado persiste entre turnos)
POST /sessions                          → { "sessionId": "mdl_sb-…", "expiresAt": "…" }

# 2. anexos do usuário entram no filesystem do sandbox
POST /sessions/{id}/files               → { "path": "/work/data.csv" }

# 3. cada turno roda código; df definido no turno 1 existe no turno 2
POST /sessions/{id}/run                 → stdout, result, error, displays, artifacts

# 4. fim da conversa (opcional — a sessão expira sozinha por idle)
DELETE /sessions/{id}

3. Criar sessão / Create a session

POST /sessions
{ "conversationId": "conv-123", "idleTtlSec": 120, "maxLifetimeSec": 3600 }

409 se o tenant exceder a quota de sessões simultâneas (padrão 5). / if the tenant exceeds the concurrent-session quota (default 5).

4. Subir arquivos / Upload files

# multipart
curl -X POST .../sessions/{id}/files -H "Authorization: Bearer …" -F "file=@dados.csv"

# ou por URL (o servidor baixa)
{ "url": "https://exemplo.com/dados.xlsx", "name": "dados.xlsx" }

Resposta { "path": "/work/dados.csv" } — use exatamente esse path no código. Máx 25MB. / Use this exact path in code. Max 25MB.

5. Executar código / Run code

POST /sessions/{id}/run
{ "code": "import pandas as pd\ndf = pd.read_csv('/work/dados.csv')\ndf.describe()",
  "timeoutMs": 30000 }

Resposta com semântica Jupyter / Response with Jupyter semantics:

{
  "ok": true,
  "stdout": "…",                  // print(), cap de 64KB (flag truncated)
  "result": "42",                 // repr da ÚLTIMA EXPRESSÃO (ou null)
  "error": null,                  // ou {ename, evalue, traceback[]} estruturado
  "displays": [                   // representações ricas (DataFrame → tabela HTML)
    { "mimeType": "text/html", "data": "<table>…" }
  ],
  "artifacts": [                  // capturados AUTOMATICAMENTE neste run
    { "name": "figure-1-1.png", "mimeType": "image/png",
      "url": "https://runbox.api.insyde.one/a/…", "sizeBytes": 9981 }
  ],
  "durationMs": 776
}

6. Ambiente do sandbox / Sandbox environment

• Python 3.12, 1 CPU, 2 GB RAM, workdir /work. Filesystem destruído com a sessão. / Filesystem destroyed with the session.
• Sem rede — requests.get() falha; não tente pip install. / No network — don't try to pip install.
• Zero segredos no ambiente. / Zero secrets in the environment.

Pacotes pré-instalados (nome pip → nome de import quando diferem): / Preinstalled packages (pip name → import name where they differ):

7. Galeria de exemplos / Example gallery

Tudo abaixo saiu do sandbox sem estilização manual — o padrão insyde.one é o default do matplotlib, e as malhas vêm da imagem. / Everything below came straight from the sandbox with no manual styling — the insyde.one look is the matplotlib default and the boundaries ship in the image.

O coroplético de SP, ponta a ponta: / The SP choropleth, end to end:

import geopandas as gpd
g = gpd.read_parquet("/opt/runbox/data/geo/br_municipios.parquet")
sp = g[g.abbrev_state == "SP"].copy()
sp["idh"] = meus_dados            # join your column here
ax = sp.plot(column="idh", scheme="quantiles", k=5, legend=True,
             edgecolor="white", linewidth=0.15)
ax.set_axis_off()                  # figura capturada automaticamente / auto-captured

8. Altair / Vega-Lite (estilo D3) & hemiciclo

Para o visual declarativo e polido do tipo D3, o sandbox traz Altair (gramática Vega-Lite). Ele renderiza offline via vl-convert (motor em Rust, sem navegador) — então chart.save("outputs/x.png") ou .svg funciona normalmente. Aplique o tema da marca com uma linha: import insyde_theme. / Altair (Vega-Lite) gives the polished, D3-style declarative look, rendered offline via vl-convert. One line for the brand theme: import insyde_theme.

Um gráfico Altair, ponta a ponta (tema da marca + render offline): / An Altair chart, end to end:

import insyde_theme, altair as alt, pandas as pd
df = pd.read_csv("/work/vendas.csv")         # seu DataFrame / your own data
chart = (alt.Chart(df, title="Receita por praça")
         .mark_bar()
         .encode(x="praca:N", y=alt.Y("valor:Q", title="R$ mi"))
         .properties(width=360, height=240))
chart.save("outputs/receita.png", scale_factor=2)  # ou .svg (vetor) — vira artifact

Hemiciclo / Parliament

Duas vias: parliamentarch (gera o SVG das cadeiras → rasterize com cairosvg.svg2png), ou ~25 linhas de matplotlib (arcos concêntricos de pontos — já sai no padrão da marca, em PNG). / Either parliamentarch (seat SVG + cairosvg) or a small matplotlib version.

9. Demais endpoints / Other endpoints

10. Códigos de erro / Error codes

11. Virando tool de IA / Wiring it as an AI tool

Três funções bastam: runbox_create_session, runbox_upload_url e runbox_run — cada uma é um fetch com o Bearer token. Os schemas completos (OpenAI tools + Anthropic input_schema), prontos para copiar, estão no runbox-llms.txt — feito para colar inteiro no contexto de outra IA.

Three functions are enough — each is one fetch with the Bearer token. The full copy-paste schemas (OpenAI tools + Anthropic input_schema) live in runbox-llms.txt, written to be pasted whole into another AI's context.

// executor mínimo / minimal executor
const BASE = 'https://runbox.api.insyde.one';
const H = { Authorization: `Bearer ${TOKEN}`, 'Content-Type': 'application/json' };

async function runboxRun(sessionId, code) {
  const r = await fetch(`${BASE}/sessions/${sessionId}/run`,
    { method: 'POST', headers: H, body: JSON.stringify({ code }) });
  return r.json();  // devolva stdout/result/error ao modelo; URLs vão pro chat
}

Playground · llms.txt · Back to Insyde APIs