Open-source, local-first social media research agent for Instagram, TikTok, and LinkedIn. Jev routes read-only steps; socai CLI captures cited browser evidence.
Troubleshooting
Jev Social directs your Chrome browser through the socai CLI to collect evidence visible to the active browser session. This guide explains how to identify and resolve common setup, connection, and platform access barriers while preserving the project's honest browser boundary.
[!WARNING] Data Retention & Privacy Notice:
- Archived Runs & Artifacts: Two distinct storage locations persist data that may survive cancellation or process termination:
- Jev Social Runs: Running, interrupted, and finalized runs persist sanitized evidence cards, action status, timing, and the partial or final report to
${JEV_SOCIAL_HOME:-~/.jev-social}/runs/<id>.json. Raw CLI stdout, cookies, DOM snapshots, and local filesystem paths are not stored in these checkpoints.socaiCommand Artifacts: The underlying CLI writes tool inputs, outputs, downloaded media, and execution artifacts following the precedence:SOCAI_RUNS_DIRenvironment override $\rightarrow$ configuredruns.dir(socai config get runs.dir) $\rightarrow$ default~/.socai/runs/.- Locating & Inspecting Effective Stores: To inspect your active artifact storage locations without modifying files:
# macOS / Linux (inspect paths) echo "Jev Social runs: ${JEV_SOCIAL_HOME:-$HOME/.jev-social}/runs" SOCAI_CONFIG_RUNS="$(/path/from-status config get runs.dir 2>/dev/null)" echo "socai artifacts: ${SOCAI_RUNS_DIR:-${SOCAI_CONFIG_RUNS:-$HOME/.socai/runs}}"# Windows PowerShell (inspect paths) $jevDir = if ($env:JEV_SOCIAL_HOME) { Join-Path $env:JEV_SOCIAL_HOME "runs" } else { "$HOME\.jev-social\runs" } $configuredRuns = (& /path/from-status config get runs.dir 2>$null) $socaiDir = if ($env:SOCAI_RUNS_DIR) { $env:SOCAI_RUNS_DIR } elseif ($configuredRuns) { $configuredRuns } else { "$HOME\.socai\runs" } Write-Host "Jev Social runs: $jevDir" Write-Host "socai artifacts: $socaiDir"- Retention & Manual Removal Guidance:
- Review directory contents (e.g.
ls "$DIR"orGet-ChildItem $dir) before removing any stored data.- To clear individual runs or prune old artifacts, delete specific target files manually from the verified store directories rather than running unvalidated recursive shell recipes across dynamic or environment-supplied paths.
- Note: configured
runs.dirpaths may use custom directory names; always verify the exact resolved target directory before manual removal.- Review Before Sharing: Exported
report.mdfiles and run checkpoints can still preserve access-restricted post text, private account connections, author names, bio/experience data, comments, and direct URLs from your active session. Always review and redact sensitive data before sharing reports or diagnostic files publicly.
Local Browser Boundary
By default (using existing or managed Chrome modes without external endpoint overrides), Jev Social operates strictly within your local Chrome browser environment:
- No authentication bypasses: It does not bypass login screens, CAPTCHAs, bot challenges, or platform rate limits.
- No credential injection: It does not store passwords, scrape private cookies, or use rotating proxy pools.
- Honest failure reporting: When a site gates content behind a login wall or rate limit, Jev Social halts visibly and returns partial results rather than inventing data or claiming false success.
(Note on non-local execution: Users can explicitly provide external debugging endpoints via SOCAI_CDP_URL / SOCAI_CDP_WS. Additionally, socai supports a hosted remote mode (chrome.profile remote), which requires socai Pro and provisions ephemeral cloud browser sessions through socai-server. Hosted remote sessions run without interactive desktop access, so users cannot solve CAPTCHAs or login gates in hosted remote mode; authoritative socai guidance is to retry later or switch to local existing or managed mode to authenticate interactively.)
Distinguishing Failure & Result States
| State | What Happened | What You See | How to Resolve |
|---|---|---|---|
Missing socai executable |
The socai CLI is not installed or not discoverable at the resolved binary path. |
Status indicator displays socai unavailable, or terminal reports spawn ENOENT / command not found. |
On macOS and Windows, run npx github:socai-io/jev-social#v0.1.13 onboard (or npm start -- onboard). On Linux, install the CLI package from source via Cargo (cargo install --git https://github.com/socai-io/socai.git socai-cli) and set SOCAI_BIN. |
| Browser connection failure | socai cannot connect to Chrome or its DevTools protocol (CDP) endpoint. |
The readiness strip shows Chrome unavailable, Chrome permission needed, Chrome disconnected, or Remote browser unavailable with a short local action. |
Follow your active connection mode below. Ensure the target Chrome instance is running with remote debugging enabled and accept any remote-debugging permission prompts. Avoid blanket process-killing commands. |
| Login-required / challenge gate | The platform blocked unauthenticated access with a login modal, redirect (e.g. authwall), or CAPTCHA. |
Status displays a partial result notice with the specific gate reason (for example, Partial results · The platform requires attention: login_required). |
Open the platform in the specific user-accessible Chrome session or profile selected by socai (existing or managed mode), complete authentication or challenges, and verify browsing before re-running. (If using hosted remote mode, switch to existing or managed mode to authenticate interactively.) |
| Valid empty result | The platform loaded successfully and the search executed cleanly, but returned 0 matching records. | Evidence cards, table, and heading remain hidden. Depending on subsequent decisions, the run can finalize as partial (Partial results · Jev stopped without usable evidence.), step_limit (if max steps are reached), or decision_failed (if a subsequent model decision call fails). |
The initial search executed cleanly without matching records on the platform. Broaden or rephrase your search query. (If a subsequent decision failed, verify model API connectivity). |
| Early decision or classification failure | The configured decision provider encountered an error during classification or the first action choice before any browser operation ran. | Classification failures emit an error before a run exists. A first action-decision failure saves a failed checkpoint with no captured posts. | Ensure the goal is supported, specify --platform explicitly, then check the OpenRouter key or local System One server reported by status. |
Mid-run decision failure (decision_failed) |
The decision provider failed after one or more actions had already executed. | Status displays Partial results · <error message> with status decision_failed; collected evidence prior to the failure is preserved. |
Check the configured provider, preserve the partial evidence, and retry only after the provider is healthy. |
Safe Diagnostics
Run these diagnostic commands to verify readiness without exposing API credentials or browser secrets:
1. Check Configuration & Capabilities
By default, Jev Social resolves an OpenRouter key from OPENROUTER_API_KEY, lowercase openrouter in .env, or saved onboarding config (config.json). A valid JEV_SOCIAL_SYSTEM_ONE_URL switches typed decisions to a loopback TypeSafe-compatible provider and does not require an OpenRouter key. Checking only $OPENROUTER_API_KEY can therefore misreport effective readiness.
Query the local status endpoint to verify the effective jevConfigured state and platform capabilities:
curl -s http://127.0.0.1:8766/api/status
The browser API endpoint /api/status returns sanitized status and omits local filesystem paths:
{
"jevConfigured": true,
"jevModel": "~typesafe/jev-latest",
"decisionProvider": "openrouter",
"socai": {
"installed": true,
"version": "0.6.0",
"capabilities": {
"instagram": true,
"tiktok": true,
"linkedin": true
},
"readiness": {
"schemaVersion": 1,
"cliAvailable": true,
"daemonRunning": true,
"daemonCompatible": true,
"browserConnected": true,
"browserState": "connected",
"profileMode": "existing",
"activeProfileMode": "existing",
"errorCode": null,
"platforms": {
"instagram": { "available": true, "loginState": "unknown", "operations": ["search", "get-posts"] },
"tiktok": { "available": true, "loginState": "unknown", "operations": ["search", "get-videos"] },
"linkedin": { "available": true, "loginState": "unknown", "operations": ["search", "get-posts"] }
}
}
}
}
The readiness probe is observational: it calls socai status --json, which does not start the daemon, launch Chrome, connect a browser, or show a permission prompt. Jev Social validates and allowlists that response before returning it. WebSocket URLs, ports, cookies, profile paths, session tokens, and the CLI's free-form next_step text are never exposed through /api/status.
An older socai build that does not support status --json remains usable. The UI reports Chrome state unknown and recommends updating socai; it does not repeatedly attempt a browser connection or block a research run.
When socai can identify platform authentication independently, the platform picker labels it as (signed in) or (sign in). An unknown login state remains unlabeled: it is not treated as either authenticated or logged out.
(Note: Platform capabilities are build-dependent. The official social CLI requires v0.6+ or a development build with social subcommands enabled; older tagged releases such as v0.5.6 registered only xhs and dy, so instagram, tiktok, and linkedin will all probe false. On v0.6+ builds, linkedin evaluates to true or false depending on whether that specific build enables the LinkedIn subcommand.)
For local operator diagnostics including the resolved configuration file path and binary path, run the CLI status command:
npm start -- status
Expected output:
{
"jevConfigured": true,
"jevModel": "~typesafe/jev-latest",
"decisionProvider": "openrouter",
"configPath": "/home/user/.jev-social/config.json",
"socai": {
"installed": true,
"bin": "/home/user/.socai/bin/socai",
"version": "0.6.0",
"capabilities": {
"instagram": true,
"tiktok": true,
"linkedin": true
},
"readiness": {
"browserConnected": true,
"browserState": "connected",
"profileMode": "existing",
"activeProfileMode": "existing"
}
}
}
[!NOTE] Privacy note:
npm start -- statusoutputsconfigPathandsocai.binfor local operator diagnostics. If sharing CLI output in public issues or chat, redact these local filesystem paths. The browser API endpoint (/api/status) automatically keeps paths sanitized.
2. Use a Local Kev Decision Server
Kev exposes the TypeSafe-compatible endpoint Jev Social needs. Start it separately, then set the exact loopback endpoint and model:
git clone https://github.com/jaredpalmer/kev.git
cd kev
git checkout 2855ba2a55a80579176a459f78b95d03548cabb5
uv sync --extra serve
uv run --extra serve python -m kev.serve --run jaredpalmer/kev-4b@139fdd94f1b6a6ad80cc15e08fcb99cac885a101 --port 8009
export JEV_SOCIAL_SYSTEM_ONE_URL=http://127.0.0.1:8009/v1/systemone
export JEV_SOCIAL_SYSTEM_ONE_MODEL=kev-latest
export JEV_SOCIAL_SYSTEM_ONE_TIMEOUT_MS=120000
export OPENROUTER_REPORT_MODEL=off
npm start -- status
npm start
The sanitized status should report "decisionProvider": "local", "jevModel": "kev-latest", and "jevConfigured": true without showing the endpoint or port. The endpoint must use plain loopback HTTP and the exact /v1/systemone path. Jev Social refuses remote hosts, redirects, embedded credentials, query strings, and fragments. Local decisions use a 120-second default and maximum timeout; set JEV_SOCIAL_SYSTEM_ONE_TIMEOUT_MS to a lower integer value when needed. OPENROUTER_REPORT_MODEL=off prevents a separately configured OpenRouter key from being used for optional report synthesis.
3. Verify the Resolved socai Binary
Jev Social resolves the socai binary in the following order:
SOCAI_BINenvironment variable orsocaiBinin~/.jev-social/config.json.- Standard installation path at
~/.socai/bin/socai(orsocai.exeon Windows). - Local development build candidates (
target/debugortarget/release). - System
PATH.
Because resolution is not pinned to a single binary and may differ from what is on your current shell PATH, test the exact binary resolved by Jev Social (found in the socai.bin field of npm start -- status, represented as /path/from-status below):
# Replace /path/from-status with your resolved binary path from `npm start -- status`:
/path/from-status --version
4. Installing or Reinstalling socai
- macOS & Windows: Run automated onboarding to download and install the official release:
npx github:socai-io/jev-social#v0.1.13 onboard # or from a repository checkout: npm start -- onboard - Linux & Source Builds: Prebuilt installer downloads currently support macOS and Windows. On Linux,
socaiis a virtual Cargo workspace; install thesocai-clipackage via Cargo or build it from source:# Install via Cargo: cargo install --git https://github.com/socai-io/socai.git socai-cli # Or build from source: git clone https://github.com/socai-io/socai.git cd socai && cargo build --release -p socai-cli export SOCAI_BIN="$(pwd)/target/release/socai"
Browser Connection & Session Modes
socai manages its Chrome connection mode and profile directory through configuration commands. To configure which browser session socai uses:
# Select profile connection mode: existing, managed, auto, or remote (requires Pro)
/path/from-status config set chrome.profile existing
# Select a custom Chrome profile / user data directory (applies to managed and auto modes):
/path/from-status config set chrome.profile_dir /path/to/profile/dir
# Stop the running daemon so new chrome.* settings take effect:
/path/from-status stop
# Inspect active configuration:
/path/from-status config get
Connection Modes & Precedence in socai v0.6.0
- CDP Precedence: Explicit
SOCAI_CDP_WSorSOCAI_CDP_URLenvironment variables take precedence in all profile modes exceptmanaged(includingexisting,auto, andremote). Ifchrome.profileis set toremotewhile an explicit CDP endpoint is provided,socaiconnects to that endpoint rather than provisioning a Pro-hosted cloud session. Onlymanagedmode (chrome.profile managed) deliberately ignores external CDP endpoints to launch or reuse its isolated managed profile. existing:socaiattaches to an already-running Chrome instance (e.g. started with--remote-debugging-port=9222or reachable atSOCAI_CDP_URL). Note:chrome.profile_diris ignored forexistingmode since it connects directly to the active browser process.managed:socaistarts and controls a dedicated Chrome process. By default, it uses the persistent profile directory at~/.socai/chrome-profile(orchrome.profile_dirif configured), preserving login credentials and cookies across runs.auto:socaitries managed launch first, then falls back to connecting to an existing Chrome instance (core/src/cdp/lifecycle.rs:403-411).remote(Hosted): A hosted cloud browser mode that requires socai Pro and provisions temporary remote sessions viasocai-server(unless an explicitSOCAI_CDP_*endpoint override is set). Because hosted remote containers lack local GUI interaction, users cannot interactively solve login gates or CAPTCHAs in hostedremotemode; authoritativesocaiguidance is to retry later or switch toexistingormanagedmode to authenticate.
[!TIP] If changing
chrome.*configuration while the backgroundsocaidaemon or browser is running, run/path/from-status stop(orsocai stop) so the daemon reloads settings on the next run.
Jev Social forwards connection overrides (SOCAI_CDP_URL, SOCAI_CDP_WS, SOCAI_CHROME_USER_DATA_DIR, and SOCAI_CHROME_EXECUTABLE) to child processes during runtime discovery. (Note: socai does not read SOCAI_CHROME_PROFILE; use socai config set chrome.profile to configure the connection mode.)
Working with Browser Sessions Safely
- Authenticate User-Accessible Profiles: When logging into social platforms or solving challenges, ensure you are interacting with the session selected by
socai:- For
existingmode: Authenticate within the running Chrome instance discovered through CDP (e.g. on--remote-debugging-port=9222orSOCAI_CDP_URL). Note:chrome.profile_diris completely ignored inexistingmode. - For
managedorautomode: Authenticate within the designated profile directory (chrome.profile_diror default~/.socai/chrome-profile). Logging into an everyday, unlinked browser profile will not share cookies or sessions withsocai. If using hostedremotemode without an explicit CDP override, switch toexistingormanagedmode on your local machine to authenticate interactively.
- For
- Existing-Profile Remote Debugging Permission: If attaching
socaito an existing Chrome profile via remote debugging (e.g.--remote-debugging-port=9222), Chrome may display an infobar or confirmation prompt requesting permission for remote debugging/automation. Confirm that this permission is granted. - Avoid Blanket Process Termination: Do not use blanket commands such as
pkill chromeorkillall chrome. Arbitrarily closing processes can destroy the exact running Chrome session, debugging port, or authenticated state thatsocaiis configured to reuse.
Platform-Specific Troubleshooting
- Issue: Instagram frequently prompts with a login modal or redirects unauthenticated queries to
/accounts/login/. - Resolution: Open
https://www.instagram.comwithin a user-accessible Chrome session/profile selected bysocai(existingormanagedmode; switch toexistingormanagedif on hostedremotemode), log into your account, and verify you can browse posts without a login modal. Then re-run Jev Social.
TikTok
- Issue: TikTok may present an interactive puzzle/slider challenge or restrict video detail and comments for unauthenticated sessions.
- Resolution: Complete any active puzzle verification within a user-accessible Chrome session/profile selected by
socai(existingormanagedmode). Test direct platform access using the resolvedsocaiexecutable:/path/from-status tiktok search "wearable AI" --num 4 --pretty
- Issue: LinkedIn redirects unauthenticated searches for people, content, or companies to
linkedin.com/authwall. - Capability Prerequisite: Binary resolution is dynamic and depends on the active
socaiexecutable. Direct LinkedIn CLI commands require an executable with LinkedIn support enabled (e.g. a LinkedIn-capablev0.6+build or settingSOCAI_BINto a capable executable). - Supported Diagnostics:
- Check platform capability via the local status endpoint:
Confirm thatcurl -s http://127.0.0.1:8766/api/statussocai.capabilities.linkedinevaluates totrue(it evaluates tofalseon builds without the LinkedIn subcommand enabled). - Test subcommand availability directly on the resolved executable:
/path/from-status linkedin --help
- Check platform capability via the local status endpoint:
- Resolution: Sign into LinkedIn within a user-accessible Chrome session/profile selected by
socai(existingormanagedmode; switch toexistingormanagedif on hostedremotemode). Once your authenticated session is active andsocai.capabilities.linkedinistrue, run research through Jev Social:
On builds where thenpm start -- search "find AI product managers in San Francisco on LinkedIn" --platform auto --limit 4linkedinsubcommand is supported by the resolved binary:/path/from-status linkedin search "AI product managers" --num 4 --pretty
Working with Partial Evidence
Understanding how Jev Social handles runs that stop before completing all requested steps:
Completed Partial Runs (Step Exhaustion & Login Gates)
When a run naturally halts at a barrier—such as a login or challenge wall (status: blocked) or reaching the configured decision step limit (status: step_limit via --max-steps)—all collected evidence is preserved and finalized:
- Finalized Report Generation: The backend executes
evidenceReport()and persists the run withsaveRun(). - Captured Post Cards: Any posts, profiles, or video cards retrieved before the stopping point remain rendered in the UI.
- Records Table: The structured evidence table retains all extracted rows.
- Action History: The "Steps chosen by Jev" list displays each operation executed along with its status (
${step.action.label} · ${step.status}). - Report Export: The generated Markdown summary is displayed, and the Download report.md button is fully accessible to export the captured evidence.
Manual Cancellation
When a run is manually cancelled (e.g. by navigating back to search, clicking back, or closing the stream connection):
- Shutdown Behavior:
- During a model request phase (classification, action choice, or optional report synthesis via OpenRouter), the in-flight HTTP request is cancelled via
AbortSignalwith no child process signals involved. - During a running
socaichild operation, process tree termination is requested immediately: on Unix (macOS / Linux),SIGTERMis sent to the process group followed bySIGKILLafter a one-second grace period; on Windows,child.kill("SIGTERM")is sent followed bytaskkill.exe /pid <pid> /t /fafter the one-second grace period. - Detached background browser sessions or the standalone
socaidaemon may remain running.
- During a model request phase (classification, action choice, or optional report synthesis via OpenRouter), the in-flight HTTP request is cancelled via
- Observable Guarantee: Cancellation stops active work and may end without a newly rendered run view or downloadable report in the UI. Completed evidence and action checkpoints remain on disk. If delivery stops during report synthesis or streaming, the checkpoint is marked interrupted and rebuilt as an honest deterministic partial report; no incomplete streamed prefix is enabled for download.