# bonsai3 tester guide Use this guide to sign in, connect an agent to a project, and check that bonsai3 returns the expected security policies. Most of the walkthrough can be done from the browser and an MCP client. ## 1. Sign in and join a project 1. Open `/login` on your bonsai3 server. On the LAN preview, use `http://192.168.1.121:4400/login`. 2. Enter your **organization name**, email, and password, or select **Sign in with SSO** to see your organization's providers. Ask the person running your test for an account if you don't have one. On the preview, the organization name is `bonsai3`. 3. If you're joining with a new account, select **Sign up โ†’ Request to join**. Your organization must have self-registration and member password login enabled to send a setup email. Follow the email link to set your password. Some organizations also allow joining through SSO. 4. Open **My agents**. Look under **Assigned projects** for `healthcare_security` on the preview. If it's under **Joinable projects**, select **Join project**. If a project appears in neither list, ask an admin to add you; private projects cannot be joined from the member dashboard. ## 2. Register an agent and connect MCP 1. From **My agents**, select **Register agent**. Give it a name such as `Healthcare smoke test`, select `healthcare_security`, and create the token. 2. Copy the token when it's shown. It won't be displayed again. This token selects the project on every lookup. 3. In an MCP client that supports Streamable HTTP, add the server URL and configure bearer authentication. Use the `/mcp` path on the same server you signed into. On the LAN preview, the URL is `http://192.168.1.121:4400/mcp`. For Codex, supply the token in the `POLICY_GATE_MCP_TOKEN` environment variable before launching Codex. Add this to `config.toml`, using your deployment URL if it differs: ```toml [mcp_servers.bonsai3] url = "http://192.168.1.121:4400/mcp" bearer_token_env_var = "POLICY_GATE_MCP_TOKEN" ``` Restart or reconnect the client. In Codex, `/mcp` should list the `security_context` tool. For other clients or hook integrations, see the [installation guide](../installation/README.md) (`/installation` on the server). ## 3. Exercise a policy lookup Ask the agent to call `security_context` with one of these exact intents. These examples match the policies seeded in the preview's `healthcare_security` project. | Intent | Expected result | | --- | --- | | `Build a patient record viewer` | `steer`; **Healthcare: Patient record access** appears in `matched_policies`. | | `Implement PHI logging for a patient portal` | `steer`; **Healthcare: PHI-safe logging and telemetry** appears. | | `Build a patient data export` | `steer`; **Healthcare: Secure patient data exports** appears. | | `Create patient fixtures` | `steer`; **Healthcare: Synthetic data in tests** appears. | | `Build credit card payment processing` | No PCI DSS policy matches unless an admin explicitly attached one to this project. | The response includes the `decision`, `matched_policies`, any `guidance`, and an `audit_id`. More than one policy can match. The MCP instructions ask the agent to show **๐ŸŒฑ Secured by bonsai3** after its first successful lookup in a session; check the actual tool result if your client doesn't show the banner. MCP returns guidance and decisions when called. To automatically stop another action from executing, the agent harness needs an enforcement hook. You can test the same lookup without an agent client. Set `POLICY_GATE_MCP_TOKEN` to your project token in your terminal, then run: ```sh curl -fsS http://192.168.1.121:4400/mcp \ -H "Authorization: Bearer $POLICY_GATE_MCP_TOKEN" \ -H 'Content-Type: application/json' \ -H 'Accept: application/json, text/event-stream' \ -d '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"security_context","arguments":{"intent":"Build a patient record viewer"}}}' ``` The returned policy result is JSON inside `result.content[0].text`. ## 4. Check the admin workflows Use an organization admin account for these checks. A delegated project admin can open **My agents โ†’ Manage project** to manage their own project's members, settings, and attached policies. 1. **Create and attach a policy.** In **Policies โ†’ New policy**, choose **Block**, enter `bonsai3-test-block` as the condition, and select **Tasks**. Save it, then open **Projects โ†’ Manage project โ†’ Project settings**. Select the new policy under **Attached custom policies** and save the settings. Test the intent `Check bonsai3-test-block`; the result should be `block`. On a separate project without that policy, the same intent should not match your rule. 2. **Edit and publish.** Change the rule in **Policies โ†’ Edit** and save the draft. Confirm a lookup still uses the published version. Publish the draft and repeat the lookup to check that it now uses the new version. Delete the sample when finished; it stops applying, and its history moves to **Deleted policies**. 3. **Choose built-ins.** In **Manage project โ†’ Project settings**, review **Built-in secure development policies** and **PCI DSS policies ยท opt-in**. In a test project, check one PCI DSS rule and save. Look up `Build credit card payment processing`, confirm the rule matches, then uncheck it and repeat the lookup. The change applies only to that project. 4. **Review the decision.** Open **Decision activity** to check the outcome and project. If a lookup needs investigating, keep its `audit_id` from the tool response. 5. **Check project access.** In **Manage project**, search the member list and try **Add** and **Remove**. Public-to-organization projects show a **Join project** option to members; private projects require assignment. An organization admin can choose **Make project admin** to delegate project management. In **Projects โ†’ Change default**, changing the default controls which project future users join automatically; it does not move existing members. 6. **Test revocation.** In **My agents**, revoke the test token and retry the API request. It should return HTTP 401. Removing a member from a project also revokes their tokens for that project. ## If something doesn't work - **Can't sign in:** Check the server address, organization name, and account. For signup, confirm your admin has enabled the relevant joining method. - **Can't register an agent:** Check that the project appears under **Assigned projects**. Join it if available, or ask an admin to add you. - **HTTP 401 or missing MCP tool:** Check that the URL ends in `/mcp`, that your client uses Streamable HTTP, and that the project token is present in the client's environment and hasn't been revoked. Restart the client after changing its configuration. - **Expected policy didn't match:** Verify that the policy is published and attached to the token's project. For this MCP tool, enable **Tasks** on custom policies. The preview uses case-insensitive substring matching, so try the exact example intent first. When reporting an issue, include the preview URL, organization and project names, your role, steps to reproduce, expected and actual results, and any `audit_id`. Leave out passwords, tokens, and real patient data.