How to Set Up a Dedicated Workspace for the Devin Coding Agent

Pointing the Devin coding agent at an unconstrained repository or local file system invites catastrophic file modifications or unintended directory traversal. Bounding the agent inside an OS-level sandbox protects system integrity, but persisting the resulting code files requires a shared workspace that agents and human developers can access concurrently.

To understand why a sandbox is necessary, it is helpful to distinguish between standard coding assistants and autonomous coding agents. A coding assistant typically operates within an integrated development environment as an autocomplete engine or a chat panel. It suggests code completions and answers questions, but it relies on a human developer to write files, execute terminal commands, and run tests. A coding agent is an autonomous AI system equipped with sandboxed execution environments, terminals, and browsers to perform software engineering tasks like bug fixing and feature development. Because the agent initiates actions, compiles code, runs tests, and interacts with third-party APIs without constant human intervention, its access must be bounded. Without isolation, a malicious script or an unexpected logical loop in the agent's code could compromise the host machine's environment.

On Linux and WSL 2 systems, Devin uses Bubblewrap and socat to create a secure, unprivileged container for process execution. Bubblewrap is a sandboxing tool that uses Linux namespaces to restrict process capabilities. The namespaces used include:

• User Namespaces: Map container root privileges to an unprivileged user on the host machine, preventing unauthorized root escalation attacks.
• Mount Namespaces: Isolate the filesystem mount points, ensuring the containerized agent only views designated folder paths.
• PID Namespaces: Isolate the process ID space, preventing Devin from viewing or modifying active processes running on the host system.
• Network Namespaces: Restrict network interfaces, ensuring the agent only connects to authorized domains.

When you run Devin with the global --sandbox flag, the agent is restricted to an isolated filesystem view. The host system's root directories are either hidden or mounted as read-only, while the designated workspace directory is mounted with read-write permissions. This setup prevents the agent from modifying system files or accessing private user data stored elsewhere on the host. The socat utility is used to establish secure communication relays between the host process and the sandboxed container, creating bidirectional streams over Unix domain sockets or loopback interfaces.

If bubblewrap or socat is not installed on the system, Devin enforces a fail-closed policy. Rather than falling back to an unsecure mode, the session halts immediately and outputs installation instructions. On macOS, Devin relies on native Seatbelt sandboxing policies to isolate process execution. On Windows, because native Windows does not support Bubblewrap, developers must run the agent inside a Windows Subsystem for Linux container or use Devin Desktop to establish the same OS-level sandbox.

• How to Set Up Shared Workspaces in OpenClawOpenClaw workspace setup provides agents with persistent, shared storage for collaborative projects. Install the Fastio...
• How to Set Up ClawHub for OpenClawClawHub is the public skill registry for OpenClaw, with over 13,000 community skills available. This guide walks...
• Devin for Terminal: Setup and CLI Command ReferenceDevin for Terminal provides a command line interface to execute local and cloud-based AI agent sessions directly from...
• How to Collaborate on Workspace Notes with Devin AIHuman developers and autonomous agents frequently require a shared context to work together effectively. Devin AI...
• How to Install and Use the Devin AI CLICognition positions Devin AI CLI as a local coding agent that runs on your machine, separate from cloud Devin in a VM....
• Devin AI Integration Guide: Connecting Devin to Your Dev StackA successful devin ai integration connects autonomous AI software engineers directly to version control, ticketing, and...

More on this subject: Devin (74 guides)

Once the sandboxing layer is active, you must configure which local directories Devin can access. In environments where the host allows the agent to manage its own workspace roots, Devin's workspace commands enable direct human control over accessible paths. These commands let you dynamically adjust the workspace boundaries during an active coding session without restarting the agent or modifying configuration files.

The primary slash commands for directory management include:

• /workspace: Lists all directories currently mounted and accessible to the agent.
• /add-dir <path>: Mounts an additional directory into the sandbox, verifies directory trust, grants write access, and allows Devin to load and run custom skills defined in that path.
• /remove-dir <path>: Revokes the agent's access to the specified path and unmounts it from the sandbox.

For permanent configuration, settings are defined in JSON files at the project or user level. The project-level configuration file is located at .devin/config.json or .devin/config.local.json inside the repository root. This file is ideal for defining repository-specific permissions and paths that Devin should always mount when working on that codebase. Because .devin/config.json is committed to version control, it ensures that every team member running Devin on that repository uses the same directory structure. The gitignored .devin/config.local.json is reserved for local path overrides, which is detailed in the Devin official documentation.

Here is an example of a project configuration file:

