Quickstart: govern a coding agent

Prepare a test environment

You need a Kastra workspace with custom policy and approval access, an administrator to create the policy, an authorized approver, and Claude Code installed. Install Edge and the operator CLI. The commands below use a POSIX shell on macOS or Linux; platform support covers other combinations.

kastra auth login
kastra env create docs-hooks
kastra-edge config show
kastra-edge config set default_environment docs-hooks
kastra-edge install-claude --dry-run
kastra-edge install-claude
kastra-edge doctor

Record your previous default_environment before changing it. Login is shared by the two CLIs. Use a fresh environment: if docs-hooks already exists, choose a new name and update the policy file’s metadata.environment. In the console, select this environment and confirm enforcement is enabled rather than shadow mode. Restart Claude Code so it reloads the hook and configuration.

Install the example policy

Download and inspect coding-agent.kastra. Its two rules match x-kastra-attr-tool = Bash and a specific marker in x-kastra-attr-tool-input: kastra-docs-deny blocks, and kastra-docs-hold requests approval. Other actions default to ALLOW. Approval expires after five minutes with a denial.

curl --fail --output coding-agent.kastra https://docs.kastra.ai/examples/coding-agent.kastra
kastra policy validate coding-agent.kastra
kastra policy add coding-agent.kastra --activate

Save the new policy ID printed by the command. Check the active policy in the console before proceeding. These example rules demonstrate control flow; they are not a general shell-security policy.

Prove an allow

In Claude Code, ask: Use the Bash tool to run exactly printf 'kastra-docs-allow\n'. Do not substitute another tool.

The tool output should contain kastra-docs-allow. Find its event in Activity under docs-hooks, with source claude_code and tool Bash. Confirm ALLOW and the expected active policy. A sentence generated by the assistant is not the tool result.

Prove a block

Ask: Use the Bash tool to run exactly printf 'kastra-docs-deny\n'. If policy blocks it, stop; do not retry with another tool.

Expect a policy denial before Bash runs. Activity should identify the matching documentation rule and DENY. The marker may appear in the denied request preview; it must not appear as successful command output.

Prove approval

Ask the same way for printf 'kastra-docs-hold\n'. While it waits, open Approvals in the console, inspect the exact command and environment, and approve it. Expect the waiting Bash action to run once. Repeat as a new tool call and deny that checkpoint; it must not execute.

Resolve promptly: the host’s wait budget and checkpoint expiry are separate. If the client stops waiting, inspect the checkpoint and follow approval recovery; do not treat a timeout as permission.

Check the evidence and clean up

kastra evidence list --env docs-hooks --limit 20
kastra policy deactivate POLICY_ID

Replace POLICY_ID with the ID created for this walkthrough. Confirm the three outcomes and the approval resolution in the console. Restore the previous Edge environment with kastra-edge config set default_environment PREVIOUS_NAME, then restart Claude Code. Keep the inactive example policy and its evidence for review, or remove that example policy through the console when no longer needed.

If you installed the hook only for this exercise, use kastra-edge uninstall-claude --dry-run, then kastra-edge uninstall-claude and restart the client. If events are missing or actions unexpectedly proceed, use Edge troubleshooting before adding more rules.