Extend and embed

Node.js and Python

Run Warden from dependency-free Node.js and Python facades without duplicating policy or backend logic.

What the SDKs wrap

The dependency-free Node.js and Python SDKs drive the installed maelys-warden binary. They do not reimplement policy compilation, backend selection, lifecycle or receipts. Temporary policy and receipt files are private, and environment values are inherited through the child environment rather than exposed in argv.

CODE

Node.js / Python application
             │ typed options
             ▼
      Warden SDK facade
             │ stable CLI contract
             ▼
       maelys-warden run
             │
             ├── canonical MIR + backend selection
             ├── bounded supervision
             └── execution + network receipts

Node.js

CODE

const { readOnly, run } = require('@maelys/warden');

const result = await run(['npm', 'ci'], {
  policy: readOnly({
    allowWrite: ['build'],
    network: ['registry.npmjs.org:443']
  }),
  networkFrontend: 'proxy'
});

process.stdout.write(result.stdout);
console.log(result.receipt);
console.log(result.networkReceipts);

Use jsonPolicy(buffer) to supply the normative JSON policy instead of the inline builder. An AbortSignal maps cancellation to SIGTERM; the CLI then performs Warden's bounded graceful/forced shutdown.

Isolated duplex protocol

CODE

const { readOnly, spawnIsolated } = require('@maelys/warden');

const execution = spawnIsolated(['/usr/local/bin/my-protocol-worker'], {
  policy: readOnly()
});

execution.stderr.on('data', chunk => process.stderr.write(chunk));
execution.protocol.write(JSON.stringify({ op: 'build' }) + '\n');
for await (const chunk of execution.protocol) {
  // The child owns the protocol; Warden transports opaque bytes on child fd 3.
}
const result = await execution.wait();

Continuously drain protocol and stderr. Code Mode uses this fd 3 transport; it is unrelated to the optional fd 4 network frontend.

Python

CODE

from maelys_warden import Policy, run

result = run(
    ["curl", "-I", "https://github.com/"],
    policy=Policy.read_only(network=["github.com:443"]),
    network_frontend="proxy",
)

print(result.returncode)
print(result.receipt)
print(result.network_receipts)

Use Policy.json(bytes) to compile a JSON policy. The Python SDK uses only the standard library plus the installed Warden executable.

OCI targets

Both SDKs make the image, digest and platform explicit:

CODE

const result = await run(['/bin/echo', 'hello'], {
  policy: readOnly(),
  imageReference: 'alpine:3.20',
  imageDigest: 'sha256:' + 'a'.repeat(64),
  platform: 'linux/arm64',
  guestWorkspace: '/workspace',
  guestCwd: '/workspace',
  receiptSchema: 'v3'
});

backend: 'apple-container-bubblewrap' is an advanced reproducibility or diagnostic constraint: it permits exactly that candidate and forbids fallback. linux/amd64 requests translated execution explicitly; the SDK never enables or installs translation implicitly. spawnIsolated() remains local-only because its protocol fd is not transported across the VM boundary.

When to use C instead

Use the C API when the host needs in-memory JSON/MIR compilation, direct lifecycle and stream ownership, a custom backend registry, or explicit Egress adapter composition without spawning the CLI process.