Inject secrets and harden a box

import asyncio

# SimpleBox is the recommended high-level entry point (async context manager).
# Secret is exported at the top level; secrets= is passed through to the underlying BoxOptions via **kwargs.
from boxlite import SimpleBox, Secret

async def main() -> None:
    secret = Secret(
        name="demo",                       # the placeholder defaults to <BOXLITE_SECRET:demo>
        value="<YOUR_API_KEY>",            # TODO: replace with a real credential; it exists only on the host side
        hosts=["api.example.com"],         # injected only when requesting these hosts (supports *.example.com wildcards)
    )

    try:
        async with SimpleBox(image="python:slim", secrets=[secret]) as box:
            # the in-guest script uses the placeholder, not the real key.
            # on egress to api.example.com, the host proxy replaces the placeholder with the real value.
            script = (
                "import urllib.request\n"
                "req = urllib.request.Request(\n"
                "    'https://api.example.com/v1/ping',\n"
                "    headers={'Authorization': 'Bearer <BOXLITE_SECRET:demo>'},\n"
                ")\n"
                "print(urllib.request.urlopen(req, timeout=10).status)\n"
            )
            result = await box.exec("python", "-c", script)
            # a non-zero exit code does not raise; check exit_code yourself.
            if result.exit_code != 0:
                print("command failed:", result.stderr)
            else:
                print(result.stdout)
    except RuntimeError as e:
        # image pull failure / startup failure with no virtualization both raise a standard RuntimeError.
        print("box failed to start:", e)

if __name__ == "__main__":
    asyncio.run(main())

import asyncio
import uuid

import boxlite
from boxlite import Secret

REAL_TOKEN = "<YOUR_API_TOKEN>"  # <-- replace; stays on the host, never enters the box

async def main() -> None:
    secret = Secret(name="testkey", value=REAL_TOKEN, hosts=["httpbin.org"])
    runtime = boxlite.Boxlite.default()
    box = None
    try:
        box = await runtime.create(
            boxlite.BoxOptions(
                image="alpine:latest",
                auto_remove=False,
                # injection requires egress through the proxy: enable the network and allow the target host
                network=boxlite.NetworkSpec(mode="enabled", allow_net=["httpbin.org"]),
                secrets=[secret],
            ),
            name=f"secret-demo-{uuid.uuid4().hex[:8]}",
        )
        # in the guest, BOXLITE_SECRET_TESTKEY is the placeholder; the real value is not in env
        ex = await box.exec(
            "wget",
            [
                "-q", "-O-",
                "--header", "Authorization: Bearer <BOXLITE_SECRET:testkey>",
                "https://httpbin.org/headers",
            ],
        )
        body = "".join([line async for line in ex.stdout()])
        result = await ex.wait()
        # the Authorization header in the body is the real value (the placeholder was replaced by the proxy
        # on egress; the real value never entered the guest).
        print("exit:", result.exit_code, "real value reached upstream:", REAL_TOKEN in body)
    finally:
        if box is not None:
            try:
                await box.stop()
            except Exception:
                pass
            try:
                await runtime.remove(box.id, force=True)
            except Exception:
                pass
        runtime.close()

if __name__ == "__main__":
    asyncio.run(main())

{ "headers": { "Authorization": "Bearer <the real value you passed to Secret(value=...)>", "Host": "httpbin.org", ... } }

import asyncio

from boxlite import SimpleBox, SecurityOptions
# Note: AdvancedBoxOptions is not exported at the top level; it must be imported from boxlite.boxlite.
from boxlite.boxlite import AdvancedBoxOptions

async def main() -> None:
    advanced = AdvancedBoxOptions(security=SecurityOptions.maximum())

    try:
        # advanced= is passed through to the underlying BoxOptions via SimpleBox's **kwargs.
        async with SimpleBox(image="alpine:latest", advanced=advanced) as box:
            result = await box.exec("id")
            if result.exit_code != 0:
                print("command failed:", result.stderr)
            else:
                print(result.stdout)
    except RuntimeError as e:
        print("box failed to start:", e)

if __name__ == "__main__":
    asyncio.run(main())

import asyncio

from boxlite import SimpleBox, Secret, SecurityOptions
from boxlite.boxlite import AdvancedBoxOptions

async def main() -> None:
    secret = Secret(
        name="demo",
        value="<YOUR_API_KEY>",  # TODO: replace with a real credential
        hosts=["api.example.com"],
    )
    advanced = AdvancedBoxOptions(security=SecurityOptions.maximum())

    try:
        async with SimpleBox(
            image="python:slim",
            secrets=[secret],
            advanced=advanced,
        ) as box:
            result = await box.exec("echo", "secrets + hardening ready")
            print(result.stdout if result.exit_code == 0 else result.stderr)
    except RuntimeError as e:
        print("box failed to start:", e)

if __name__ == "__main__":
    asyncio.run(main())

// the package name is @boxlite-ai/boxlite (not 'boxlite'). Pure ESM.
import { SimpleBox } from "@boxlite-ai/boxlite";

async function main(): Promise<void> {
  try {
    // SimpleBox implements AsyncDisposable; use `await using` for automatic release.
    await using box = new SimpleBox({
      image: "python:slim",
      secrets: [
        {
          name: "demo",
          value: "<YOUR_API_KEY>", // TODO: replace with a real credential
          hosts: ["api.example.com"],
          // when placeholder is omitted, it defaults to <BOXLITE_SECRET:demo>
        },
      ],
      // Node has no maximum() preset; pass the object directly (seccomp takes effect on Linux only).
      security: {
        jailerEnabled: true,
        seccompEnabled: true,
        maxOpenFiles: 1024,
        maxProcesses: 100,
        closeFds: true,
      },
    });

    const result = await box.exec("echo", "secrets + hardening ready");
    console.log(result.exitCode === 0 ? result.stdout : result.stderr);
  } catch (err) {
    // a missing command / pull failure throws a bare Error, not necessarily BoxliteError.
    console.error("box failed:", err);
  }
}

main();

# Wrong
# from boxlite import AdvancedBoxOptions

# Correct
from boxlite.boxlite import AdvancedBoxOptions

from boxlite import SecurityOptions

debug_only = SecurityOptions.development()  # jailer and seccomp both off — diagnosis only