> ## Documentation Index
> Fetch the complete documentation index at: https://agdiai-597e782f.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# OpenShell

# OpenShell

OpenShell is a managed sandbox backend for Agdi. Instead of running Docker
containers locally, Agdi delegates sandbox lifecycle to the `openshell` CLI,
which provisions remote environments with SSH-based command execution.

The OpenShell plugin reuses the same core SSH transport and remote filesystem
bridge as the generic [SSH backend](https://agdiai-597e782f.mintlify.site/gateway/sandboxing.md#ssh-backend). It adds
OpenShell-specific lifecycle (`sandbox create/get/delete`, `sandbox ssh-config`)
and an optional `mirror` workspace mode.

## Prerequisites

* The `openshell` CLI installed and on `PATH` (or set a custom path via
  `plugins.entries.openshell.config.command`)
* An OpenShell account with sandbox access
* Agdi Gateway running on the host

## Quick start

1. Enable the plugin and set the sandbox backend:

```json5 theme={"theme":{"light":"min-light","dark":"min-dark"}}
{
  agents: {
    defaults: {
      sandbox: {
        mode: "all",
        backend: "openshell",
        scope: "session",
        workspaceAccess: "rw",
      },
    },
  },
  plugins: {
    entries: {
      openshell: {
        enabled: true,
        config: {
          from: "agdi",
          mode: "remote",
        },
      },
    },
  },
}
```

2. Restart the Gateway. On the next agent turn, Agdi creates an OpenShell
   sandbox and routes tool execution through it.

3. Verify:

```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
agdi sandbox list
agdi sandbox explain
```

## Workspace modes

This is the most important decision when using OpenShell.

### `mirror`

Use `plugins.entries.openshell.config.mode: "mirror"` when you want the **local
workspace to stay canonical**.

Behavior:

* Before `exec`, Agdi syncs the local workspace into the OpenShell sandbox.
* After `exec`, Agdi syncs the remote workspace back to the local workspace.
* File tools still operate through the sandbox bridge, but the local workspace
  remains the source of truth between turns.

Best for:

* You edit files locally outside Agdi and want those changes visible in the
  sandbox automatically.
* You want the OpenShell sandbox to behave as much like the Docker backend as
  possible.
* You want the host workspace to reflect sandbox writes after each exec turn.

Tradeoff: extra sync cost before and after each exec.

### `remote`

Use `plugins.entries.openshell.config.mode: "remote"` when you want the
**OpenShell workspace to become canonical**.

Behavior:

* When the sandbox is first created, Agdi seeds the remote workspace from
  the local workspace once.
* After that, `exec`, `read`, `write`, `edit`, and `apply_patch` operate
  directly against the remote OpenShell workspace.
* Agdi does **not** sync remote changes back into the local workspace.
* Prompt-time media reads still work because file and media tools read through
  the sandbox bridge.

Best for:

* The sandbox should live primarily on the remote side.
* You want lower per-turn sync overhead.
* You do not want host-local edits to silently overwrite remote sandbox state.

Important: if you edit files on the host outside Agdi after the initial seed,
the remote sandbox does **not** see those changes. Use
`agdi sandbox recreate` to re-seed.

### Choosing a mode

| | `mirror` | `remote` |
| - | - | - |
| **Canonical workspace** | Local host | Remote OpenShell |
| **Sync direction** | Bidirectional (each exec) | One-time seed |
| **Per-turn overhead** | Higher (upload + download) | Lower (direct remote ops) |
| **Local edits visible?** | Yes, on next exec | No, until recreate |
| **Best for** | Development workflows | Long-running agents, CI |

## Configuration reference

All OpenShell config lives under `plugins.entries.openshell.config`:

| Key | Type | Default | Description |
| - | - | - | - |
| `mode` | `"mirror"` or `"remote"` | `"mirror"` | Workspace sync mode |
| `command` | `string` | `"openshell"` | Path or name of the `openshell` CLI |
| `from` | `string` | `"agdi"` | Sandbox source for first-time create |
| `gateway` | `string` | — | OpenShell gateway name (`--gateway`) |
| `gatewayEndpoint` | `string` | — | OpenShell gateway endpoint URL (`--gateway-endpoint`) |
| `policy` | `string` | — | OpenShell policy ID for sandbox creation |
| `providers` | `string[]` | `[]` | Provider names to attach when sandbox is created |
| `gpu` | `boolean` | `false` | Request GPU resources |
| `autoProviders` | `boolean` | `true` | Pass `--auto-providers` during sandbox create |
| `remoteWorkspaceDir` | `string` | `"/sandbox"` | Primary writable workspace inside the sandbox |
| `remoteAgentWorkspaceDir` | `string` | `"/agent"` | Agent workspace mount path (for read-only access) |
| `timeoutSeconds` | `number` | `120` | Timeout for `openshell` CLI operations |

Sandbox-level settings (`mode`, `scope`, `workspaceAccess`) are configured under
`agents.defaults.sandbox` as with any backend. See
[Sandboxing](https://agdiai-597e782f.mintlify.site/gateway/sandboxing.md) for the full matrix.

## Examples

### Minimal remote setup

```json5 theme={"theme":{"light":"min-light","dark":"min-dark"}}
{
  agents: {
    defaults: {
      sandbox: {
        mode: "all",
        backend: "openshell",
      },
    },
  },
  plugins: {
    entries: {
      openshell: {
        enabled: true,
        config: {
          from: "agdi",
          mode: "remote",
        },
      },
    },
  },
}
```

### Mirror mode with GPU

```json5 theme={"theme":{"light":"min-light","dark":"min-dark"}}
{
  agents: {
    defaults: {
      sandbox: {
        mode: "all",
        backend: "openshell",
        scope: "agent",
        workspaceAccess: "rw",
      },
    },
  },
  plugins: {
    entries: {
      openshell: {
        enabled: true,
        config: {
          from: "agdi",
          mode: "mirror",
          gpu: true,
          providers: ["openai"],
          timeoutSeconds: 180,
        },
      },
    },
  },
}
```

### Per-agent OpenShell with custom gateway

```json5 theme={"theme":{"light":"min-light","dark":"min-dark"}}
{
  agents: {
    defaults: {
      sandbox: { mode: "off" },
    },
    list: [
      {
        id: "researcher",
        sandbox: {
          mode: "all",
          backend: "openshell",
          scope: "agent",
          workspaceAccess: "rw",
        },
      },
    ],
  },
  plugins: {
    entries: {
      openshell: {
        enabled: true,
        config: {
          from: "agdi",
          mode: "remote",
          gateway: "lab",
          gatewayEndpoint: "https://lab.example",
          policy: "strict",
        },
      },
    },
  },
}
```

## Lifecycle management

OpenShell sandboxes are managed through the normal sandbox CLI:

```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
# List all sandbox runtimes (Docker + OpenShell)
agdi sandbox list

# Inspect effective policy
agdi sandbox explain

# Recreate (deletes remote workspace, re-seeds on next use)
agdi sandbox recreate --all
```

For `remote` mode, **recreate is especially important**: it deletes the canonical
remote workspace for that scope. The next use seeds a fresh remote workspace from
the local workspace.

For `mirror` mode, recreate mainly resets the remote execution environment because
the local workspace remains canonical.

### When to recreate

Recreate after changing any of these:

* `agents.defaults.sandbox.backend`
* `plugins.entries.openshell.config.from`
* `plugins.entries.openshell.config.mode`
* `plugins.entries.openshell.config.policy`

```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
agdi sandbox recreate --all
```

## Current limitations

* Sandbox browser is not supported on the OpenShell backend.
* `sandbox.docker.binds` does not apply to OpenShell.
* Docker-specific runtime knobs under `sandbox.docker.*` apply only to the Docker
  backend.

## How it works

1. Agdi calls `openshell sandbox create` (with `--from`, `--gateway`,
   `--policy`, `--providers`, `--gpu` flags as configured).
2. Agdi calls `openshell sandbox ssh-config <name>` to get SSH connection
   details for the sandbox.
3. Core writes the SSH config to a temp file and opens an SSH session using the
   same remote filesystem bridge as the generic SSH backend.
4. In `mirror` mode: sync local to remote before exec, run, sync back after exec.
5. In `remote` mode: seed once on create, then operate directly on the remote
   workspace.

## See also

* [Sandboxing](https://agdiai-597e782f.mintlify.site/gateway/sandboxing.md) -- modes, scopes, and backend comparison
* [Sandbox vs Tool Policy vs Elevated](https://agdiai-597e782f.mintlify.site/gateway/sandbox-vs-tool-policy-vs-elevated.md) -- debugging blocked tools
* [Multi-Agent Sandbox and Tools](https://agdiai-597e782f.mintlify.site/tools/multi-agent-sandbox-tools.md) -- per-agent overrides
* [Sandbox CLI](https://agdiai-597e782f.mintlify.site/cli/sandbox.md) -- `agdi sandbox` commands


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.