Copied to clipboard!
Safety & Control

Security built from the ground up

Sesi enables safe mode by default, blocks shell execution, and restricts filesystem access to approved workspace paths unless you explicitly opt out.

Safe mode
Enabled by default; sensitive process execution such as exec and spawn is blocked.
-a, --allowed-paths
Adds explicit directories to the filesystem path whitelist.
--timeout <ms>
Stops execution after a caller-selected deadline.
Runtime sandbox

Restricted execution is the default.

Every normal CLI run starts with safe mode enabled unless the operator deliberately disables it. Safe mode controls process execution, host-integrated runtimes, server creation, browser automation, media processes, and filesystem reach.

Default postureSESI_SAFE_MODE is treated as enabled unless explicitly set to false.

OperationSafe modeReason
exec / run / spawnBlockedPrevents direct host command and subprocess execution.
python / jsBlockedPrevents arbitrary code execution through external runtimes.
std/browserBlockedBrowser automation can interact with external pages and the host.
std/apiBlockedNative HTTP and WebSocket servers cannot be opened in safe mode.
ffmpeg / gif / videoBlockedCommand-line media processing launches native processes.
open / open_fileBlockedPrevents a script from launching host applications or viewers.
file operationsScopedPermitted only when the resolved path remains inside an allowed directory.
normal language logicAllowedValues, functions, loops, transformations, and ordinary computation remain available.

Safe mode is a runtime policy, not a claim that every permitted operation is risk-free. Programs still need input validation, sensible timeouts, and careful credential handling.

Filesystem boundaries

Paths are resolved before access.

Sesi resolves a requested path to an absolute location, compares it with the allowed directory set, and rejects escapes before the filesystem operation runs.

blocked-path.sesiRejected
try {  let data = read_file("../outside_file.txt")  show data} catch (err) {  show "Blocked:" err}
Security Violation: Path traversal detected

Allowed by default

The current working directory is allowed. When a script file is executed, its own directory is also added to the allowed set.

Extend narrowly

Use -a "./data,./logs" to add explicit directories without disabling the rest of the sandbox.

Traversal still resolves

Relative .. segments and absolute paths are normalized first. A spelling trick cannot bypass the directory comparison.

Automated tool calls

Model output does not inherit operator authority.

When a model requests a function through tool_call, the interpreter applies a separate sensitive-tool denylist. This check is independent of normal function lookup.

The runtime rejects both a sensitive builtin named directly and a custom tool that resolves back to one of those builtins.

Always forbidden through automated tool execution

Enforced even if normal lookup finds the function

execrunspawnpythonjsffmpeggifvideo

Important: this denylist protects automated tool execution. Application-defined tools still need narrow inputs, validation, and minimal side effects.

Secrets & data protection

Keep credentials out of source and history.

Sesi can load credentials from the environment and encrypt scripts, strings, or embedded database files. These are separate controls with different scopes.

Environment credentials

Use environment variables for provider keys and passwords. SESI_PASSWORD lets the CLI encrypt or decrypt without placing a password in shell history.

sesi -enc private.sesi

Script & string encryption

CLI file encryption and the encrypt() builtin use an AES-256-CBC iv:ciphertext envelope with a random IV.

encrypt("private notes", password)

Database encryption

Passing a password to db_open encrypts the JSON database on disk and decrypts it during reads.

db_open("data.db", password)

Encryption boundary

The current AES-CBC envelope provides confidentiality but is not an authenticated-encryption format. Treat encrypted files as sensitive, protect backups and passwords, and use an external secret manager or authenticated storage when tamper detection is required.

Modules & dependencies

Import scope and package trust are different problems.

The allow form makes imported names visible in source. Safe mode also limits where non-standard modules may be resolved from.

Visible imports

Selective imports show which exported names enter the file. Namespaced imports keep a module behind an alias.

allow "std/db" in with {db_open}

Review third-party code

The package manager downloads GitHub repositories into sesi_modules. Review dependencies and pin a trusted tag or commit reference.

sesi install owner/repo#ref

What the sandbox does not prove: installation from GitHub is not a signature or provenance guarantee. Safe mode limits runtime authority; it does not certify that dependency logic is correct or benign.

Operator controls

Escalation should be deliberate and visible.

Prefer the narrowest control that makes the program work. Add a directory before disabling the sandbox; add a deadline before trusting a long-running task.

ControlEffectUse
defaultSafe mode onUse for ordinary scripts and unfamiliar code.
-a, --allowed-pathsAdds directoriesGrant only the extra filesystem roots a script requires.
--timeout <ms>Adds deadlineStop execution after a positive caller-selected duration.
-l, localDisables sandboxRequired for raw system commands and unrestricted local filesystem access. Use only with trusted code.
SESI_SAFE_MODE=falseDisables safe modePersistent environment override; avoid setting it globally.
Deployment checklist

Before a script touches real systems.

Security depends on the runtime configuration and the program around it. Review both before moving from a local example to automation or a service.

01

Keep safe mode enabled

Escalate only when a reviewed operation specifically requires it.

02

Minimize allowed paths

Grant dedicated data directories instead of broad parent folders.

03

Set a timeout

Bound unattended jobs and model-assisted workflows.

04

Validate inputs

Check paths, arguments, parsed data, and tool parameters before use.

05

Protect environment files

Do not commit provider keys, database passwords, or SESI_PASSWORD.

06

Review dependencies

Inspect third-party modules and pin the Git reference you intend to run.

07

Constrain tools

Expose narrowly scoped custom tools rather than generic system operations.

08

Handle failures

Catch filesystem and permission errors without leaking credentials into logs.

Trust boundaries

Know what each control guarantees.

Sesi reduces default authority and blocks common escape paths. It does not replace operating-system isolation, dependency review, network policy, secret management, backups, or application-level authorization.

The runtime enforces

  • • Safe-mode operation blocks
  • • Directory-based path checks
  • • Automated sensitive-tool denial
  • • Caller-selected execution deadlines

The operator still owns

  • • Dependency and source trust
  • • Credential lifecycle
  • • Network and process isolation
  • • Authorization and data policy

Review the implementation and current security-reporting guidance in the project repository.

Project repository