Code Execution

Daytona runs Python, TypeScript, and JavaScript code in sandboxes through language kernels, so untrusted or generated code executes in isolation from your application.

Every run is a code process that executes in a session with a language kernel. The kernel keeps state between runs in the same session, so variables, imports, and functions defined in one run are available in the next. Runs use a shared kernel per language by default; isolated runs and interpreter contexts give code its own kernel. To run shell commands and manage long-running processes, see process execution. To follow a run's output live, see log streaming.

Use cases

Code execution is used when an application runs Python, TypeScript, or JavaScript that it did not write or does not trust.

• AI-generated code. An agent writes code, runs it in the sandbox, and reads the output and errors to correct its next attempt. The code runs isolated from your application. Each result also holds the exit status of the process.

• Data analysis. The kernel keeps data, imports, and functions in memory between runs, so each step builds on the previous one, as in a notebook. Runs without a context share one kernel per language, so later runs in that language see the same data. The first run in a language installs the kernel, so that run can take longer than later ones.

• Charts and tables. Runs that plot or display data return charts and tables as artifacts with the result. Each artifact is keyed by MIME type, so an application renders it in the right format. A flag on each result tells the value of the last expression apart from displayed outputs.

• Code interpreters for users. Each user or conversation gets its own interpreter context, so state from one does not reach another. A context has its own kernel, working directory, and environment. Its kernel uses memory even while idle, until the application deletes the context.

• One-off runs. An isolated kernel runs code with no state from earlier runs. The session is deleted after the run, so nothing the code defines reaches other runs. An isolated run cannot be combined with an interpreter context.

Run code

Run code in a sandbox. Runs without a context share one kernel per language, so state from one run is available to later runs in that language. The default language is Python.

The result contains the standard output and standard error, rich outputs, the exception if the code raised one, and the exit status of the process.

from daytona import Daytona

daytona = Daytona()
sandbox = daytona.v2.create()

response = sandbox.run_code('''
def greet(name):
    return f"Hello, {name}!"

print(greet("Daytona"))
''')
print(response.logs.stdout)

Artifacts

Rich outputs such as charts and tables are returned with the result, keyed by MIME type.

from daytona import Daytona

daytona = Daytona()
sandbox = daytona.v2.create()
sandbox.process.run("pip install matplotlib numpy")

code = '''
import matplotlib.pyplot as plt
import numpy as np

x = np.linspace(0, 10, 30)
plt.plot(x, np.sin(x))
plt.title("Sine wave")
plt.show()
'''

response = sandbox.run_code(code)
if response.error:
    print(response.error.name, response.error.value)
for result in response.results:
    print(list(result.data))  # MIME types, for example ['image/png', 'text/plain']

Run code in an isolated kernel

Run code in a temporary kernel that starts with no state. Daytona creates a session with a new kernel, runs the code, and deletes the session after the run. Nothing the code defines is visible to other runs, and the code does not see state from the shared kernel or from interpreter contexts.

from daytona import Daytona

daytona = Daytona()
sandbox = daytona.v2.create()

sandbox.run_code("value = 42")

# The isolated kernel does not see variables from the shared kernel
response = sandbox.run_code("print(value)", isolated=True)
if response.error:
    print(response.error.name)  # NameError

Interpreter contexts

An interpreter context is a session with its own language kernel, working directory, and environment. State persists across runs in a context and is not shared with the shared kernel or other contexts. A context lives until deleted, so its kernel uses memory while idle.

In the Toolbox API, a context is a session that runs a language kernel. Shell sessions are not created through this endpoint; see sessions.

Create a context

Create an interpreter context and run code in it. Run code with the context handle, or pass the handle to a run in the sandbox.

from daytona import Daytona

daytona = Daytona()
sandbox = daytona.v2.create()

ctx = sandbox.interpreter.create_context(language="python", env={"STAGE": "dev"})
try:
    ctx.run("value = 'stored in ctx'")
    result = sandbox.run_code("print(value)", context=ctx)
    print(result.logs.stdout)
finally:
    ctx.close()

List contexts

List a sandbox's interpreter contexts. The list also includes the shared kernel of each language that has run code, with the ID code-python, code-typescript, or code-javascript. The list does not include shell sessions.

from daytona import Daytona

daytona = Daytona()
sandbox = daytona.v2.create()

for ctx in sandbox.interpreter.list_contexts():
    print(f"Context: {ctx.context_id}, Language: {ctx.language}")

Reconnect to a context

Reconnect to an existing context from another worker or process. Contexts are addressed by ID, so any client with the sandbox ID and the context ID can run code in the context.

from daytona import Daytona

daytona = Daytona()
sandbox = daytona.v2.create()

# Worker A: create a context with a known ID
ctx = sandbox.interpreter.create_context(language="python", context_id="my-context")
ctx.run("x = 42")

# Worker B: reconnect to the context by ID
context = sandbox.interpreter.connect_context("my-context", language="python")
response = context.run("print(x)")
print(response.logs.stdout)  # 42

# Or persist the context in worker A and reconnect from the saved dict, which carries the language
saved = ctx.to_json()  # {"sandboxId": "...", "contextId": "my-context", "language": "python"}
context = sandbox.interpreter.connect_context(saved)

Delete a context

Delete an interpreter context. Deleting a context shuts its kernel down and frees its memory.

from daytona import Daytona

daytona = Daytona()
sandbox = daytona.v2.create()

ctx = sandbox.interpreter.create_context(language="python")
try:
    ctx.run("data = list(range(10_000_000))")
finally:
    sandbox.interpreter.delete_context(ctx)

Errors

The SDKs raise these errors with the codes in the following table, and the Toolbox API returns them in the code field. An exception in the code itself is not an error of the request: it is returned in the result.

Permissions

Code execution runs through the toolbox of a sandbox. Access is governed by one project permission, which you can grant to an organization role or an API key.

A sandbox access token with the toolbox:exec operation grants the same access to a single sandbox, without an API key. The sandbox read permission alone does not grant toolbox access.