Best practices for working with Paver

Use these best practices across your day-to-day work, initial setup, and advanced workflows to keep your environment secure, fast, and predictable. Getting the most out of IBM® Paver comes down to leaning into its operator model. Paver runs in your infrastructure and runs governed operations through your existing command-line interface (CLI), API, and platform tooling.

View as markdown

On this page

Daily usage best practices#

Use precise context triggers, clear guardrails, and persistent memory to speed up your everyday workflows.

Supply instant context with @ mentions#

Instead of copying and pasting multi-megabyte log files or large configuration manifests into the prompt, use the @ trigger to give Paver targeted context:

Local files: Type @/path/to/file.tf to upload the file to your workspace and attach it to the prompt.
Cloud resources: Type @my-vpc-prod to have Paver pull and attach the live resource metadata.
Workspace files: Type @logs.txt to reference a file that is already in your persistent workspace.

Choose the right mode and guardrails for the job#

Control how much execution permission Paver has during a session:

Safe mode (/safe): Use this for discovery, audits, troubleshooting, and planning. Paver can't make changes in your environment, but it can read and write files in the sandbox, such as scripts or Terraform for your plan.
Edit mode (/edit): Use this mode when you are ready to make changes with policy-based human approvals.
Speed up routine low-risk actions: If you find yourself approving routine read or list operations too often, raise the auto-approval threshold:
```
/guard auto-approve-low
```

Plan before you ask Paver to do the work#

For any task that has more than a few steps, ask Paver for a written plan before you ask it to make changes. A plan gives you a chance to correct misunderstandings while they are still easy to fix.

Switch to safe mode and request a plan: In safe mode, Paver can't make changes in your environment, but it can write files in the sandbox. Ask for concrete, ordered steps, and ask Paver to save the plan as a file:
```
Create a plan in plan.md for migrating the staging cluster to the new VPC. List each step, the commands or tools that you will use, the resources that are affected, and how to verify each step.
```
Review the plan: Check that Paver understood your goals, constraints, and environment. Look for missing steps, wrong assumptions, and steps that affect resources that you didn't intend.
Refine the plan: Ask Paver to update the document until it matches what you want. You can attach the file to a prompt with @plan.md.
Run the plan: When you're satisfied, switch to edit mode with /edit and ask Paver to complete the plan. Policy-based approvals still apply to each change.

Use subagents for research tasks#

When a task involves researching or gathering information, such as comparing configurations across several accounts or reviewing many resources, suggest that Paver use subagents. A subagent works on a focused part of the task in its own context and reports a summary back. Subagents can make research faster and reduce the number of tokens that Paver uses, which helps you stay within your usage quota.

Use subagents to research the configuration of my development, staging, and production environments in parallel, then summarize the differences in one table.

Subagents work best for self-contained research. For small lookups or tasks where each step depends on the previous one, Paver can usually do the work directly.

Put memory to work#

Paver stores your operational preferences across conversations so that you don't have to repeat them.

Seed your environment defaults: Tell Paver your project context once in natural language:
```
paver ask "Note that I work on Project Apollo and my default region is us-south"
```
Review and clean up memory: Run /memory to see what Paver has stored about your setup. If you switch to a new project or account, clear outdated entries:
```
/memory clear
```

Setup best practices#

Configure credential handling and sandbox connectivity first so that you can run tasks without interruption.

Use the keyring for secrets#

Do not pass API keys, tokens, or passwords directly in your prompts. Prompts stay in conversation history, but the encrypted keyring injects exported secrets directly into the sandbox as environment variables when commands run.

Set a time-to-live (TTL) on temporary keys: Give sensitive tokens an expiration so that they are removed automatically:
```
paver keyring add MY_TOKEN --ttl 7d
```
Automatically export keys that you use every day: Avoid running /keyring export every time you open a session. Add frequently used keys to the autoExport array in ~/.paver/config.json, and Paver makes them available when your sandbox starts:
```
{
"keyring": {
  "autoExport": [
    "ibmcloud_api_key",
    { "key": "github_token", "as": "GITHUB_TOKEN" }
  ]
}
}
```
Keep secrets at eight characters or more: The Paver automatic redaction engine masks strings in the chat only if they are at least eight characters long.

Set up a custom shell host for your sandbox#

Paver runs commands inside an isolated sandbox.

Connect to private subnets without tunneling: By default, Paver uses a public sandbox. If you need to manage resources in a private VPC or corporate intranet, do not try to build tunnels through the public sandbox. Instead, register a Linux host inside that network as a custom shell:
```
paver shell register <name>
```
Use preinstalled tools: Standard tools such as ibmcloud, kubectl, terraform, and oc are already installed in the sandbox. Paver calls them directly during execution, or you can open the interactive shell yourself:
```
/shell
```

Advanced best practices#

Automate recurring runbooks and keep project assets ready across sessions.

Build custom skills for repeatable workflows#

If you find yourself giving Paver the same five-step instructions every week, turn the procedure into a skill:

Upload your team's domain logic: Package your team's knowledge into a folder and upload it:
```
paver skills upload ./my-skill/
```
Trigger skills on demand: Set user-invokable: true in the skill front matter so you can run it as a custom slash command (such as /my-custom-cleanup).

Treat your workspace as a project folder#

Use ~/.paver/files/ as your persistent project folder. Upload your Terraform modules, shell scripts, and configuration bundles once, and they stay available across all future sessions without repeated uploads.