Add Runtime Skill

Decision Framework

These values are consistent across all runtimes and should be kept as-is unless there is a strong, documented reason to deviate:

• Fsize: 64 MiB (sufficient for typical output files)
• Nproc: "soft" (inherits system soft limit; per-sandbox limiting uses cgroup_pids_max)
• MemMax: 268435456 (256 MiB physical memory; prevents host OOM)
• MemSwapMax: 0 (swap disabled for strict memory enforcement)
• CpuMsPerSec: 900 (90% of one core)

These values require runtime-specific analysis:

AS (Virtual Address Space, in MiB)

The AS limit controls the maximum virtual address space. It does NOT directly limit physical memory (that's MemMax). Unmapped VAS pages consume no RAM, so a higher AS is safe when MemMax constrains physical usage.

How to decide: Run the runtime with a simple program and check its VAS usage (/proc/<pid>/status → VmSize). Then add 2-4× headroom. If the runtime uses mmap-based garbage collection (like V8 or JVM), use 4096.

Nofile (Open File Descriptors)

PidsMax (Per-cgroup Process + Thread Limit)

How to decide: Run a "hello world" program and check the peak thread/process count. Then add headroom for user-created threads. Interpreters that rarely spawn threads → 32. Runtimes with native concurrency support → 64.

For Compiled Runtimes

Compiled runtimes need TWO sets of limits: one for compilation (CompileLimits) and one for execution (Limits). Compilation typically needs:

• Higher AS (compiler toolchains are memory-hungry)
• Higher Nofile (many concurrent source file reads)
• Higher PidsMax (compiler parallelism)

Step 2: Verify mise Installation

Before writing code, verify that the runtime installs correctly via mise on the target platform (Debian bookworm / glibc).

# Check available versions
mise ls-remote <tool> | tail -20

# Check if special settings are needed (like ruby.compile=false)
# Search mise docs for the tool

Key considerations:

• The Dockerfile uses a glibc-linked mise binary (not musl). This is because mise's libc detection affects which precompiled binaries it downloads. A musl-linked mise would download musl Python/Ruby/etc., which won't run on Debian (glibc).
• Some runtimes need special mise settings (e.g., ruby.compile=false to use prebuilt binaries instead of compiling from source).
• Check if the runtime binary path follows the standard pattern: /mise/installs/<tool>/<version>/bin/<executable>.

Step 3: Implementation Checklist

The following files need changes. Items marked with ★ apply only to compiled runtimes.

3.1 internal/sandbox/runtime.go

3.1a Add Runtime Constant

Add the constant to the const block. Insert before RuntimeBash (Bash is always last by convention):

const (
    RuntimeNode   RuntimeName = "node"
    RuntimeRuby   RuntimeName = "ruby"
    RuntimeGo     RuntimeName = "go"
    RuntimePython RuntimeName = "python"
    // ← Insert new runtime here (before RuntimeBash)
    RuntimeBash   RuntimeName = "bash"
)

3.1b Register in Runtimes Map

Add the entry to the runtimes map variable, matching the constant order:

var runtimes = map[RuntimeName]Runtime{
    RuntimeNode:   nodeRuntime{},
    RuntimeRuby:   rubyRuntime{},
    RuntimeGo:     goRuntime{},
    RuntimePython: pythonRuntime{},
    // ← Insert new runtime here (before RuntimeBash)
    RuntimeBash:   bashRuntime{},
}

3.1c Implement Runtime Struct

Insert the implementation between the preceding runtime's section and the next one. Follow the // --- Name --- section header convention.

Interpreted runtime template (use Ruby/Python as reference):

// --- LanguageName ---

type langRuntime struct{}

func (langRuntime) Name() RuntimeName { return RuntimeLang }

func (langRuntime) Command(entryFile string) []string {
    return []string{"/mise/installs/<tool>/<version>/bin/<executable>", entryFile}
}

func (langRuntime) BindMounts() []BindMount {
    return []BindMount{{Src: "/mise/installs/<tool>/<version>", Dst: "/mise/installs/<tool>/<version>"}}
}

func (langRuntime) Env() []string {
    return []string{"PATH=/mise/installs/<tool>/<version>/bin:/usr/bin:/bin"}
}

// Limits returns resource limits for <Language> execution.
// Rlimits:
//   - AS <value> MiB: <rationale>.
//   - Fsize 64 MiB: sufficient for typical output files.
//   - Nofile <value>: <rationale>.
//   - Nproc soft: inherits the system soft limit; per-sandbox process limiting is handled by cgroup_pids_max.
//
// Cgroups:
//   - PidsMax <value>: per-cgroup task limit (processes + threads); limits fork bombs and runaway thread creation.
//   - MemMax 268435456 (256 MiB): physical memory limit; prevents sandbox OOM from affecting the host.
//   - MemSwapMax 0: swap disabled to enforce strict memory limits.
//   - CpuMsPerSec 900: throttle CPU to 900 ms per second (90% of one core).
func (langRuntime) Limits() Limits {
    return Limits{
        Rlimits: Rlimits{
            AS:     "<value>",
            Fsize:  "64",
            Nofile: "<value>",
            Nproc:  "soft",
        },
        Cgroups: Cgroups{
            PidsMax:     "<value>",
            MemMax:      "268435456",
            MemSwapMax:  "0",
            CpuMsPerSec: "900",
        },
    }
}

func (langRuntime) RestrictedFiles() []string { return nil }

★ Compiled runtime: additionally implement the CompiledRuntime interface methods (CompileCommand, CompileBindMounts, CompileEnv, CompileLimits) following the Go runtime as reference. Add var _ CompiledRuntime = langRuntime{} type assertion after the existing one for Go.

3.1d Default Files (if needed)

If the runtime requires default files (like Go's go.mod and go.sum), create them under internal/sandbox/defaults/<runtime>/. Files with .tmpl suffix have the suffix stripped at runtime. Most interpreted runtimes need no default files.

3.1e Restricted Files (if needed)

If certain filenames must be rejected (like Go's go.mod, go.sum, main), return them from RestrictedFiles(). Most interpreted runtimes return nil.

3.2 Dockerfile

Add the runtime installation in the base stage, after the existing runtime installations:

# <Tool>
ENV PATH="/mise/installs/<tool>/<version>/bin:$PATH"
RUN mise use -g <tool>@<version>

If the runtime needs special mise settings (like Ruby's ruby.compile=false), add them in the same RUN command.

★ Compiled runtime: may need additional setup like pre-building standard libraries or pre-downloading dependencies (see Go's pattern with go build std and go mod download).

3.3 internal/sandbox/sandbox_test.go

Add 4 test entries:

3.3a Test_LookupRuntime — add valid runtime entry:

{name: "<lang> is valid", runtime: Runtime<Lang>, wantErr: false},

3.3b Test<Lang>Runtime_Limits — add new test function:

func Test<Lang>Runtime_Limits(t *testing.T) {
    t.Parallel()
    rt := <lang>Runtime{}
    got := rt.Limits()
    assert.Equal(t, "<AS>", got.Rlimits.AS)
    assert.Equal(t, "64", got.Rlimits.Fsize)
    assert.Equal(t, "<Nofile>", got.Rlimits.Nofile)
    assert.Equal(t, "soft", got.Rlimits.Nproc)
    assert.Equal(t, "<PidsMax>", got.Cgroups.PidsMax)
    assert.Equal(t, "268435456", got.Cgroups.MemMax)
    assert.Equal(t, "0", got.Cgroups.MemSwapMax)
    assert.Equal(t, "900", got.Cgroups.CpuMsPerSec)
}

★ Compiled runtime: also test CompileLimits() in the same function (see TestGoRuntime_Limits).

3.3c Test_readDefaultFiles — add sub-test:

t.Run("<lang> has no defaults", func(t *testing.T) {
    t.Parallel()
    files, err := readDefaultFiles(Runtime<Lang>)
    assert.NoError(t, err)
    assert.Empty(t, files)
})

If the runtime HAS default files, assert their names and content instead.

3.3d TestRuntime_RestrictedFiles — add sub-test:

t.Run("<lang> has no restricted files", func(t *testing.T) {
    t.Parallel()
    rt, err := LookupRuntime(Runtime<Lang>)
    require.NoError(t, err)
    assert.Empty(t, rt.RestrictedFiles())
})

If the runtime HAS restricted files, use assert.ElementsMatch instead.

3.4 e2e/tests/api/validation.yml

Update the "unknown runtime" test case's expected error message to include the new runtime in alphabetical order: