# Using the Paver interactive shell Use the `paver shell` command to open an interactive terminal in your IBM® Paver sandbox, with `ibmcloud`, `kubectl`, `terraform`, `helm`, and `oc` preinstalled. You can also register custom shell hosts to reach private network resources. The sandbox is the same environment IBM Paver uses when it executes commands on your behalf. It's also accessible by using the `/shell` slash command in `paver chat` or from the web UI. The shell and chat interfaces are complementary. Chat handles intent-driven orchestration. The shell is for direct execution for workflows that simply aren't possible through the agent, like TTY-dependent tools, raw file system operations, and reaching private network endpoints. ## When to use the shell Using the shell over chat is helpful when: - **You're iterating rapidly.** Tight feedback loops on piped commands (`ibmcloud ... | jq ... | grep ...`) are faster with bash history and immediate execution than round-tripping through the agent. - **You're authoring or testing scripts.** Writing and executing multi-line bash or Python directly is more efficient than delegating to the agent and reviewing its output. - **Your tools require a TTY.** Some tools require an interactive terminal or raw stdin/stdout, and the shell gives you a direct pseudo-terminal (pty) session. - **You're doing bulk file system work.** Manipulating Terraform configs, Kubernetes manifests, or workspace files is faster with standard UNIX tools than natural language instructions. Using an interactive chat session is helpful when the task requires multi-step orchestration across services where Paver's reasoning and tool selection add real value. Also when you want to review and approve actions before they execute rather than driving them yourself. There are also some advantages of using the interactive shell over a local terminal: - **No toolchain management**: The `ibmcloud`, `kubectl`, `terraform`, `helm`, `oc` tools and standard UNIX utilities are preinstalled in the sandbox image, at the versions available when the image was built. - **Credential isolation**: Paver never writes keyring secrets to your shell history or local disk. When exported as environment variables, they are accessible to any process running in that session. - **Persistent file workspace**: Files in `~/.paver/files` persist across sessions and are shared across all your conversations. Other sandbox state (installed packages, working directory) is isolated per conversation. - **Private network access**: You can register a custom shell host on a jump server or bastion inside a private VPC to reach endpoints that aren't publicly routable. - **Reproducible environment**: The sandbox is a standardized container image, so environment drift across team members is a nonissue. For file management in the sandbox, see [Sharing files with Paver](https://paver.ibm.com/docs/core-concepts/files.md). For managing credentials available inside the shell, see [Storing your secrets in the keyring](https://paver.ibm.com/docs/core-concepts/keyring.md). ## Sandbox contents Every shell session runs inside a `paver-sandbox` container, which is the same image Paver uses when it executes bash commands during a conversation. It includes: | Tool | Purpose | | ------------------------- | -------------------------------------------- | | `ibmcloud` CLI + plug-ins | IBM Cloud® resource management | | `kubectl` | Kubernetes cluster management | | `helm` | Kubernetes package manager | | `terraform` | Infrastructure as Code | | `oc` | Red Hat OpenShift CLI | | Node.js | Scripting and automation | | Python 3.12 | Scripting and automation | | Standard UNIX tools | `curl`, `jq`, `grep`, `awk`, `sed`, and more | Keyring secrets are available as environment variables in the shell when exported. You can export them manually with `/keyring export` in `paver chat`, or configure `keyring.autoExport` to inject them automatically at the start of every session. See [Storing your secrets in the keyring](https://paver.ibm.com/docs/core-concepts/keyring.md) for details. Files in your sandbox workspace (managed with `paver files`) are available at `~/.paver/files`. > **One sandbox per conversation** > > Each conversation gets its own isolated sandbox container. Changes that you make > in a shell session, such as installed packages, working directory, and files outside > `~/.paver/files`, are visible to Paver in the same conversation but do not > affect other conversations. Files in `~/.paver/files` are shared across all > your conversations. ## Opening a shell You can easily open a shell from the web UI or CLI. ### From inside a chat ```text /shell ``` Suspends the interactive chat and opens an interactive shell session in the same conversation's sandbox, then returns to the chat when you exit. The conversation context is preserved. ### From the CLI ```text paver shell ``` This creates a new conversation, starts the corresponding sandbox container, and opens a pty session inside it. Your terminal enters raw mode, and you interact with the bash shell directly. To attach to the sandbox for a specific or recent conversation: ```text paver shell --continue # Attach to the most recent conversation's sandbox paver shell -c # Attach to a specific conversation's sandbox ``` ## Registering custom shell hosts Shell sessions run in Paver's managed sandbox infrastructure by default (the `default` host). You can register your own machines or containers as **shell hosts** to route sessions to your own environment instead. > **When to use a custom shell host** > > Use a custom shell host when you need access to private network resources, > custom tooling not in the default sandbox image, or persistent container > state across sessions. The default host is sufficient for most users. ### Listing hosts ```text paver shell list ``` ```text Available shell hosts: ✓ default ← active Tip: Use 'paver shell register ' to register a new host ``` Shell host status indicators: | Icon | Meaning | | ---- | ------------------------------------------------------------------- | | `✓` | Online: The host is connected and ready. | | `⏳` | Pending: The host is registered but the agent is not yet connected. | | `✗` | Offline: The host was registered but is currently disconnected. | ### Showing the active host ```text paver shell current ``` ```text Selected shell host: default ``` ### Registering a new host Register a machine or container as a shell host: ```text paver shell register ``` Hostnames can contain letters, numbers, underscores, and hyphens (maximum 64 characters). The name `default` is reserved. After registration, the server returns a one-time setup command to run on the remote host: ```text paver shell register my-server ``` ```text ✓ Shell host 'my-server' registered successfully! Run this on your remote host: script_url='https:///register-shell.sh' host='my-server' server_url='https://' token='eyJ2IjoxL...' hid='90d60a9b4b09bbad50f60417b0adeee0' arg5='icr.io/finn-open/paver-shell:latest' arg6='icr.io/finn-open/paver-sandbox:latest' curl -fsSL "$script_url" | sh -s -- "$host" "$server_url" "$token" "$hid" "$arg5" "$arg6" Token expires in: 24 hours ``` Copy the full block, including the multi-line variable assignments, and paste it on the target machine. The setup script pulls the `paver-shell` image and starts the agent container. When the agent connects, the host transitions from `pending` to `online`. > **Token expires in 24 hours** > > The registration token is single-use and expires after 24 hours. If you do > not run the setup command in time, remove the host and register again. When > the agent has connected, it maintains the connection independently. The > token expiry does not affect a running host. The `paver-shell` agent container requires Podman (or Docker) with the `--privileged` flag to run nested sandbox containers. The setup script handles this automatically. Ensure that Podman is installed and the container runtime socket is accessible on the target machine. ### Switching the active host ```text paver shell use ``` Switches all subsequent shell sessions to the named host. The host must be `online`. ```text paver shell use my-server ✓ Using shell host: my-server ``` To return to the Paver-managed default: ```text paver shell use default ``` ### Removing a host ```text paver shell remove ``` Removes the host from your account and closes its active WebSocket connection. You cannot remove the `default` host. ```text paver shell remove my-server ✓ Removed shell host: my-server ``` Refer to the [IBM Paver CLI command reference](https://paver.ibm.com/docs/cli-reference.md) and [IBM Paver chat commands reference](https://paver.ibm.com/docs/tui-reference.md) for full usage details. ## Troubleshooting working in the shell ### What does shell connection could not be restored mean? If your network drops briefly, the CLI reconnects automatically. The server keeps the shell process alive for up to 60 seconds after a disconnect, so your working directory, environment variables, and running processes survive short interruptions without any action on your part. During reconnect, the terminal stays in raw mode and any input you type is buffered (up to 64 KiB). Input is flushed to the shell as soon as the connection is restored. If reconnection fails after 8 attempts, the CLI exits with the error `Shell connection could not be restored. Start /shell again to reconnect.`. Run `/shell` or `paver shell` to start a new session. ### Why does a host require re-setup before it can be used? This error occurs when a registered host is running an older agent version that is no longer compatible. The agent must be replaced. To upgrade: 1. Remove the host: `paver shell remove ` 2. Re-register it: `paver shell register ` 3. Copy the setup command from the output and run it on the remote host. The setup script replaces the existing agent container with the current version. When the agent reconnects, the host returns to `online` status.