Computers through the API¶

The concept behind tools is explained in Tools.

Give a turn its own computer: an isolated machine on which the model runs commands and reads and writes files. The model can write a script, run it, read the output and try again — to work through an attached CSV file, draw a chart or test some code. What it makes comes back to you as an artifact.

A computer belongs to one response. It is made on that response's first computer tool call, stays the same machine for every later call in the same response, and goes away when the response is done. A turn that calls no computer tool costs nothing.

The same computer also runs your organisation's own programs, offered as one tool each: see Scripts through the API. A script needs the computer capability but not the three tools below.

What your key needs¶

1. The computer capability. It depends on tooling, so switch that on as well.
2. The system tool computer in the key's tooling configuration. That one switch offers all three computer tools; in the console it is called Use a computer (Keys).
3. files if the model should read your attachments, and artifacts if you want files back from the computer.

{
  "name": "Reporting",
  "capabilities": {
    "tooling": { "system_tools": ["computer"] },
    "computer": {},
    "files": {},
    "artifacts": {}
  }
}

Your organisation must permit computer too. An organisation that existed before computers did does not permit it automatically: running code is a deliberate choice of whoever administers the organisation above, or of your operator.

Your deployment must also run computers for your organisation. Where it does not, Core refuses a request naming a computer tool with 400 and "This tool is not configured on this deployment.", before the model runs. The 400 carries "computer_not_configured" as error.code. Calling such a tool directly with POST /tools/{name}/call answers 422 on name instead, with "reason_code": "computer_not_configured" in the problem body.

The three tools¶

A relative path is under /workspace. Calls in one round run one after another, in the order the model wrote them, so a script written and then run works as intended.

A request¶

Offer the three tools like any other tool, and attach the files the model should work with:

{
  "model": "<a model id>",
  "input": [
    {
      "role": "user",
      "content": [
        { "type": "input_text", "text": "Add up the revenue per month and draw it as a bar chart." },
        { "type": "input_file", "file_id": "src_3Wq8..." }
      ]
    }
  ],
  "tools": [
    { "type": "tool", "name": "builtin__computer_exec" },
    { "type": "tool", "name": "builtin__computer_write_file" },
    { "type": "tool", "name": "builtin__computer_read_file" }
  ]
}

Or offer them through a toolset with the pattern builtin__computer_*.

Files in and out¶

In. On the first computer call, Core copies the files the turn attaches — its input_file and input_image items — to /workspace/inputs/<file id>/<file name>. It does so only for a key that holds files, and only for files the key may also read through GET /files/{id}/content: a file the key's policy does not name, one that belongs to another person or one deleted since is skipped. An artifact is not copied in.

Out. A file leaves the computer only when the model exports it, with builtin__computer_read_file and export: true. It becomes an artifact of your key, with the same maximum as any other artifact (25 MiB). Without artifacts it is not kept and the model is told so. Find a response's artifacts with:

GET /api/v1/artifacts?response_id=resp_...

GET /artifacts/{id}/content then answers the bytes (Files).

The computer's disk is scratch space. Whatever was not exported is gone when the computer stops.

What a computer cannot do¶

