---
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()` provides a shell and filesystem without starting a container or VM.

```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 prepare and persist its virtual filesystem. It cannot use OCI images or Dockerfiles, does not run native processes, and provides no network isolation. The session does not expose `setNetworkPolicy()`.

## Automatic installation

When an environment uses just-bash during `eve dev`, eve installs the package into your application if it is missing, unless you set `autoInstall: false` in the environment options. `DefaultSandbox` selects only one provider, but another environment, such as local self-modification, can use just-bash independently. Other environments require you to install the package yourself.

For pnpm projects, automatic installation adds `@mongodb-js/zstd` and `node-liblzma` to `ignoredOptionalDependencies` in the owning `pnpm-workspace.yaml` when they have no explicit package policy. These optional native codecs are not needed for basic shell and filesystem operations. Commands that require those codecs may be unavailable without them. eve preserves existing package-specific build decisions and does not automatically approve build scripts.

## Custom commands

`customCommands` registers your own functions as commands in each live just-bash shell, where they work in pipelines and redirections. Write a `JustBashCommand` from `eve/sandbox/just-bash`:

```ts
import { defineSandbox } from "eve/sandbox";
import { JustBashSandbox, type JustBashCommand } 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({ 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`; `customCommands` accepts the result.

Custom commands run as application code in the app runtime process, outside the virtual filesystem. They are not available while eve prepares the template.

## Custom filesystem

`filesystem` composes the filesystem of each live sandbox. eve calls it with `defaultFilesystem`, the session's durable filesystem that holds `/workspace`, and `justBash`, the loaded `just-bash` module. 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({
  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 `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)