SandboxOptions

Type, in @jr2/orchestrator/src/workspace.ts. The signature of an export, or a type that it names, names this type. The Authoring surface page lists each export. This type is not an export of @jr2/orchestrator, so a workflow module does not import it by name.

type SandboxOptions<TSlots extends string, TInput = unknown> = {
  image?: string;
  user?: string | UserContainer;
  resources?: Size;
  repos: Record<TSlots, RepoSlot<TInput>> | typeof open;
  secrets?: readonly string[];
  effector?: { image: string };
};

The options of a workspace() that say what its Sandbox is made of and which Repos it clones. They are the same for each run.

Fields

• image (optional): string

  The Sandbox Image: the image of the container where the Agent's Working tools and command Effects run. A file: URL to a docker context that your module ships (import.meta.resolve("./image")), which jr2 up builds, or a registry ref. Its floor is glibc and git; jr2 adds its own runtime at /opt/jr2. Default: the Instance's images/default, then jr2's Harness image.

• user (optional): string | UserContainer

  The User Container: a third container in the Sandbox, for a service that must run beside the Agent, such as an sshd. Its image, in the same two forms as image, or { image, resources } to give it a part of the Size. It runs its own entrypoint, with /work mounted. jr2 adds nothing to it. Default: none. Without resources, it has no limit of its own and shares the Size of the Sandbox.

• resources (optional): Size

  The Size: the memory and cpu limit of the whole Sandbox, { limits: { memory, cpu } }, such as { limits: { memory: "4Gi", cpu: "2" } }. jr2 reserves all of it on the node: each request equals its limit. jr2 also enforces the cpu limit. Only limits, and in it only memory and cpu, are accepted. Default: the Instance's sandbox.resources, then 2Gi and 1 cpu. Under a Size that you give, a field you leave out takes the kit's value, not the Instance's. The Instance that registers the Machine can change it with customize(machine, { resources }).

• repos: Record<TSlots, RepoSlot<TInput>> | typeof open

  The Repo Slots: the repositories that the Sandbox clones, each under a name of your Machine's choice. The name is the key of workspace.repos in the body and the directory under /work. At least one slot. Leave repos out for a Workspace with no Repo Slot (see NoSlotWorkspaceOptions). Each value is one of:

  • a url, or { url, ref }, where ref is the branch or commit that the Worktree starts from (default: the Repo's default branch);
  • open, for the Instance that registers the Machine to bind with customize();
  • a function of the run input, ({ input }) => url or { url, ref }, when each run chooses.

  Or repos: open for the whole map: the Machine names no slot, and the Instance that registers it names each one with customize(). The body's input is then Workspaced<RunInput, string>.

• secrets (optional): readonly string[]

  The Held secrets that this Sandbox can use: names from the secrets list in jr2.config.ts. The Sandbox's Custodian holds each value and puts it into requests to the hosts of that Held secret. The Agent sees only a Stand-in. You need not list the model key of an Agent that runs here: its provider claims it. Each name once.

• effector (optional): object

  The image of the Sandbox Effector. This container runs three kinds of Effect for this Workspace: a push, an http Effect with a Worktree file as its body, and a command with an Effect secret in its env. It gets the Effect secrets that those Effects name. Give an image when those Effects need tools or credentials that you keep out of the Sandbox Image, such as terraform. A file: URL or a registry ref, as for image. Default: the Sandbox Image, which already holds git.

  • image: string