Code execution

Give a Response access to the sandbox platform through either shell or code_interpreter. Both tools run on the same sandbox platform and return execution output to the model so it can continue its response. Use shell for broader workspace tasks: running commands and scripts, working with files, and combining command-line tools. Use code_interpreter when the task is specifically to write and run code, such as a calculation or data analysis. Shell can run code too; the distinction is the interface and kind of task you want to give the model. For sessions and commands controlled directly by your application, use the standalone Sandbox API.

Choose a tool

Tool	Use it for	Session configuration
`shell`	General workspace tasks, commands, scripts, and file operations	Automatic environment or an existing session ID
`code_interpreter`	Writing and running code for calculations and analysis	Automatic container with optional file IDs, or an existing session ID

The API key needs both read:sandbox and write:sandbox, as well as permission to create responses. The examples use X-On-Behalf-Of to keep execution scoped to one end user; replace its placeholder with your end-user ID. Omit it consistently if your application operates as the API-key identity. The OpenAI SDK examples use its custom-request method to send MKA1 tool configuration without changing field names to match another provider’s tool types.

Run a shell command

This request lets Responses provision the sandbox. The model decides when to invoke the tool; the prompt explicitly asks it to run a calculation and report the result.

import { SDK } from '@meetkai/mka1';

const sdk = new SDK({ bearerAuth: 'Bearer <mka1-api-key>' });

const result = await sdk.llm.responses.create({
  xOnBehalfOf: '<end-user-id>',
  responsesCreateRequest: {
    model: 'auto',
    input: "Use the shell to calculate the sum of the integers from 1 to 100, then report the result.",
    tools: [{ type: 'shell', environment: { type: 'container_auto' } }],
  },
});
console.log(result);

import OpenAI from 'openai';

const openai = new OpenAI({
  apiKey: '<mka1-api-key>',
  baseURL: 'https://apigw.mka1.com/api/v1/llm/',
  defaultHeaders: { 'X-On-Behalf-Of': '<end-user-id>' },
});

const result = await openai.post('/responses', {
  body: {
  "model": "auto",
  "input": "Use the shell to calculate the sum of the integers from 1 to 100, then report the result.",
  "tools": [
    {
      "type": "shell",
      "environment": {
        "type": "container_auto"
      }
    }
  ]
},
});
console.log(result);

from meetkai_mka1 import SDK

sdk = SDK(bearer_auth="Bearer <mka1-api-key>")

result = sdk.llm.responses.create(
    x_on_behalf_of="<end-user-id>",
    model="auto",
    input="Use the shell to calculate the sum of the integers from 1 to 100, then report the result.",
    tools=[{"type": "shell", "environment": {"type": "container_auto"}}],
)
print(result)

using System.Collections.Generic;
using MeetKai.MKA1;
using MeetKai.MKA1.Types.Components;

var sdk = new SDK(bearerAuth: "Bearer <mka1-api-key>");

var result = await sdk.Llm.Responses.CreateAsync(
    new ResponsesCreateRequest()
    {
        Model = "auto",
        Input = ResponsesCreateRequestInput.CreateStr("Use the shell to calculate the sum of the integers from 1 to 100, then report the result."),
        Tools = new List<ResponsesCreateRequestTool>
        {
            ResponsesCreateRequestTool.CreateShellToolDefinition(
                new ShellToolDefinition()
                {
                    Environment = ShellEnvironment.CreateContainerAuto(
                        new ShellEnvironmentContainerAuto()),
                }),
        },
    },
    xOnBehalfOf: "<end-user-id>"
);
System.Console.WriteLine(result);

mka1 llm responses create \
  -H 'X-On-Behalf-Of: <end-user-id>' \
  --model auto \
  --input '"Use the shell to calculate the sum of the integers from 1 to 100, then report the result."' \
  --tools '[{"type": "shell", "environment": {"type": "container_auto"}}]'

