Execution Environments

Knot provides three distinct script execution environments, each tailored for specific use cases with different library availability and security constraints.

Overview

Choosing an Environment

Is it an MCP tool for AI?
├─ YES → MCP Environment
└─ NO → Is it running in a space/container?
    ├─ YES → Remote Environment
    └─ NO → Local Environment

Local Environment

Command: knot run-script

Execute scripts locally with full system access. Libraries are resolved in priority order, mirroring scriptling-cli behaviour:

1. Script directory — the directory containing the script file (or cwd for stdin/interactive)
2. Extra lib paths — --libpath / -L flags or SCRIPTLING_LIBPATH env var
3. Configured libdir — server.lib_dir in knot.toml
4. Server API — fetched on demand from the server

Security Considerations

• Full system access - use with trusted scripts only
• Can read/write files on the local machine
• Can execute system commands via subprocess
• Can load arbitrary .py files from disk

Example

# Run local script - libs resolved from script's directory first
knot run-script myscript.py arg1 arg2

# Add extra lib search paths
knot run-script -L /path/to/libs myscript.py arg1 arg2

# SCRIPTLING_LIBPATH env var also works
SCRIPTLING_LIBPATH=/path/to/libs knot run-script myscript.py

MCP Environment

Used by: AI assistants executing MCP tools

Execute tool scripts in a controlled environment designed for AI integration. This is the most restricted environment for security.

Available Libraries

Standard libraries and safe extended libraries are available. System access libraries (os, pathlib, subprocess, sys) are not available.

Security Considerations

• No filesystem access
• No command execution
• Cannot load external files
• Only fetches libraries from server
• Limited to safe operations for AI tool usage

Example

import scriptling.mcp.tool as tool

name = tool.get_string("name", "World")
tool.return_string(f"Hello, {name}!")

Remote Environment

Command: knot space run-script

Execute scripts remotely in user spaces. Scripts run inside the container with full capabilities within that container’s isolation.

Available Libraries

All standard, extended, and knot.* libraries are available, loaded on-demand from the server.

Security Considerations

• Runs in isolated container (space)
• Full capabilities within container
• No access to host filesystem
• Requires active agent connection - script execution fails if space agent is not connected
• scriptling.console provides an interactive TUI streamed back to the client terminal
• scriptling.ai.agent.interact is available for interactive AI agent sessions

Example

knot space run-script myspace myscript arg1 arg2

Library Availability Matrix

For detailed documentation on scriptling standard and extended libraries, see the Scriptling Documentation.