Skip to main content
A model that writes code needs somewhere to run it. Running it on your own server is a risk, because you did not write the code and cannot review every line. On InstaBox the code runs in a machine of its own, so a bad script cannot touch your server, and you delete the machine when you are done. This page builds the loop that a code interpreter or a data-analysis agent uses: your program takes code from a model, runs it in a machine, and returns the output, the errors, and the exit code to the model.
1

Install the SDK

Install the SDK for your language.
Then set an API key, which both SDKs read from INSTABOX_API_KEY. Create the key on API keys in the dashboard, and keep it on your server.
2

Create a machine

Create one machine for the conversation. The call returns when the machine is running, so the next step can use it at once.
3

Run the model's code

Write the code to a file in the machine and run it with a timeout, so that a script that never ends is stopped. Here code is the text that your model returned.
A script that prints hello returns hello in stdout with exit code 0. A script that raises an error returns the traceback in stderr with a non-zero exit code, and a script that runs past the timeout is stopped with exit code 124. In TypeScript a non-zero exit throws CommandExitError, which carries the same fields. In Python it is a normal result.
4

Send the result back to the model

Give the model the output and let it decide what to do next. When the code failed, the model reads the error and writes a fix, and your program runs the new code in the same machine. The loop stops after five attempts, so that a model that keeps writing failing code does not run without end.
yourModel.writeCode and yourModel.fixCode, and their Python forms, stand for your own calls to a model.
5

Delete the machine

Delete the machine when the conversation ends. Its files are deleted with it. Put the delete in your program’s cleanup path, such as a finally block, so that the machine is also deleted when a model call or an SDK call fails.

Keep one machine for a whole conversation

Files and installed packages stay on the machine between runs, so a later script can read a file that an earlier one wrote, and a package the model installed is still there. Keep the machine for as long as the conversation lasts and you do not pay to set it up again for each run. A machine that nobody uses pauses itself, and it wakes for the next command. This means an idle conversation costs no runtime, and the next message finds the machine as it was. See Auto-pause and max-run.

Keep your keys and private data out of the machine

Code that a model wrote can read anything in the machine, and the machine can reach the internet. So the code can also send out anything it can read, such as a repo or a data file that you copied in. Put only what the task needs into the machine. Do not put API keys there. When the code needs to call an API, save the key as an Org Secret. The machine then holds only a placeholder, and the outbound proxy adds the real key to requests for the hosts you allow. See Org Secrets.

Limits

  • A command is stopped after 60 seconds unless you set a timeout, and the longest timeout is 600 seconds. For longer work, run the command in the background. See Run commands.
  • Each of stdout and stderr is cut at 1 MiB, and truncated in the result says so. To get all of a long output, stream it. See Run commands.

Run commands

Timeouts, streaming, input, and background jobs.

Files

Write and read files, and copy folders in and out.

Snapshots

Start every machine with your packages already installed.

Coding agents

Run Claude Code, Codex, or OpenCode in a machine.