curl https://apigw.mka1.com/api/v1/llm/responses \
  --request POST \
  --header 'Authorization: Bearer <mka1-api-key>' \
  --header 'X-On-Behalf-Of: <end-user-id>' \
  --header 'Content-Type: application/json' \
  --data '{
  "model": "auto",
  "input": "Use the shell to calculate the sum of the integers from 1 to 100, then report the result.",
  "tools": [
    {
      "type": "shell",
      "environment": {
        "type": "container_auto"
      }
    }
  ]
}'

Analyze an uploaded file

Upload a CSV file first and replace <file-id> with its file ID. The automatic code-interpreter container accepts file_ids so the model can analyze the supplied file. This example expects a numeric amount column.

const result = await sdk.llm.responses.create({
  xOnBehalfOf: '<end-user-id>',
  responsesCreateRequest: {
    model: 'auto',
    input: "Use code to read the supplied CSV and calculate the sum of its amount column. Explain the result.",
    tools: [{ type: 'code_interpreter', container: { type: 'auto', fileIds: ['<file-id>'] } }],
  },
});
console.log(result);

const result = await openai.post('/responses', {
  body: {
  "model": "auto",
  "input": "Use code to read the supplied CSV and calculate the sum of its amount column. Explain the result.",
  "tools": [
    {
      "type": "code_interpreter",
      "container": {
        "type": "auto",
        "file_ids": [
          "<file-id>"
        ]
      }
    }
  ]
},
});
console.log(result);

result = sdk.llm.responses.create(
    x_on_behalf_of="<end-user-id>",
    model="auto",
    input="Use code to read the supplied CSV and calculate the sum of its amount column. Explain the result.",
    tools=[{"type": "code_interpreter", "container": {"type": "auto", "file_ids": ["<file-id>"]}}],
)
print(result)

var result = await sdk.Llm.Responses.CreateAsync(
    new ResponsesCreateRequest()
    {
        Model = "auto",
        Input = ResponsesCreateRequestInput.CreateStr("Use code to read the supplied CSV and calculate the sum of its amount column. Explain the result."),
        Tools = new List<ResponsesCreateRequestTool>
        {
            ResponsesCreateRequestTool.CreateCodeInterpreterToolDefinition(
                new CodeInterpreterToolDefinition()
                {
                    Container = Container.CreateCodeInterpreterContainerAuto(
                        new CodeInterpreterContainerAuto()
                        {
                            FileIds = new List<string> { "<file-id>" },
                        }),
                }),
        },
    },
    xOnBehalfOf: "<end-user-id>"
);
System.Console.WriteLine(result);

mka1 llm responses create \
  -H 'X-On-Behalf-Of: <end-user-id>' \
  --model auto \
  --input '"Use code to read the supplied CSV and calculate the sum of its amount column. Explain the result."' \
  --tools '[{"type": "code_interpreter", "container": {"type": "auto", "file_ids": ["<file-id>"]}}]'

curl https://apigw.mka1.com/api/v1/llm/responses \
  --request POST \
  --header 'Authorization: Bearer <mka1-api-key>' \
  --header 'X-On-Behalf-Of: <end-user-id>' \
  --header 'Content-Type: application/json' \
  --data '{
  "model": "auto",
  "input": "Use code to read the supplied CSV and calculate the sum of its amount column. Explain the result.",
  "tools": [
    {
      "type": "code_interpreter",
      "container": {
        "type": "auto",
        "file_ids": [
          "<file-id>"
        ]
      }
    }
  ]
}'

Reuse an existing session

Use an existing session when your application needs to prepare a workspace or retrieve files directly:

Create a session and wait for it to be running.
Upload your input files if the task needs them.
Set the shell environment to container_reference and use that session’s ID.
After the response finishes, inspect or download the workspace files through the Sandbox API.

The request below creates a small CSV artifact in the selected workspace. Replace <session-id> with the ID of the running session. Use the same API key and end-user identity used to create it.

const result = await sdk.llm.responses.create({
  xOnBehalfOf: '<end-user-id>',
  responsesCreateRequest: {
    model: 'auto',
    input: "Use the shell to write /workspace/squares.csv with columns n and square for integers 1 through 10. Confirm the path when done.",
    tools: [{ type: 'shell', environment: { type: 'container_reference', containerId: '<session-id>' } }],
  },
});
console.log(result);

