codecell

Stateless, subprocess-isolated code execution for LLM agents. Zero dependencies.

Unlike a Jupyter cell, there's no shared kernel — each call runs in a fresh subprocess with only the tools you inject.

Scope: codecell is intentionally limited to sandboxed code evaluation — safe computation and namespace-based tool invocation. It is not a full runtime or a general-purpose execution engine. Features like stateful sessions, IPC-based tool calling, and container isolation may be added in future versions.

Quick start

from codecell import SubprocessRuntime
from codecell.python import PythonValidator

runtime = SubprocessRuntime(PythonValidator())
result = runtime.execute("print(1 + 2)", timeout=10)
print(result.stdout)  # "3\n"

Languages

Python (sandboxed)

AST-validated — blocks file I/O, network, command execution, dynamic imports. Only safe computation modules allowed.

from codecell import SubprocessRuntime
from codecell.python import PythonValidator

py = SubprocessRuntime(PythonValidator())

# Safe computation works
py.execute("import math; print(math.sqrt(16))")

# Dangerous code is rejected before execution
py.execute("import os; os.system('rm -rf /')")  # raises ValueError

Bash (deny-list)

Regex-based deny list blocks known-dangerous patterns. Not a sandbox — reduces risk but cannot guarantee safety.

from codecell import SubprocessRuntime
from codecell.bash import BashValidator

bash = SubprocessRuntime(BashValidator())
bash.execute("echo hello && ls -la")   # OK
bash.execute("rm -rf /")               # raises ValueError

Trusted code (no validation)

from codecell import SubprocessRuntime, NullValidator

unsafe = SubprocessRuntime(NullValidator("python"))
unsafe.execute("import os; print(os.getpid())")  # runs without validation

Namespace injection (Python only)

Inject callables into the execution namespace. In subprocess mode, they're available as stubs for discovery:

def search(query: str) -> list:
    """Search for documents."""
    ...

result = py.execute(
    "print('search' in dir())",
    namespace={"search": search},
)
# stdout: "True"

API

SubprocessRuntime(validator)

Execute code in a subprocess. The validator provides language identity and code validation.

runtime.execute(code, *, namespace=None, timeout=None) -> CodeResult

Parameter Type Description
code str Source code to execute
namespace dict[str, Callable] | None Callables to inject (Python only)
timeout float | None Max seconds before kill

CodeResult

Field Type Description
stdout str Captured standard output (truncated at 64 KB)
stderr str Captured standard error
return_code int Exit code, -1 for timeout
timed_out bool Whether killed by timeout

Validators

Validator Security level Language
PythonValidator Strong (AST analysis) Python
BashValidator Best-effort (regex deny-list) Bash
NullValidator(lang) None — trusted code only Any

License

MIT

Project links

Data verified by PyPI on Jul 2, 2026
Data provided by the project maintainers, verified at the time the release was uploaded to PyPI.

Key dates

PyPI data
Data sourced directly from PyPI's database.
  • Released:
Latest release

1 maintainer

PyPI data
Data sourced directly from PyPI's database.
Avatar for Oaklight from gravatar.com Oaklight

Credits

Author: Peng Ding

GitHub Statistics

Data verified by PyPI on Jul 2, 2026
The GitHub source repository was provided by the project maintainers and verified by PyPI at the time of upload. Stars, forks, and open issues/PRs are derived from that repository and have not been independently verified.

License expression

MIT
View SPDX License List

Requires

Python >=3.10

Provides Extra

dev test

Report project as malware

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

codecell-0.2.1.tar.gz (15.8 kB view details)

Uploaded Source

Built Distribution

If you're not sure about the file name format, learn more about wheel file names.

codecell-0.2.1-py3-none-any.whl (14.2 kB view details)

Uploaded Python 3

File details

Details for the file codecell-0.2.1.tar.gz.

File metadata

  • Download URL: codecell-0.2.1.tar.gz
  • Upload date:
  • Size: 15.8 kB
  • Tags: Source
  • Uploaded using Trusted Publishing? Yes
  • Uploaded via: twine/6.1.0 CPython/3.13.12

File hashes

Hashes for codecell-0.2.1.tar.gz
Algorithm Hash digest
SHA256 4a153e8f2116e0a0e314e7b00f0eeea304c73e3239cd3f9daac541a2ba0b2a42
MD5 04b1d4ada5960610361a32e223795e03
BLAKE2b-256 796588d8f6dba3187b550b131e5804e49b6fce2f99eb67af97af7b4e0da6fe2f

See more details on using hashes here.

Provenance

The following attestation bundles were made for codecell-0.2.1.tar.gz:

Publisher: release.yml on Oaklight/codecell

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file codecell-0.2.1-py3-none-any.whl.

File metadata

  • Download URL: codecell-0.2.1-py3-none-any.whl
  • Upload date:
  • Size: 14.2 kB
  • Tags: Python 3
  • Uploaded using Trusted Publishing? Yes
  • Uploaded via: twine/6.1.0 CPython/3.13.12

File hashes

Hashes for codecell-0.2.1-py3-none-any.whl
Algorithm Hash digest
SHA256 8b9f2e591dc11b9c0a6494a46f543fd6b20fa79c218ba56faa87d8af42ac8446
MD5 960ca2b8f16beefeb8c2f2437fe1f7f4
BLAKE2b-256 e19c667c1c9cef5f8f07bda37820cd1fb87c81a423a943d75164eeb2c0ecbf03

See more details on using hashes here.

Provenance

The following attestation bundles were made for codecell-0.2.1-py3-none-any.whl:

Publisher: release.yml on Oaklight/codecell

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

Release history Release notifications | RSS feed

This release

0.2.1 This release

2 files

0.2.0

2 files

0.1.0

2 files

Supported by

AWS Cloud computing and Security Sponsor Datadog Monitoring Depot Continuous Integration Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page