Skip to content

High-performance browser automation bridge and multi-instance orchestrator with advanced stealth injection and real-time dashboard.

6.2 KB
Raw Blame

Agent Identity

PinchTab offers three levels of agent identification, from simple to fully managed. Pick the one that fits your setup.

Server Token

Every PinchTab server has a bearer token configured in server.token. This is the baseline authentication method — it proves the caller is authorized to use the server, but says nothing about which agent is making the request.

The CLI reads it from the local config automatically. To supply it explicitly (for example against another server), use the environment variable — there is no --token flag:

export PINCHTAB_TOKEN=your-server-token
pinchtab nav https://example.com

When to use: Single-agent setups, quick scripting, or when you don't need per-agent tracking.

Limitation: All requests look the same in the activity feed — no way to tell which agent did what.

Agent ID

Adding an agent ID tags every request with a name. This shows up in the activity feed and the dashboard's Agents page. The server still authenticates via the bearer token, but now each request carries an identity.

pinchtab --agent-id bosch nav https://example.com

Or via environment variable:

export PINCHTAB_AGENT_ID=bosch
pinchtab nav https://example.com

The X-Agent-Id header is sent with every request. No server-side setup required — any string works.

When a request has an agent ID but no agent session, PinchTab also keeps that agent's current tab separately from other agents. You can omit tabId in a multi-step flow without stealing another agent's current tab.

When to use: Multiple agents sharing one server where you want to see who did what, but don't need session management.

Limitation: No revocation, no idle tracking, no labels. The agent ID is self-declared — any caller can claim any identity.

Agent Sessions

⚠️ Security notice: Agent sessions are designed for trusted, controlled environments — local machines, private networks, CI, and setups where all agents are under your control. Do not expose the session management API (/sessions) to the public internet. Any authenticated caller (bearer token or dashboard cookie) can create, list, and inspect sessions for any agent. Session-authenticated callers are blocked from dashboard/admin endpoint families, but sessions are still not a multi-tenant isolation boundary.

Sessions are the full identity solution. Each session is a revocable, server-managed token tied to a specific agent ID. Sessions provide:

  • Labels — human-readable names like "research task" or "daily scrape"
  • Activity grouping — all requests within a session are grouped in the dashboard
  • Idle timeout — sessions expire after 30 minutes of inactivity (configurable)
  • Max lifetime — hard expiry after 24 hours (configurable)
  • Revocation — kill a session without rotating the server token

Enable Sessions

Add to your config.json:

{
  "sessions": {
    "agent": {
      "enabled": true,
      "mode": "preferred"
    }
  }
}

Modes:

Mode Behavior
off Agent sessions disabled
preferred Both bearer and session auth accepted (default when enabled)
required Not implemented; refused at config load (see Configuration)

Create a Session

curl -X POST http://localhost:9867/sessions \
  -H "Authorization: Bearer $PINCHTAB_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"agentId": "bosch", "label": "research task"}'

Response:

{
  "id": "ses_e6ac8132fe7e7016",
  "agentId": "bosch",
  "label": "research task",
  "sessionToken": "ses_1138f72e77f23c49...",
  "status": "active"
}

The sessionToken is returned exactly once. Store it — PinchTab only persists the hash.

Use a Session

export PINCHTAB_SESSION=ses_1138f72e77f23c49...
pinchtab nav https://example.com
pinchtab snap -i -c
pinchtab click e5

Or pass the header directly:

curl -X POST http://localhost:9867/navigate \
  -H "Authorization: Session ses_1138f72e77f23c49..." \
  -H "Content-Type: application/json" \
  -d '{"url": "https://example.com"}'

No need to set --agent-id — the session carries the agent identity.

Current-tab state is session-scoped. Two sessions for the same agentId keep separate current tabs, and session scope takes priority over any X-Agent-Id header.

Manage Sessions

# List all sessions
curl http://localhost:9867/sessions \
  -H "Authorization: Bearer $PINCHTAB_TOKEN"

# Revoke
curl -X POST http://localhost:9867/sessions/ses_e6ac8132fe7e7016/revoke \
  -H "Authorization: Bearer $PINCHTAB_TOKEN"

Configuration

Setting Default Description
sessions.agent.enabled true Enable agent sessions
sessions.agent.mode preferred Auth mode. preferred serves agent sessions alongside the server token; off disables them exactly as enabled: false does. required is not implemented and is refused at config load — the bearer token and the dashboard cookie still authenticate, so the value cannot deliver the session-only auth it names
sessions.agent.idleTimeoutSec 1800 (30m) Session expires after this many seconds of inactivity
sessions.agent.maxLifetimeSec 86400 (24h) Hard session expiry

If a session record carries explicit grants, those grants narrow which endpoint groups the session may call. Grants are set when the session is created — pinchtab session create --agent-id <id> --grant browse, or the grants field on POST /sessions — and are reported by session list and session info. If a session has no explicit grants, it can use the normal non-admin automation API by default, while dashboard/admin routes remain blocked. That default is meant for trusted automation only. A grant never widens: server-level capability gates still apply on top of it.

Choosing the Right Level

Scenario Recommendation
One agent, local only Server token is enough
Multiple agents, want attribution Add --agent-id or PINCHTAB_AGENT_ID
Production multi-agent, need revocation Use agent sessions
Shared server, untrusted agents Run separate PinchTab instances; sessions are not sufficient isolation