📖 Situational Tutorial: Start a New Workspace from Scratch

Summary: Learn how to scaffold, provision, configure, and launch a secure development sandbox for your AI coding agents in under 2 minutes.

📌 1. The Target Problem

1. The Target Problem

"How do I spin up a new sandboxed project and configure my AI editor agent to operate securely without manual configuration?"

When starting a new project, developers manually copying configurations, rules, and model settings across files will introduce configuration gaps. If the AI agent is not isolated from day one, it can exfiltrate credentials, modify local files outside the project, or leak private intellectual property.

🚀 2. Step-by-Step Walkthrough

Step 1: Scaffold the Workspace

Initialize a clean project directory using the Sprawl workspace engine. This registers the workspace globally and sets up the standard folder structure:

sprawl create secure-app
cd secure-app

Step 2: Synchronize and Provision the Sandbox

Pull down your team's global DNA registry baseline, automatically provision a clean local python virtual environment for skills execution, and compile your initial baseline rules context:

sprawl sync

This command creates the .agents/ configuration directory and sets up the isolated .agents/.venv virtual environment.

Step 3: Inject Specific Registry Rules

Add your team's code formatting and development style guidelines from your organization's DNA registry directly into your project's manifest:

sprawl add rules/coding-standards

Sprawl adds this rule module to sprawl_manifest.yml and triggers an automatic sync to rebuild your compiled rules context.

Step 4: Mount Shared External Context (Optional)

If your agent needs to read files from a shared components folder outside your workspace root, mount the directory safely to grant scoped read-only access:

sprawl mount add /home/user/shared-components --alias components

This binds /home/user/shared-components to @components/ inside the local Sprawl configuration without copy-pasting code.

Step 5: Compile IDE and Agent Bindings

Generate the native configuration files for all active editors (Cursor, VS Code, Windsurf) and agents (Antigravity CLI, Claude Desktop):

sprawl bind

Choose VS Code/Cursor and Claude Desktop from the interactive menu. Sprawl compiles and links the context-optimized AGENTS.md and mcp_config.json files automatically.

Step 6: Call Your Agent

Now, launch your editor or runtime client in the project directory:

  • VS Code / Cursor: Open the directory:
    code .

Your editor agent (Cursor or Copilot) will automatically load the compiled .cursorrules (linked to AGENTS.md).

  • Claude Desktop / Stdio MCP: Launch Claude Desktop. The loaded Sprawl MCP server handles all filesystem requests, allowing the model to interact safely.
  • Google Antigravity SDK CLI: Run tasks natively within your shell:
    sprawl shell

This drops you into the active sandbox environment where your agent code runs in isolation.

🔍 Verification & Diagnostics

To verify that your sandbox is healthy, active, and fully mapped to your team's DNA:

sprawl status

🩺 Troubleshooting

  • Virtual environment provisioning fails
  • Cause: Your machine is missing python3 virtualenv binaries.
  • Resolution: Run sudo apt-get install python3-venv on Ubuntu/Debian, or equivalent for your OS package manager.

🔗 Related Resources & Tutorials