{
  "workspace": {
    "roots": [
      "/home/developer/projects/app"
    ],
    "ignored_paths": [
      ".git",
      "node_modules",
      "dist"
    ]
  },
  "sandbox": {
    "enforce": "Required",
    "allowed_domains": [
      "github.com",
      "api.github.com",
      "registry.npmjs.org",
      "pypi.org",
      "mcp.fast.io"
    ]
  }
}

Broader configurations are stored in the user-level configuration file, located at ~/.config/devin/config.json or %APPDATA%\devin\config.json on Windows. The user configuration is typically used to manage network access controls. Within the sandbox configuration block, you can define allowed_domains as an array of strings to restrict which external hostnames Devin can contact. For organizations, administrators can set the sandbox enforcement level to Optional or Required in Team Settings. When set to Required, team members cannot start a Devin session without the --sandbox flag, preventing any unisolated tool execution. Local configuration files override project-wide settings, which in turn override global settings, ensuring flexible developer configurations.

In addition to directory boundaries, Devin's behavior is guided by permission modes that dictate its autonomy. These modes determine whether Devin can execute file modifications and shell commands automatically or if it must pause to request human approval. You can specify the desired mode using the --permission-mode CLI flag or by defining the DEVIN_PERMISSION_MODE environment variable.

The available permission modes include:

• normal: This is the default mode. Devin automatically approves read-only actions, such as viewing files or listing directory contents. However, any file edit, directory creation, or terminal command requires explicit user approval.
• accept-edits: Workspace file edits are auto-approved, allowing Devin to modify code inside the active directories without prompting. Shell commands and writes outside the workspace still require explicit confirmation.
• smart: Workspace file edits are auto-approved, and other tool calls are evaluated by a fast safety model to run automatically only when deemed safe.
• bypass: All tool calls, including executing arbitrary shell commands and making external network fetches, are auto-approved without prompting.
• autonomous: This mode is only available when the OS-level sandbox is active. Because the sandbox restricts system access, shell commands and network fetches are auto-approved, while direct file modifications still prompt for user verification.

You can modify the permission mode interactively during a session by using the Shift+Tab keyboard shortcut or by typing /mode in the interactive console. It is important to note that setting a permissive mode like bypass in a local session does not override team-wide policies configured by administrators. If the organization has enforced an ask rule for specific actions, Devin will still prompt the user, ensuring that safety policies are maintained at the organizational level.

To see these modes in action, consider a developer executing a large refactoring task across hundreds of source files. Before starting the session, the developer sets the permission mode to accept-edits:

export DEVIN_PERMISSION_MODE=accept-edits
devin

This configuration allows Devin to edit the codebase without pausing for manual confirmation on every single file write. However, when the agent attempts to run compile commands or execute test scripts, the terminal tools trigger a prompt, giving the human developer an opportunity to review the commands before execution. If the developer decides to automate the verification phase, running /mode autonomous within the session enables unprompted terminal executions inside the sandbox container.

Stop losing Devin AI code files between session runs

Get one branded workspace with an MCP-ready endpoint for your agent's reads and writes, with versioning and search built in. Every organization starts with a 14-day free trial, which requires a credit card. Plans are Starter at $29/mo, Business at $99/mo, and Growth at $299/mo.

Start 14-Day Trial

Local disk directories, simple AWS S3 buckets, and traditional sync folders are common options for persisting code files. However, they present challenges when used as workspaces for AI agents. Local directories isolate files on a single developer's machine, preventing other agents and team members from collaborating. Simple AWS S3 buckets require custom scripts to handle indexing, metadata extraction, and access control. Google Drive and OneDrive lack real-time activity feeds and do not support remote tool configurations for agents.

Fast.io provides an intelligent cloud workspace designed for collaborative agent workflows. Instead of acting as simple storage, Fast.io acts as a shared substrate where human engineers and coding agents operate from a single workspace. Because Fast.io is built to support the Model Context Protocol, Devin can connect to it directly to read, write, and index project files in real time.

Since version 3000.3, the Devin CLI supports dedicated MCP configurations. To protect sensitive credentials, you should configure the Fast.io connection in the gitignored project-level file .devin/mcp_config.local.json or the global user-level file. Because Fast.io runs a remote MCP server over Streamable HTTP with a legacy SSE transport, you do not need to configure command arguments or local npm executables. Instead, you specify the remote endpoint. If you are using Devin Desktop, use serverUrl to point to the server.

To connect Devin to a Fast.io workspace, define the configuration as follows:

{
  "mcpServers": {
    "fastio": {
      "serverUrl": "https://mcp.fast.io/mcp/key",
      "headers": {
        "Authorization": "Bearer <YOUR_FASTIO_ORGANIZATION_API_KEY>"
      }
    }
  }
}

For Devin Desktop installations, configure the server using this structure:

{
  "mcpServers": {
    "fastio": {
      "serverUrl": "https://mcp.fast.io/mcp/key",
      "headers": {
        "Authorization": "Bearer <YOUR_FASTIO_ORGANIZATION_API_KEY>"
      }
    }
  }
}

Once configured, Devin gains access to Fast.io's workspace tools. This integration provides several advantages:

• Persistent Version History: Unlike basic storage volumes that overwrite files, Fast.io maintains a complete version history for every file. If Devin makes an unwanted edit, developers can restore previous versions, ensuring concurrent agent operations are fully auditable.
• Intelligence Mode: When Intelligence Mode is enabled on a Fast.io workspace, uploaded documents are auto-indexed on arrival. Devin can perform hybrid search using the MCP tools to retrieve contextual information with built-in citations, eliminating the need to set up a separate vector database.
• Metadata Views: Teams can structure documents into a queryable database by describing the fields they want extracted in natural language. Fast.io automatically populates a spreadsheet with fields like date, integers, booleans, and JSON, which Devin can query via the MCP interface. Learn more about document data extraction at the Metadata Views page.
• Ownership Transfer: When Devin completes a development task, the human engineer can transfer ownership of the workspace or share specific files using branded, expiring shares with per-recipient access, enabling a smooth transition from agent to human.

Creating a user account is free, but doing real work requires an organization on a paid subscription. Every organization starts with a 14-day free trial, which requires a credit card | Plans are Starter at $29/mo, Business at $99/mo, and Growth at $299/mo. Review details on the pricing page.

In cases where you need to interact with the workspace from outside MCP, you can make HTTP requests directly to the Fast.io REST API. The API lives at https://api.fast.io/current/ and the documentation is public at the Fast.io API Reference. Routes are nested, singular, and end in a slash, such as POST /current/workspace/{workspace_id}/storage/{parent_id}/addfile/ for adding files, or GET /current/user/ for fetching user profiles.

During a collaborative run, Devin writes code files to a shared workspace in Fast.io. The human supervisor and another documentation writer agent monitor workspace updates using the workspace activity long-poll interface. When changes are detected, the documentation agent reads the updated code files, generates API documentation, and saves it as a Collaborative Note in the same workspace. The human supervisor reviews the note and creates a durable File Share via the Fast.io storage for agents panel.

After configuring the sandbox, setting the permissions, and adding the Fast.io MCP server, you should verify the environment before starting long-running tasks. Devin provides CLI diagnostic tools to check the status of the environment.

You can verify platform prerequisites by running:

devin sandbox setup

This command checks if bubblewrap and socat are installed on Linux, confirms WSL 2 permissions on Windows, and verifies that the system has sufficient privileges to mount sandboxed paths. If the setup fails, ensure that your user account has permissions to execute unprivileged user namespace mounts, which are required by Bubblewrap.

To check network connectivity and MCP server configurations, execute the doctor utility:

devin doctor

This utility tests connections to all defined MCP servers, verifies API keys, and ensures that headers are correctly configured. If the connection to Fast.io fails with a network error, check that the URL matches https://mcp.fast.io/mcp/key and that your organization API key is valid.

If Devin reports file-access errors within a session, check the active directory mappings. If a path is missing from the active sandbox mount, Devin cannot read or write to it, even if the directory exists on the host machine. You can resolve this by running the /add-dir command with the absolute path of the directory you want to mount. This command updates the active container mounts dynamically, allowing the agent to read and write to the folder without needing to restart the session.

When troubleshooting sandbox configurations, check these common error messages:

• Bubblewrap binary not found: Indicates that the system path does not contain bwrap. On Ubuntu or Debian, run sudo apt-get install bubblewrap socat to resolve it. On CentOS/RHEL, use sudo dnf install bubblewrap socat.
• Unprivileged user namespaces are disabled: Some Linux distributions disable this feature by default. Run sudo sysctl -w kernel.unprivileged_userns_clone=1 to enable it temporarily, or write the setting to /etc/sysctl.d/99-bubblewrap.conf for persistence.
• socat connection refused: Indicates a communication failure between the host's relay and the container. Verify that the agent is not blocked by local firewall configurations or security policies that restrict loopback connections.
• MCP connection handshake timeout: Verify that your corporate network or proxy is not blocking WebSocket or Streamable HTTP connections to mcp.fast.io.

Before kicking off overnight runs, developers should run a brief validation task. Have Devin read a single test file, perform a basic write operation within the mounted directory, and make a ping request to the Fast.io MCP server. This simple test verifies that file access, sandbox constraints, and remote tool configurations are fully operational before executing long-running runs.