• No network. The computer cannot reach the internet, nor your own systems. Send what it needs as an attachment. The exception is a deployment whose operator offers computers that reach the internet, for an organisation that switched computer_internet on, along with every organisation above it: there, code on the computer can connect out and send its arguments and files anywhere. Without the switch you get a computer with no network, or none where the deployment has only open ones. Even with it you get no such computer when your policy names allowed regions or vendors, narrows the hosts it may reach, or requires personal data hidden, or when your key hides personal data. An organisation that has set allowed hosts is refused too. A residency exception does not change that; every computer call answers Denied by policy..
• Through Core's proxy, where the deployment runs one. A computer that reaches the internet is then told to use Core's egress proxy: HTTPS_PROXY, HTTP_PROXY and their siblings are set for every command, with a credential that belongs to that computer alone. Traffic that goes through the proxy is logged -- host, bytes, time -- and the proxy refuses what your organisation's rules refuse; where the deployment configures a rate limit it is limited per organisation, and a limiter that does not answer lets connections through. You read the log with GET /computers/{computer_id}/egress or GET /computer-egress, narrowed by host, opened_after and opened_before. Traffic that bypasses Core's proxy -- a tool that ignores the proxy variables, a socket opened directly -- still reaches the internet, and is not logged, not limited, and not checked against the block list or the private-address rule.
• The proxy's credential is visible to code on the computer. It is in the computer's environment and in /workspace/.artific/proxy.env, so a command that prints it puts it in the turn's output, and from there in the turn's items and its trace. It belongs to that one computer, and where the operator sets that up the proxy is reachable only from the address computers connect out from. It stops opening the proxy when the computer is destroyed or its lifetime ends, and also when the key is deleted, expired or disabled, when the organisation is not active, or when the switch is no longer in force; the proxy checks this about every 30 seconds.
• No computer across a conversation. Every response gets a new computer. The next response in the same conversation starts with an empty disk; what the model needs there must be in an artifact or in the conversation. The one exception is a computer a shell task keeps: the turns of the thread find it while it is kept.
• Not outside a turn of its own. A computer tool you call directly, or name in a nested turn, is refused with A computer tool runs only in a turn of its own. A step of an evaluation is an ordinary turn and can use a computer.

How long a computer lives¶

• A synchronous turn keeps its computer until the turn ends, however it ends: answered, failed, cut off or stopped.
• A background run keeps its computer until the run completes, fails or is cancelled. When the run waits for the output of a function tool you execute (requires_action), the computer goes away; the resumed run gets a new one.
• A shell task keeps the conversation's computer while it runs and a few minutes after, so the turn that answers its result finds it.
• Never longer than the deployment's limit, one hour by default. The key can shorten it, see below.

You can also stop a computer yourself, with a key that holds computer. GET /computers lists your organisation's computers that are still alive; ?status=all lists all of them, stopped ones included, and ?response_id= those of one response. DELETE /computers/{computer_id} stops one and answers 204. When it was already gone you get 409; when Core cannot reach the machine, 503 — Core then cleans it up later on its own. The turn that was using it loses it immediately.

Limits per key¶

The computer capability's configuration narrows the deployment's limits and never widens them. A value above the limit is brought down to the limit.

{
  "capabilities": {
    "tooling": { "system_tools": ["computer"] },
    "computer": { "exec_timeout_seconds": 30, "lifetime_seconds": 600 },
    "files": {},
    "artifacts": {}
  }
}

Your operator may have set other defaults. Processor and memory are fixed per deployment and cannot be set per key.

What the model is told¶

A command's output and a file's text are untrusted, like every tool result (Tool-result trust), and are cut at 32 KiB. A command that runs out of time answers what it printed so far, headed timed out after <n> seconds. When something goes wrong, the model reads one of Core's fixed sentences:

None of these ends the turn; the model can carry on.

Regions¶

When your key's or your organisation's policy restricts regions (policy.settings.regions_allow), the region your organisation's computers run in has to be on that list. Your operator sets that region; ask them where your computers run. Outside the list, every computer call answers Denied by policy., nothing is made and the refusal is in your audit trail. Name builtin:computer as a residency exception to allow computers anyway without opening the whole region.

Usage and audit¶

For each computer Core writes one usage record of kind sandbox_seconds when it stops: the whole seconds from the moment it was ready to the moment it went away, rounded up, attributed to the key whose turn made it. When someone stops it through DELETE, the bill stays with that key. Once priced per second it counts towards your monthly cap. The console calls this kind Sandbox time.

The audit trail records computer.created and computer.destroyed (with the seconds it ran), computer.destroy_requested when someone stopped it through the API or the console, and per call computer.executed with its kind (exec, write_file, read_file), its duration and, for a command, its exit code, and computer.egress_rate_limited when Core's egress proxy refused a connection for your organisation's share. The command itself, its output and file names never reach the audit trail; they are kept in the turn itself and its trace, under your organisation's retention window.