const result = await openai.post('/responses', {
  body: {
  "model": "auto",
  "input": "Use the shell to write /workspace/squares.csv with columns n and square for integers 1 through 10. Confirm the path when done.",
  "tools": [
    {
      "type": "shell",
      "environment": {
        "type": "container_reference",
        "container_id": "<session-id>"
      }
    }
  ]
},
});
console.log(result);

result = sdk.llm.responses.create(
    x_on_behalf_of="<end-user-id>",
    model="auto",
    input="Use the shell to write /workspace/squares.csv with columns n and square for integers 1 through 10. Confirm the path when done.",
    tools=[{"type": "shell", "environment": {"type": "container_reference", "container_id": "<session-id>"}}],
)
print(result)

var result = await sdk.Llm.Responses.CreateAsync(
    new ResponsesCreateRequest()
    {
        Model = "auto",
        Input = ResponsesCreateRequestInput.CreateStr("Use the shell to write /workspace/squares.csv with columns n and square for integers 1 through 10. Confirm the path when done."),
        Tools = new List<ResponsesCreateRequestTool>
        {
            ResponsesCreateRequestTool.CreateShellToolDefinition(
                new ShellToolDefinition()
                {
                    Environment = ShellEnvironment.CreateContainerReference(
                        new ShellEnvironmentContainerReference()
                        {
                            ContainerId = "<session-id>",
                        }),
                }),
        },
    },
    xOnBehalfOf: "<end-user-id>"
);
System.Console.WriteLine(result);

mka1 llm responses create \
  -H 'X-On-Behalf-Of: <end-user-id>' \
  --model auto \
  --input '"Use the shell to write /workspace/squares.csv with columns n and square for integers 1 through 10. Confirm the path when done."' \
  --tools '[{"type": "shell", "environment": {"type": "container_reference", "container_id": "<session-id>"}}]'

curl https://apigw.mka1.com/api/v1/llm/responses \
  --request POST \
  --header 'Authorization: Bearer <mka1-api-key>' \
  --header 'X-On-Behalf-Of: <end-user-id>' \
  --header 'Content-Type: application/json' \
  --data '{
  "model": "auto",
  "input": "Use the shell to write /workspace/squares.csv with columns n and square for integers 1 through 10. Confirm the path when done.",
  "tools": [
    {
      "type": "shell",
      "environment": {
        "type": "container_reference",
        "container_id": "<session-id>"
      }
    }
  ]
}'

For code_interpreter, pass the existing session ID as the tool’s container string instead of an automatic-container object.

Retrieve generated files

A model’s statement that it wrote a file is not the file itself. For the existing-session example, inspect the workspace and download /workspace/squares.csv using the same session ID and its session token. Check that the file exists before treating the task as complete. Download artifacts before terminating the session or allowing it to expire. The standalone guide covers file transfer, workspace inspection, and session-token handling in each supported client.

Session lifetime and identity

Automatic workspaces follow the conversation. Calls with the same conversation reuse that conversation’s workspace. Calls linked by previous_response_id reuse the response chain’s workspace. A separate conversation gets a separate workspace, even for the same user. Without either reference, each response starts with a fresh workspace. All calls to the same tool within one response share its workspace. Delegated agents share their parent’s workspace by default, including agents they delegate to in turn. They keep their own prompts and message history: sharing files does not give them the parent’s conversation history. Shell and code interpreter continue to use separate runtimes, so sharing applies within the same tool type. Setting session_scope: "request" on a child agent’s tool starts a fresh workspace for that child and its delegated agents. An explicit sandbox ID on the child also overrides inheritance. Otherwise, the child inherits the parent’s memory limit, network policy, and memory-store mounts. Conflicting settings require an explicit workspace override. The child can upload its own files and load its own skills into the shared workspace. Parallel child agents can overwrite the same files in a shared workspace. Use session_scope: "request" on each child’s tool when the jobs need independent scratch files. If inherited workspace settings are no longer supported, the request returns an error identifying the parent response. It does not silently remove a memory limit, network policy, or memory-store mount. Tools that do not use a sandbox and explicit workspace overrides do not depend on the parent’s sandbox settings. Choose the lifetime that fits your task:

