Background
Pinchtab is a lightweight browser automation tool that provides AI Agent-friendly browser control capabilities via an HTTP API. Compared to Playwright, it reduces token consumption by 5–13×.
Project Repository: GitHub - pinchtab/pinchtab: High-performance browser automation bridge and multi-instance orchestrator with advanced stealth injection and real-time dashboard. · GitHub
Environment
- OS: Elementary OS 8.1 (based on Ubuntu 24.04)
- Architecture: ARM64
- Chromium: Chromium bundled with Playwright
Deployment Steps
1. Install Go
sudo apt update && sudo apt install -y golang-go
2. Fetch Pinchtab Binary
git clone https://github.com/pinchtab/pinchtab.git
cd pinchtab && go build -o pinchtab ./cmd/pinchtab
3. systemd Service Configuration
[Unit]
Description=Pinchtab Browser Automation Service
After=network.target
[Service]
Type=simple
User=$USER
Group=$USER
WorkingDirectory=/opt/pinchtab
ExecStart=/opt/pinchtab/pinchtab
Restart=on-failure
RestartSec=10
Environment="PINCHTAB_PORT=9867"
Environment="PINCHTAB_HEADLESS=true"
Environment="PINCHTAB_PROFILE_DIR=/var/lib/pinchtab/chrome-profile"
Environment="PINCHTAB_STATE_DIR=/var/lib/pinchtab"
Environment="PINCHTAB_AUTO_LAUNCH=1"
Environment="CHROME_BIN=$HOME/.cache/ms-playwright/chromium-1212/chrome-linux/chrome"
Environment="CHROME_FLAGS=--no-sandbox"
NoNewPrivileges=true
PrivateTmp=true
ProtectSystem=strict
ProtectHome=read-only
ReadWritePaths=/var/lib/pinchtab $HOME/.config/pinchtab
MemoryMax=2G
CPUQuota=200%
[Install]
WantedBy=multi-user.target
4. Deploy
sudo mkdir -p /opt/pinchtab /var/lib/pinchtab
sudo chown $USER:$USER /var/lib/pinchtab
sudo cp pinchtab /opt/pinchtab/ && sudo chmod +x /opt/pinchtab/pinchtab
sudo systemctl daemon-reload && sudo systemctl enable --now pinchtab
Key Pitfalls and Solutions
1. chromium-browser Is a Snap Stub
On Ubuntu 24.04, the chromium-browser package is merely a transitional snap wrapper — it contains no actual browser binary. Pinchtab auto-detects it but fails to launch.
Solution: Use Playwright’s bundled Chromium instead, and explicitly specify its path via the CHROME_BIN environment variable:
# Locate Playwright's Chromium binary
find ~/.cache/ms-playwright -name chrome -type f
# Set CHROME_BIN to the path found above
2. AppArmor Sandbox Restrictions
Chrome startup fails with No usable sandbox!. Starting with Ubuntu 23.10, AppArmor restricts unprivileged user namespaces.
Solution: Disable sandboxing via CHROME_FLAGS=--no-sandbox.
3. curl Proxy Interference with localhost
If all_proxy is set system-wide, curl attempts to route localhost requests through the proxy, causing connection failures (exit code 97).
Solution: Add the --noproxy flag to curl commands to bypass proxy for localhost.
4. systemd’s ProtectHome Blocks Chromium Access
Setting ProtectHome=true prevents the service from accessing Playwright’s Chromium binary located in the user’s home directory.
Solution: Use ProtectHome=read-only, which permits read access while blocking writes.
Measured Token Efficiency
Test page: play.wenpai.net
| Mode | Characters | Estimated Tokens | Savings |
|---|---|---|---|
Text extraction (/text) |
769 | ~192 | 94% |
Interactive snapshot (?filter=interactive) |
1,995 | ~498 | 85% |
Full snapshot (/snapshot) |
13,157 | ~3,289 | Baseline |
In text mode, a full webpage requires only ~192 tokens to retrieve all content — a 94% reduction compared to Playwright’s full snapshot (~3,289 tokens).
Usage Examples
# Health check
curl --noproxy localhost http://localhost:9867/health
# Navigate to a webpage
curl --noproxy localhost -X POST http://localhost:9867/navigate \
-H "Content-Type: application/json" \
-d '{"url":"https://example.com"}'
# Extract text (~192 tokens)
curl --noproxy localhost http://localhost:9867/text
# Interactive snapshot (~498 tokens)
curl --noproxy localhost "http://localhost:9867/snapshot?filter=interactive"
# Take screenshot
curl --noproxy localhost http://localhost:9867/screenshot > screenshot.jpg
Summary
Pinchtab has been successfully deployed and runs stably under systemd on Elementary OS (Ubuntu 24.04 ARM64). Four key points enabled success:
- Use Playwright’s Chromium instead of the snap stub — Ubuntu 24.04’s
chromium-browserpackage is only a snap wrapper. - Bypass AppArmor with
--no-sandbox— Ubuntu 23.10+ restricts unprivileged user namespaces. - Use
curl --noproxyto avoid proxy interference — Required when accessinglocalhostunder a system-wide proxy configuration. - Set
ProtectHome=read-only— Allows the systemd service to read Chromium binaries stored in the user’s home directory without granting write access.
Real-world measurements show 85–94% higher token efficiency versus traditional approaches — making Pinchtab exceptionally well-suited for AI Agent-driven browser automation.
systemd user service
CLI bug present; API works fine