Server facts and programs

system lets a server-side app read a few facts about its machine and run the programs it needs, such as git, only when main.yaml declares them.

Like disk, it works through permissions: a fact or program that is not declared is refused. The app does not import node:os or node:child_process for this; mainsdk check fails on that (MAIN-PERM-0001). Programs run without a shell, so the arguments are never interpreted. system is server side only and free on every plan.

permissions:
  mode: enforce
  system: [hostname, platform]
  processes: [git]

import { system } from "mainsdk";

// allowed only if git is under permissions.processes and the URL is in network.allow
const out = await system.run("git", ["ls-remote", "https://github.com/acme/app.git"]);
const os = system.platform();

import assert from "node:assert/strict";
import { it } from "node:test";
import { createTestApp } from "@mainsdk/testing";
import { system } from "mainsdk";

it("app-permissions AC2 refuses a fact that is not declared", () => {
  createTestApp({ yaml: "schema: 1\nproject: t\npermissions:\n  system: [hostname]\n" });
  assert.equal(typeof system.hostname(), "string");
  assert.throws(() => system.user(), { code: "MAIN-PERM-0002" });
});

system:
  driver: builtin

Quick start

permissions:
  mode: enforce
  system: [hostname, platform]
  processes: [git]

import { system } from "mainsdk";

export function buildInfo() {
  // allowed: platform is under permissions.system
  const { os, arch, node } = system.platform();
  return { host: system.hostname(), os, arch, node };
}

export async function currentCommit() {
  // allowed: git is under permissions.processes
  const { stdout } = await system.run("git", ["rev-parse", "HEAD"]);
  return stdout.trim();
}

Configuration

Every key below lives under permissions:.

permissions:
  mode: enforce                  # observe | enforce
  system: [user, hostname, platform, network-interfaces]
  processes: [git, curl]

What you get

• Four facts, each declared before use: the running user, host name, platform and network addresses.
• system.run for programs you declare under processes, run without a shell, with a timeout and capped output.
• Every URL in a program's arguments checked against network.allow before it starts.
• Every use recorded as a decision with the calling file and line.

Calls

createSystem(perm) builds a system on a permission layer, and SYSTEM_FACTS (a constant array, not a function) lists the fact names a system permission may hold: user, hostname, platform, network-interfaces.

system.run takes opts.cwd (a folder the app may read under permissions.disk, or the folder inside a disk.temp call; default is the app folder) and opts.timeoutMs (default 60 seconds). A program that starts and exits non-zero returns its code; it does not throw. Output is limited to 16 MB per stream.

URLs in program arguments

A program that reaches the network, such as git clone https://…, git ls-remote git@github.com:… or curl https://…, has every URL in its arguments checked against network.allow before it starts. A host that is not allowed is refused with MAIN-NET-0002, so declaring git does not open every host to it.

Examples

Fetch a repository's default branch

import { system } from "mainsdk";

// allowed: git is under processes; github.com is under network.allow
const { stdout } = await system.run("git", ["ls-remote", "--symref", "https://github.com/acme/app.git", "HEAD"]);

network:
  allow: [github.com]
permissions:
  processes: [git]

Report which host the app runs on

import { system } from "mainsdk";

export function GET() {
  return Response.json({ host: system.hostname(), platform: system.platform().os });
}

permissions:
  system: [hostname, platform]

Errors and checks

Swapping drivers

system has no driver. It reads the machine it runs on and always runs programs without a shell. What changes between environments is the permissions block: set permissions.system and processes per environment in main.yaml.

Testing

createTestApp() from @mainsdk/testing reads your permissions. Facts and programs are the real ones of the machine the test runs on, so assert on shape, not on a value.

import assert from "node:assert/strict";
import { it } from "node:test";
import { createTestApp } from "@mainsdk/testing";
import { system } from "mainsdk";

it("app-permissions AC2 refuses a fact that is not declared", () => {
  createTestApp({ yaml: "schema: 1\nproject: t\npermissions:\n  system: [hostname]\n" });
  assert.equal(typeof system.hostname(), "string");
  assert.throws(() => system.user(), { code: "MAIN-PERM-0002" });
});

permissions.decisions() on the test app lists each decision with its file and line. A fake for system.run is planned.

Security and privacy

• Deny by default. Only the facts and programs under permissions can be used.
• Programs run with execFile and no shell, so arguments are passed as they are.
• URLs in arguments are checked against the network list before the program starts.
• Every use is recorded as a decision with the calling file and line, and mainsdk info lists them.
• The facts are about the server. They are not sent anywhere by this interface.

FAQ

Can I run sh -c through system.run? Declare sh under processes only if you accept that the shell can run anything it is given. The better route is a program with fixed arguments.

Why did a program work in my terminal but fail here? Check that it is installed on the server the app runs on, and that it is declared under processes. A missing program fails with MAIN-PERM-0005.

Does system read environment variables? No. Read configuration through config or secrets.

Next

• Local files: the folders the app may read and write.
• Network permissions: the hosts a program may reach.
• Declare what your app uses: run discovery and write the permissions block.