Choice	Code interpreter	Shell
Keep files for the conversation (default)	`container: { "type": "auto" }`	`environment: { "type": "container_auto" }`
Start fresh for each request, including turns in an existing conversation	Add `"session_scope": "request"` to the automatic container	Add `"session_scope": "request"` to the automatic environment
Reuse an existing workspace	Set `container` to its sandbox ID	Set `environment` to `{ "type": "container_reference", "container_id": "<sandbox-id>" }`

For example, this tool configuration starts a fresh code-interpreter workspace for each response, even when the request includes conversation or previous_response_id:

{
  "type": "code_interpreter",
  "container": {
    "type": "auto",
    "session_scope": "request"
  }
}

The TypeScript SDK uses sessionScope for this field. Python uses session_scope, and C# uses SessionScope. These are configuration fields on the automatic container or environment, not code-execution arguments chosen by the model. The Responses API reference describes the generated types. In the portal, use Workspace in the code-interpreter or shell settings to select the same three options. Reuse an existing workspace requires a sandbox ID. When a tool provisions a sandbox, its results include the actual container_id, and code-interpreter call items also return it. Code interpreter and shell use separate automatic workspaces. Files in explicitly attached memory stores remain shared according to the store’s access policy. A request-only workspace is shared with its default-scoped delegated agents but stays separate from later turns that switch back to the default conversation scope. A response chain uses its oldest accessible response as its workspace root. Deleting that response or losing access to it can change the workspace selected by later turns; use a conversation for continuity independent of response deletion. An existing workspace keeps the memory-store mounts and network policy it had at creation. Omit memory_stores, network_policy, and session_scope when referencing it. Use an automatic container when you need a different mount set or policy. The portal removes these creation settings when you select Reuse an existing workspace. If your integration previously relied on files persisting between unrelated requests, send conversation, link turns with previous_response_id, or explicitly reuse a sandbox. The calling identity alone no longer selects a shared workspace. Session access is scoped to the organization, team, and user. Keep X-On-Behalf-Of consistent when creating, using, and downloading from a session. A different end user cannot reuse that session simply by knowing its ID. Authorized organization administrators retain workspace-management access under the platform’s permission rules. Use your stable end-user ID for X-On-Behalf-Of; do not change the end-user identity to simulate a new conversation. Automatic sessions use the gateway’s configured idle timeout and the sandbox’s file-retention policy. An idle container can stop and later resume with retained files. After those files expire, a new automatic workspace starts empty. An explicit reference to a missing, expired, failed, or terminated session returns an error instead of silently creating an empty replacement. A reference to a session that is still provisioning waits for it to become ready. Independent automatic requests need separate containers, so they can incur cold-start or capacity-queue delays. For an explicitly managed session, terminate it once the response and any downloads have finished. See lifetime and states for expiration behavior.

Inspect results and handle failures

Check the response status and error before relying on its output. Inspect tool output as well as the final answer: a completed response can still describe a command that failed. Confirm expected artifacts through the Sandbox API. For longer execution, use background responses and wait for completion before downloading artifacts or terminating the session. Avoid blindly retrying a command that may already have changed the workspace.

Get started

SDKs and CLI

Responses

Standalone APIs

Agents

Evals

Compute

Authentication

Production

Code execution

Choose a tool

Run a shell command

Analyze an uploaded file

Reuse an existing session

Retrieve generated files

Session lifetime and identity

Inspect results and handle failures

​Choose a tool

​Run a shell command

​Analyze an uploaded file

​Reuse an existing session

​Retrieve generated files

​Session lifetime and identity

​Inspect results and handle failures

Choose a tool

Run a shell command

Analyze an uploaded file

Reuse an existing session

Retrieve generated files

Session lifetime and identity

Inspect results and handle failures