Skip to main content

Sandboxer

The main Sandboxer class. This class is intended to be used as follows, where the module is placed in ServerScriptService named Init: 

require(game:GetService("ServerScriptService").Init):Init()

This would be expected to be the first line of all scripts that are to be sandboxed (not including --!strict, --!optimize, and other directives).

Having this be the first line guarantees that the script is sandboxed before any other code runs. You would have to check if it is the first line of code yourself, using external sources with modules such as rbx-reader.

Properties​

InstanceSandboxer​

This item is read only and cannot be modified. Read Only
</>
Sandboxer.InstanceSandboxer: typeof(InstanceSandboxer)

A reference to the InstanceSandboxer class.

InstanceList​

This item is read only and cannot be modified. Read Only
</>
Sandboxer.InstanceList: typeof(InstanceList)

A reference to the InstanceList class.

Config​

This item is read only and cannot be modified. Read Only
</>
Sandboxer.Config: typeof(Config)

A reference to the Config.

Functions​

EditDefaultSandbox​

</>
Sandboxer.EditDefaultSandbox(
config: {[string]: any}--

A table containing the configuration for the sandbox.

) → boolean--

Whether the operation was completely successful.

Edits the default sandbox configuration. This is used to add or remove certain globals in the sandbox environment.

The config is saved and will be used for all future sandboxes made AFTER this function is called. Calls to this will overwrite previous values, if any.

Due to dictionary limitations, values cannot be set to nil. To remove a global, set the value to false.

The following globals are always removed from the sandbox:

  • getfenv
  • setfenv
  • loadstring
  • newproxy
  • debug (library), debug.info, & debug.traceback

Attempting to add these functions/libraries will result in them being ignored. However, you can set them to other values, such as a custom function. This will also allow you to overwrite already sandboxed globals, such as game.

The sandboxer will make no attempt to secure custom functions, so use them at your own risk.

The function will return true if the operation was completely successful (i.e., all values were set on the configuration table) and false if any of the keys or values were forbidden globals.

The table is NOT recursively checked for forbidden globals. If you manage to bypass the checks, you are responsible for any consequences.

Init​

</>
Sandboxer:Init() → ()

Initializes the sandbox environment for the calling script.

The following globals are removed:

  • SharedTable
  • debug library
  • getfenv
  • setfenv
  • loadstring
  • newproxy
  • xpcall (note: use pcall instead)

All other globals are set to sandboxed versions of the originals.

A separate table is created for _G / shared

Sandbox​

</>
Sandboxer:Sandbox(
fnOrLevel: InstanceSandboxer.AnyFn | number--

The function to sandbox or the level to sandbox at.

) → ()

Sandboxes the given function or the calling script at the specified level.

Level Definition
1 function calling Sandboxer:Sandbox
2 caller of the above function
3... etc.

Errors

TypeDescription
"level must be at least 1"If fnOrLevel is a number, it must be at least 1.

SandboxString​

</>
Sandboxer:SandboxString(
src: string,--

The specified string to be loaded as Luau code.

chunkname: string--

An optional chunk name for error messages and debug information.

) → InstanceSandboxer.AnyFn

Loads the Luau chunk src as a function using loadstring and sandboxes it. ServerScriptService.LoadStringEnabled must be true for this to work as per the loadstring rules.

Errors

TypeDescription
"loadstring() is not available"ServerScriptService.LoadStringEnabled was false.
Show raw api
{
    "functions": [
        {
            "name": "EditDefaultSandbox",
            "desc": "Edits the default sandbox configuration. This is used to add or remove certain\nglobals in the sandbox environment.\n\nThe config is saved and will be used for all future sandboxes **made AFTER this\nfunction is called**. Calls to this will overwrite previous values, if any.\n\nDue to dictionary limitations, values cannot be set to `nil`. To remove a global,\nset the value to `false`.\n\nThe following globals are **always** removed from the sandbox:\n- `getfenv`\n- `setfenv`\n- `loadstring`\n- `newproxy`\n- `debug` (library), `debug.info`, & `debug.traceback`\n\nAttempting to add these functions/libraries will result in them being ignored.\nHowever, you can set them to other values, such as a custom function.\nThis will also allow you to overwrite already sandboxed globals, such as `game`.\n\nThe sandboxer will make **no attempt** to secure custom functions, so use them\nat your own risk.  \n\nThe function will return `true` if the operation was completely successful\n(i.e., all values were set on the configuration table) and `false` if any \nof the keys or values were forbidden globals.\n\n**The table is NOT recursively checked for forbidden globals. If you manage\nto bypass the checks, you are responsible for any consequences.**",
            "params": [
                {
                    "name": "config",
                    "desc": "A table containing the configuration for the sandbox.",
                    "lua_type": "{ [string]: any }"
                }
            ],
            "returns": [
                {
                    "desc": "Whether the operation was *completely* successful.",
                    "lua_type": "boolean"
                }
            ],
            "function_type": "static",
            "source": {
                "line": 178,
                "path": "src/init.luau"
            }
        },
        {
            "name": "Init",
            "desc": "Initializes the sandbox environment for the calling script.\n\nThe following globals are **removed**:\n- `SharedTable`\n- `debug` library\n- `getfenv`\n- `setfenv`\n- `loadstring`\n- `newproxy`\n- `xpcall` (*note: use `pcall` instead*)\n\nAll other globals are set to sandboxed versions of the originals.\n\nA separate table is created for `_G` / `shared`",
            "params": [],
            "returns": [],
            "function_type": "method",
            "source": {
                "line": 227,
                "path": "src/init.luau"
            }
        },
        {
            "name": "Sandbox",
            "desc": "Sandboxes the given function or the calling script at the specified level.\n\n| Level | Definition |\n|-------|------------|\n| 1     | function calling `Sandboxer:Sandbox` |\n| 2     | caller of the above function |\n| 3...  | etc. |",
            "params": [
                {
                    "name": "fnOrLevel",
                    "desc": "The function to sandbox or the level to sandbox at.",
                    "lua_type": "InstanceSandboxer.AnyFn | number"
                }
            ],
            "returns": [],
            "function_type": "method",
            "errors": [
                {
                    "lua_type": "\"level must be at least 1\"",
                    "desc": "If fnOrLevel is a number, it must be at least 1."
                }
            ],
            "source": {
                "line": 253,
                "path": "src/init.luau"
            }
        },
        {
            "name": "SandboxString",
            "desc": "Loads the Luau chunk `src` as a function using `loadstring` and \nsandboxes it. **`ServerScriptService.LoadStringEnabled` must be `true`\nfor this to work as per the `loadstring` rules.**",
            "params": [
                {
                    "name": "src",
                    "desc": "The specified string to be loaded as Luau code.",
                    "lua_type": "string"
                },
                {
                    "name": "chunkname",
                    "desc": "An optional chunk name for error messages and debug information.",
                    "lua_type": "string"
                }
            ],
            "returns": [
                {
                    "desc": "",
                    "lua_type": "InstanceSandboxer.AnyFn\n"
                }
            ],
            "function_type": "method",
            "errors": [
                {
                    "lua_type": "\"loadstring() is not available\"",
                    "desc": "ServerScriptService.LoadStringEnabled was false."
                }
            ],
            "source": {
                "line": 414,
                "path": "src/init.luau"
            }
        }
    ],
    "properties": [
        {
            "name": "InstanceSandboxer",
            "desc": "A reference to the [`InstanceSandboxer` class](InstanceSandboxer).",
            "lua_type": "typeof(InstanceSandboxer)",
            "readonly": true,
            "source": {
                "line": 444,
                "path": "src/init.luau"
            }
        },
        {
            "name": "InstanceList",
            "desc": "A reference to the [`InstanceList` class](InstanceList).",
            "lua_type": "typeof(InstanceList)",
            "readonly": true,
            "source": {
                "line": 453,
                "path": "src/init.luau"
            }
        },
        {
            "name": "Config",
            "desc": "A reference to the [`Config`](Config).",
            "lua_type": "typeof(Config)",
            "readonly": true,
            "source": {
                "line": 462,
                "path": "src/init.luau"
            }
        }
    ],
    "types": [],
    "name": "Sandboxer",
    "desc": "The main Sandboxer class. This class is intended to be used as follows,\nwhere the module is placed in ServerScriptService named `Init`:\n```lua\nrequire(game:GetService(\"ServerScriptService\").Init):Init()\n```\nThis would be expected to be the first line of all scripts that are to be sandboxed\n(not including `--!strict`, `--!optimize`, and other directives).\n\nHaving this be the first line guarantees that the script is sandboxed before any other code runs.\nYou would have to check if it is the first line of code yourself, using external sources with\nmodules such as [rbx-reader](https://npmjs.org/package/rbx-reader).",
    "source": {
        "line": 36,
        "path": "src/init.luau"
    }
}