📖 Situational Tutorial: Sharing External Context Safely

Summary: Learn how to grant sandboxed AI agents read-only access to shared folders (libraries, assets, common components) outside the workspace root without file duplication.

📌 1. The Target Problem

1. The Target Problem

"How do I stop my AI assistant from reading files outside my workspace while still granting it secure access to specific shared folders?"

AI agents need access to shared libraries or monorepo packages to write correct code. If you disable folder restrictions, the agent can access sensitive folders on your machine. If you keep rules tight, the agent cannot access shared resources and hallucinates API signatures.

🚀 2. Step-by-Step Walkthrough

Step 1: Identify and Mount the External Directory

Mount the target external folder to your workspace, giving it a secure, scoped alias:

sprawl mount add /home/user/shared-libraries --alias shared-lib

This adds /home/user/shared-libraries to sprawl_manifest.yml under the @shared-lib prefix.

Step 2: Synchronize Settings and Schemas

Recompile your rules and reload the local MCP schemas to register the new mount:

sprawl sync

Step 3: Generate Local Binding Configs

Refresh your active IDE bindings to update settings files:

sprawl bind

Step 4: Tell Your Agent How to Use the Mount

In your project prompts or rules manifest, tell the agent that external libraries are accessible under the @shared-lib/ path.

  • Example Prompt: Please review the authentication module at @shared-lib/auth/jwt.ts and implement a client handler in my project.

Step 5: Call Your Agent

Submit the prompt to Claude Code, Cursor, or your IDE assistant. The agent reads @shared-lib/auth/jwt.ts via the Sprawl MCP filesystem server, but is blocked if it attempts to navigate to /home/user/.ssh/ or /etc/passwd.

🔍 Verification & Diagnostics

List all active, configured directory mounts for your project sandbox:

sprawl mount list

🩺 Troubleshooting

  • Agent fails to locate files in the mounted directory
  • Cause: The agent is using absolute paths instead of the registered @alias prefix.
  • Resolution: Explicitly instruct the agent in your prompts or .cursorrules overrides to prepend @<alias>/ when referencing mounted external folders.

🔗 Related Resources & Tutorials