Every agent has a sandbox — the agent reaches for it on its own when the work calls for it. It’s created fresh for the run and discarded afterwards. The three Sandbox tools appear in the agent’s tool list as always on and can’t be switched off, because every agent gets a sandbox regardless. To steer an agent toward or away from using it, use custom instructions.
What It Does
Because the sandbox is on every agent whether you enable it or not, it never sets an agent’s per-run price — see Tool credits. On the Neo Support Agent the sandbox is free entirely.
Sandbox Write File writes the exact content the agent supplies. For a Python script it can also confirm the file compiles as it writes, so a broken script is caught at write time instead of failing later in the run.
Typical uses:
- Loop one API call across hundreds of records in a single script instead of hundreds of agent turns
- Parse or reshape a CSV/JSON export the agent fetched from another tool
- Run a one-off calculation or text transformation
- Produce a file — a CSV, a chart, a PDF — for someone to download off the run
How Long One Command Can Run
A single sandbox command runs for up to 30 minutes on a scheduled or triggered agent. In a Chat Agent it is capped at 5 minutes, because the whole reply has one budget and someone is waiting for it — a Chat Agent asked for something big splits the work into steps, saves each step’s results as it goes, and carries on across the following commands rather than going quiet for half an hour. You may see that split in the chat: the agent fetches a first batch, tells you what it has, and continues. That is the intended shape. If a job genuinely needs one long uninterrupted run — a full-history export, a fleet-wide sweep — run it as a scheduled agent instead, where the longer budget applies.Files The Agent Leaves Behind Become Downloads
When the run ends, the files the agent left in itsworkspace/ directory are saved and attached to that run as artifacts, downloadable from the run’s page in the dashboard (and via the public API). Files the agent tucked into a hidden directory are skipped, as are the oversized tool outputs described below.
Saving is per file when the workspace holds fewer than 100 files. A workspace holding 100 files or more is normally saved as a single workspace.tar.gz download instead, because saving that many one at a time runs past the time Neo gives this step. The archive holds every file, but you unpack it on your own machine and the run’s download list shows one entry rather than a browsable list. An agent writing one file per record is the shape that produces an archive, and one file per batch is the shape that keeps individual downloads — worth saying in the agent’s custom instructions if you ask for a bulk export.
If the archive cannot be built, or comes out over 50 MB, Neo falls back to saving file by file and can then run out of time or reach its 200 MB total. It keeps what it saved and leaves the rest behind, with nothing in the chat to mark the gap. So after a bulk export, check the run’s download list against what you asked for. A single file over 50 MB is always skipped, archive or not.
This is worth knowing for two reasons:
- It’s how the agent hands you a file. A CSV, spreadsheet, chart, or PDF the agent builds is a real deliverable you can open — it isn’t stuck inside the run.
- It’s a separate path from Generate Artifact. That tool writes a markdown report that renders inline on the run. The sandbox produces actual files you download. Turning Generate Artifact off stops the written reports; it doesn’t stop an agent that has been instructed to build a file from building one in the sandbox. If you don’t want an agent producing files, say so in its custom instructions.
Oversized Tool Outputs Land Here
When any integration tool (PSA, RMM, Microsoft 365, documentation, …) returns a response too large for the agent to read in one go, Neo automatically saves the complete response to a file in the sandbox and shows the agent a map of it plus the file path. The map lists the parts of the response: the records in a list and the sections of a document, with their sizes, or the headings of a page, with where each one starts. The agent then reads only the parts it needs, so a big data pull never derails the run or forces the agent to re-fetch with narrower queries. Reading a part costs nothing in the common case. Sandbox Read File is free, and it can return one value of a JSON response, find text anywhere in the file, or return a range of characters. This works even when the response was saved on a single line, as most API responses are. When a part sits inside an item of a list, and that item has anid field of up to 64 characters, the read names that id, so the agent updates the right record. The agent uses the shell only when it has to filter or total the data.