luasbox

Imported from woodybriggs/luasbox (SKILL.md). Install upstream with npx skills add woodybriggs/luasbox. Copyright stays with the author.

SKILL: Running luasbox

Overview

luasbox is a sandboxed Lua script runner. You (the agent) act as the approval layer — luasbox sends you requests when a script tries to access modules, functions, or call sandboxed APIs. You decide whether to approve or deny each request.

How It Works

1. Start luasbox with a script and socket path: luasbox -c config.ini --socket /tmp/luasbox.sock script.lua
2. Use luasbox-client to read requests and send approvals.
3. Repeat until the script finishes.

Protocol

Two sockets are created:

• <path>.req — agent connects to read the pending request
• <path>.approve — agent connects to send approval/denial

Each connection is short-lived: connect, send one message, disconnect.

Messages (luasbox → agent):

• REQUEST module <name> — Script wants to require a module
• REQUEST function <name> — Script wants to access a function
• REQUEST call <name> [[arg]]... — Script wants to call a function with args
• DONE — Script completed successfully
• ERROR <msg> — Script error

Messages (agent → luasbox):

• APPROVED — Allow the request
• DENIED — Block the request

Using luasbox-client

# Read the pending request
luasbox-client /tmp/luasbox.sock read
# → REQUEST module io

# Approve the request
luasbox-client /tmp/luasbox.sock approve

# Read + approve in one step
luasbox-client /tmp/luasbox.sock auto
# → REQUEST module io
# (sends APPROVED automatically)

# Deny a request
luasbox-client /tmp/luasbox.sock deny

Bash Example

# Start luasbox
luasbox -c sandbox.ini --socket /tmp/luasbox.sock script.lua &

# Read and approve each request
luasbox-client /tmp/luasbox.sock auto  # REQUEST module io
luasbox-client /tmp/luasbox.sock auto  # REQUEST module math
luasbox-client /tmp/luasbox.sock auto  # REQUEST call io.open [[/tmp/f.txt]] [[w]]

Decision Strategy

When in doubt, ask the human.

Notes

• Each approval is per-operation. Once io.open is approved, future calls still go through the protocol.
• If no response is sent within30 seconds, the request is denied automatically.
• os.execute is always blocked even if approved — the sandbox enforces this.
• Scripts must use local io = require("io") (assign to variable) since standard lib globals are sandboxed.