---
title: just-bash Sandbox
description: Use a pure-JavaScript shell and virtual filesystem.
url: "https://eve.dev/docs/sandbox/just-bash"
docs_index: /llms.txt
---

> For an index of all documentation, see [/llms.txt](/llms.txt).

`JustBashSandbox.environment()` gives each session a pure-JavaScript shell and a virtual filesystem that keeps its files between turns. It starts no container or VM.

```ts title="agent/sandbox.ts"
import { defineSandbox } from "eve/sandbox";
import { JustBashSandbox } from "eve/sandbox/just-bash";

export const environment = JustBashSandbox.environment();
export default defineSandbox(() => environment.open());
```

just-bash can't use OCI images or Dockerfiles, runs no native processes, and provides no network isolation. Its session has no `setNetworkPolicy()`.

## Automatic installation

During `eve dev`, eve installs the `just-bash` package into your application when an environment uses it and it's missing. Set `autoInstall: false` in the environment options to skip this. Other commands require you to install the package yourself.

With pnpm, automatic installation skips the optional native codecs `@mongodb-js/zstd` and `node-liblzma` unless they have an explicit package policy. It adds them to `ignoredOptionalDependencies` in the `pnpm-workspace.yaml` of the workspace that contains your app. Basic shell and filesystem operations don't need them, but commands that do may be unavailable. eve keeps your existing per-package build settings and doesn't approve build scripts.

## Experimental options

`experimental.customCommands` and `experimental.filesystem` follow just-bash's own command and filesystem contracts, so they have no compatibility promise. Import their types, such as `JustBashCommand` and `JustBashFilesystem`, from `eve/experimental/sandbox/just-bash`. `autoInstall` and `prepare` are stable.

### Custom commands

`experimental.customCommands` adds your own functions as commands in each live shell. They work in pipelines and redirections:

```ts
import { defineSandbox } from "eve/sandbox";
import type { JustBashCommand } from "eve/experimental/sandbox/just-bash";
import { JustBashSandbox } from "eve/sandbox/just-bash";

const today: JustBashCommand = {
  name: "today",
  async execute() {
    return { exitCode: 0, stderr: "", stdout: `${new Date().toISOString().slice(0, 10)}\n` };
  },
};

export const environment = JustBashSandbox.environment({
  experimental: { customCommands: [today] },
});
export default defineSandbox(() => environment.open());
```

A `JustBashCommand` receives `cwd`, `env`, `fs`, and `signal` in its context. When a command needs standard input or the rest of just-bash's command context, create it with `defineCommand()` from `just-bash`. `experimental.customCommands` accepts the result.

Custom commands run as app code in the app runtime process, outside the virtual filesystem. They aren't available while eve prepares the template.

### Custom filesystem

`experimental.filesystem` builds the filesystem of each live sandbox. eve calls it with:

- `defaultFilesystem`: the session's saved filesystem that holds `/workspace`.
- `justBash`: the loaded `just-bash` module.
- `resolveProjectPath`: resolves a path relative to your app.

Return a `JustBashFilesystem` that keeps `defaultFilesystem` as its base, such as a just-bash `MountableFs`:

```ts
import { defineSandbox } from "eve/sandbox";
import { JustBashSandbox } from "eve/sandbox/just-bash";

export const environment = JustBashSandbox.environment({
  experimental: {
    async filesystem({ defaultFilesystem, justBash, resolveProjectPath }) {
      await defaultFilesystem.mkdir("/reference", { recursive: true });
      return new justBash.MountableFs({
        base: defaultFilesystem,
        mounts: [
          {
            filesystem: new justBash.OverlayFs({
              mountPoint: "/",
              readOnly: true,
              root: resolveProjectPath("reference"),
            }),
            mountPoint: "/reference",
          },
        ],
      });
    },
  },
});
export default defineSandbox(() => environment.open());
```

eve does not call `experimental.filesystem` while it prepares the template, so files under a mount are not part of the template.

See the [sandbox overview](/docs/sandbox) for managed workspace, skills, parent inheritance, and custom providers.

---

For a semantic overview of all documentation, see [/sitemap.md](/sitemap.md)

For an index of all available documentation, see [/llms.txt](/llms.txt)

For agent-facing discovery, including API and MCP surfaces, see [/agents.md](/agents.md)