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 A script that prints
code is the text that your model returned.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
stdoutandstderris cut at 1 MiB, andtruncatedin 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.