Agent Security

AI coding agents are powerful but run with your permissions. A misconfigured agent can read credentials, overwrite files, or modify live financial data.

Three layers of protection keep your Bkper development safe:

Sandbox isolation

The most effective way to limit an agent is to run it inside a sandbox — a container, micro-VM, or OS-level boundary that restricts what it can reach.

Most agents support a “yolo” or auto-approve mode that skips permission prompts. The per-command approval model sounds safe but creates friction that kills productivity — agents frequently need to run builds, tests, and CLI commands. Pi Agent (and therefore Bkper Agent) runs in yolo mode by default.

Running in a sandbox makes this safe: full autonomy inside a restricted boundary.

Built-in sandboxing

Some agents sandbox themselves without a container. Claude Code and Codex both use OS-level primitives (Seatbelt on macOS, bubblewrap on Linux) to enforce filesystem and network isolation. If you use either, enable their sandbox mode before working with real data.

Container-based sandboxing

For agents without built-in sandboxing — including Pi Agent and Bkper Agent — use a container. We use Docker with DevContainers and DevPod to get reproducible, isolated environments that work the same way locally and in the cloud. Claude Code also publishes a reference devcontainer designed for autonomous operation with network allowlisting.

Other sandbox tools worth knowing about:

• Docker Sandboxes — microVM-based sandboxes built for coding agents, with host-side credential injection
• Gondolin — lightweight micro-VMs with programmable network egress and secret injection
• Podman — rootless, daemonless Docker alternative

Credential protection

Even inside a sandbox, the agent can access any credentials present in that environment. The Bkper CLI stores OAuth credentials (including a refresh token) at ~/.config/bkper/.bkper-credentials.json. If the agent can read that file, it can make API calls as you.

Host-side credential injection

The most secure option. Your credentials never enter the sandbox — an HTTP proxy on the host intercepts outbound API requests and injects authentication headers before forwarding them. Docker Sandboxes and Gondolin implement this pattern.

This works well with the Bkper CLI because only bkper auth login starts an interactive browser login. Regular CLI commands can proceed without local credentials and let the proxy add authentication.

Login inside the sandbox, then logout cleanly

This is the simplest practical workflow for many teams. Authenticate inside the sandbox with a secondary low-permission account:

bkper auth login

When you are done, revoke the refresh token and remove the local credentials:

bkper auth logout

bkper auth logout does both:

• revokes the stored refresh token remotely when possible
• clears local credentials from disk

If remote revocation fails, the CLI still clears local credentials and warns that remote cleanup may need manual follow-up.

Permission scoping

The Bkper CLI authenticates as the user who ran bkper auth login. If that user is the book owner, the agent has owner-level access — it can delete accounts, change sharing settings, and modify lock dates.

Use a secondary account with limited permissions instead. Log into the CLI with a different Google account (for example, a personal Gmail), then share the target book with that account at the appropriate level:

Permission	What the agent can do	Good for
View Only	Read accounts, transactions, and balances	Read-only scripts, reporting, analysis
Record Only	Create and delete drafts	Automated data entry with human review
Record & View	Record drafts, post transactions, view data	Most development and testing workflows
Editor	Full data management (accounts, groups, transactions)	Building apps that manage book structure

Avoid granting Owner permission to the agent’s account. Owner access allows sharing changes, closing-date modifications, and other irreversible operations that should remain under direct human control.

For the full permissions matrix, see Book Sharing — Permissions.

Combining layers

A typical secure setup:

1. Sandbox — agent runs inside a DevContainer, Docker Sandbox, or micro-VM with only the project directory mounted
2. Credentials — either injected from the host, or authenticated inside the sandbox and explicitly revoked with bkper auth logout when work is done
3. Permissions — CLI authenticated as a secondary account with Record & View access

No single layer is bulletproof, but together they limit exposure to a narrow, time-bound, permission-scoped window.