Code execution

⚠️

Preview — this feature is being built; the design below is the spec.

With the built-in syntic_code_execution tool, the model can write and run code in an isolated container that Syntic hosts. It can analyse spreadsheets, compute statistics, transform files, draw charts and check its own work, then return the answer along with any files it produced. Your systems are never touched.

When to use it

Data analysis on uploaded CSV or Excel files.
Accurate maths, statistics and date calculations.
Producing charts, cleaned data files or converted documents.
Running agent skills that ship scripts.

Endpoint and auth

POST https://app.syntic.ai/v1/chat/completions (and Messages), Authorization: Bearer sk_live_....

Tool definition

Field	Type	Required	Details
`type`	string	Yes	`"syntic_code_execution"`
`container`	string or object	No	`"auto"` (default) creates a fresh container. `{"id": "cntr_..."}` reuses one from an earlier request so files and installed packages carry over.
`files`	array of strings	No	File ids (`purpose: "code_input"`) copied into `/mnt/input/` before the model starts.
`max_runs`	integer	No	Code runs allowed in this request, 1 to 50. Default 20.

The container

Property	Value
Languages	Python 3.12 and Bash; common data libraries pre-installed (pandas, numpy, matplotlib, openpyxl, pypdf)
CPU and memory	2 vCPU, 4 GB RAM
Disk	5 GB
Network	Off by default. No inbound access. Package installs come from a Syntic mirror.
Run timeout	120 seconds per run
Lifetime	Idle containers are removed after 30 minutes; any container after 24 hours
Output folder	Files written to `/mnt/output/` become Files you can download

Response

{
  "message": {
    "role": "assistant",
    "content": "Average order value rose 8.4% in Q3. The chart is attached.",
    "server_tool_calls": [
      { "id": "srv_03", "type": "syntic_code_execution", "status": "ok", "exit_code": 0, "duration_ms": 2140 }
    ],
    "files": [
      { "id": "file_01JBXK2", "filename": "aov_by_month.png", "bytes": 48211, "source": "code_execution" }
    ]
  },
  "container": { "id": "cntr_01JBXK0", "expires_at": 1791822600 },
  "usage": {
    "prompt_tokens": 3920, "completion_tokens": 410, "total_tokens": 4330,
    "server_tool_use": { "code_execution_seconds": 6 }
  }
}

Field	Description
`message.server_tool_calls[]`	One entry per run with `status`, `exit_code`, `duration_ms`. Pass `include: ["code_execution.code"]` in the request to also get the code and its output.
`message.files[]`	Files written to `/mnt/output/`. Download with `GET /v1/files/{id}/content`.
`container.id`	Send it back to keep working in the same container.

Streaming

Each run sends server_tool_call deltas with status: "running" and then the result, the same as web search.

Examples

curl https://app.syntic.ai/v1/chat/completions \
  -H "Authorization: Bearer $SYNTIC_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "Amara S1.2",
    "stream": false,
    "tools": [{ "type": "syntic_code_execution", "files": ["file_01JBXJZ"] }],
    "messages": [{ "role": "user", "content": "orders.csv is in /mnt/input. Plot average order value by month and tell me the Q3 trend." }]
  }'

const H = { Authorization: `Bearer ${process.env.SYNTIC_API_KEY}`, 'Content-Type': 'application/json' }
const data = await (await fetch('https://app.syntic.ai/v1/chat/completions', {
  method: 'POST',
  headers: H,
  body: JSON.stringify({
    model: 'Amara S1.2',
    stream: false,
    tools: [{ type: 'syntic_code_execution', files: [fileId] }],
    messages,
  }),
})).json()
 
for (const f of data.choices[0].message.files ?? []) {
  const bytes = await (await fetch(`https://app.syntic.ai/v1/files/${f.id}/content`, { headers: H })).arrayBuffer()
  await fs.writeFile(f.filename, Buffer.from(bytes))
}
const containerId = data.container.id // reuse in the next request

import os, requests
 
h = {"Authorization": f"Bearer {os.environ['SYNTIC_API_KEY']}"}
data = requests.post(
    "https://app.syntic.ai/v1/chat/completions",
    headers=h,
    json={
        "model": "Amara S1.2",
        "stream": False,
        "tools": [{"type": "syntic_code_execution", "container": {"id": container_id}}],
        "messages": messages,
    },
    timeout=600,
).json()
 
for f in data["choices"][0]["message"].get("files", []):
    content = requests.get(f"https://app.syntic.ai/v1/files/{f['id']}/content", headers=h).content
    open(f["filename"], "wb").write(content)

Errors

Unified envelope. Code that crashes is not an API error: the model sees the error output and usually fixes its code.

Status	`code`	Cause
400	`server_tool_not_supported`	The model cannot use code execution.
404	`container_not_found`	Unknown, expired or another workspace’s container.
404	`file_not_found`	An id in `files` does not exist.
403	`tool_disabled`	Turned off for your organisation.
429	`container_limit_reached`	Too many live containers for your tier (default 20).
503	`overloaded`	No container capacity right now. Retry after `Retry-After`.

Pricing


Container time	$0.05 per container-hour, billed per second while code runs, minimum 5 seconds per request
Tokens	Code the model writes and output it reads are normal tokens
Free allowance	50 container-hours per month per organisation

Security

Each container belongs to one workspace and is never reused across organisations.
No network unless your organisation enables an egress allowlist in the Console.
Files in a container are deleted with it; files in /mnt/output/ follow Files retention.

Build notes for the platform team

Reuse the App Builder sandbox fleet (ab-sandbox) with a separate pool and strict egress rules.
Containers are addressed by cntr_ ids mapped to sandboxes; never expose sandbox hostnames.
Billing line code_execution per second.

Web fetch Computer and browser use

Was this page helpful?