Agent Security
Run AI coding agents safely with Bkper — sandbox isolation, credential protection, and permission scoping to limit what an agent can access and do.
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.
Ephemeral access tokens
When host-side injection isn’t available, generate a short-lived access token on the host with bkper auth token and pass only that into the container. The token expires after approximately one hour. An attacker who exfiltrates it has a limited window and cannot refresh it — the refresh token stays on the host.
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:
- Sandbox — agent runs inside a DevContainer, Docker Sandbox, or micro-VM with only the project directory mounted
- Credentials — either injected from the host or provided as an ephemeral token
- 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.