Shell

Execute shell commands. Requires shell.enabled: true and the command must match a pattern in shell.allowlist.

Synchronous execution

AssemblyScript

import { shellExec } from "@luminarys/sdk-as";

const result = shellExec("go build -o myapp .", "/data/project");
if (result.exit_code != 0) {
    // result.output contains stderr
}

Go

result, err := sdk.ShellExec(sdk.ShellExecRequest{
    Command: "go build -o myapp .",
    Workdir: "/data/project",
})
if err != nil {
    return "", err
}
if result.ExitCode != 0 {
    return "", fmt.Errorf("build failed: %s", result.Output)
}

Rust

let result = shell_exec(&ShellExecRequest {
    command: "go build -o myapp .".into(),
    workdir: "/data/project".into(),
    ..Default::default()
})?;
if result.exit_code != 0 {
    return Err(format!("build failed: {}", result.output).into());
}

ShellExecRequest:

Field	Type	Default	Description
command	string	required	Command to execute
workdir	string	sandbox root	Working directory
timeout_ms	int	0 (30s)	Timeout in milliseconds
tail	int	0 (all)	Return only the last N lines of output
grep	string	""	Filter output lines by regex
as_daemon	bool	false	Start as background daemon, return immediately with PID
log_file	string	""	Daemon log file path (auto-generated if empty)

ShellExecResult:

Field	Type	Description
output	string	Combined stdout + stderr
exit_code	int	Process exit code (0 = success)
pid	int	Process ID (only when as_daemon = true)
log_file	string	Log file path (only when as_daemon = true)

Background processes (daemon mode)

Start a process as a daemon — returns immediately with PID and log file path.

AssemblyScript

import { shellExec } from "@luminarys/sdk-as";

const result = shellExec(
    "./myapp serve --port 9090",  // command
    "/data/project",              // workdir
    0, 0, "",                     // timeoutMs, tail, grep
    true,                         // asDaemon
    "/data/project/server.log",   // logFile
);
// result.pid — process ID
// result.log_file — log file path

Go

result, err := sdk.ShellExec(sdk.ShellExecRequest{
    Command:  "./myapp serve --port 9090",
    Workdir:  "/data/project",
    AsDaemon: true,
    LogFile:  "/data/project/server.log",
})
// result.Pid — process ID
// result.LogFile — log file path

Rust

let result = shell_exec(&ShellExecRequest {
    command: "./myapp serve --port 9090".into(),
    workdir: "/data/project".into(),
    as_daemon: true,
    log_file: "/data/project/server.log".into(),
    ..Default::default()
})?;
// result.pid — process ID
// result.log_file — log file path

Process management

Use ps and kill commands (must be in shell.allowlist):

AssemblyScript

// List processes (filter by name)
const ps = shellExec("ps aux", "", 0, 0, "myapp");

// Stop a process
shellExec("kill 1234");

Go

// List processes (filter by name)
ps, _ := sdk.ShellExec(sdk.ShellExecRequest{
    Command: "ps aux",
    Grep:    "myapp",
})

// Stop a process
sdk.ShellExec(sdk.ShellExecRequest{Command: "kill 1234"})

Rust

// List processes (filter by name)
let ps = shell_exec(&ShellExecRequest {
    command: "ps aux".into(),
    grep: "myapp".into(),
    ..Default::default()
})?;

// Stop a process
shell_exec(&ShellExecRequest {
    command: "kill 1234".into(),
    ..Default::default()
})?;

Restrictions

• Chain operators (&&, ||, ;, |) are blocked
• Redirections (>, >>, <) are blocked
• Command substitution ($(), `) are blocked
• The command must match a pattern in shell.allowlist
• workdir must be within shell.allowed_dirs

Allowlist patterns

shell:
  enabled: true
  allowlist:
    - "go **"
    - "gofmt **"
    - "ps **"
    - "kill **"
    - "./**"
  allowed_dirs:
    - "/data/project"

** matches all remaining arguments.