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. For managing credentials available inside the shell, see Storing your secrets in the keyring.

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:

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 for details. Files in your sandbox workspace (managed with paver files) are available at ~/.paver/files.

Opening a shell#

You can easily open a shell from the web UI or CLI.

From inside a chat#

/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#

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:

paver shell --continue          # Attach to the most recent conversation's sandbox
paver shell -c <conversation-id>  # 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.

Listing hosts#

paver shell list

Available shell hosts:

✓ default ← active

Tip: Use 'paver shell register <name>' to register a new host

Shell host status indicators:

Showing the active host#

paver shell current

Selected shell host: default

Registering a new host#

Register a machine or container as a shell host:

paver shell register <name>

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:

paver shell register my-server

✓ Shell host 'my-server' registered successfully!

Run this on your remote host:

script_url='https://<paver-server>/register-shell.sh'
host='my-server'
server_url='https://<paver-server>'
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.

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#

paver shell use <name>

Switches all subsequent shell sessions to the named host. The host must be online.

paver shell use my-server

✓ Using shell host: my-server

To return to the Paver-managed default:

paver shell use default

Removing a host#

paver shell remove <name>

Removes the host from your account and closes its active WebSocket connection. You cannot remove the default host.

paver shell remove my-server

✓ Removed shell host: my-server

Refer to the IBM Paver CLI command reference and IBM Paver chat commands reference 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 <name>
2. Re-register it: paver shell register <name>
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.