---
title: SandboxOptions
description: The options of a `workspace()` that say what its Sandbox is made of and which Repos it clones.
---

# `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](../authoring-surface.md) page lists each export. This type is not an export of `@jr2/orchestrator`, so a workflow module does not import it by name.

```ts
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`](type-size.md)

  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`](type-noslotworkspaceoptions.md)). 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`