NextCore Browser Local API

Control profiles with scripts running on the same machine: create, open, get the CDP port, arrange windows, back up and restore.

#What the Local API is

The Local API is a "control port" that NextCore Browser opens right on your machine. Instead of clicking in the app, a program (script) sends commands to this port to create profiles, open browsers, arrange windows… and the app does exactly what it would if you clicked.

• Only programs running on this same machine can call it (address 127.0.0.1); other machines on the network and the Internet cannot reach it.
• Every command must include a token (like a password) taken from SETTINGS › AI agent (MCP) › Advanced.
• Web pages opened in a browser cannot call it (the app rejects every request with an Origin header), so a malicious page cannot secretly control your profiles.
• No command returns proxy passwords, 2FA keys, cookies or email passwords.

#What it is for

#Turning it on and getting the token

SETTINGS › AI agent (MCP), open Advanced at the bottom of the block: turn on Enable Local API, set the Port (default 19880), and click Show token to see the Token. The bottom right corner of the app footer shows API : while listening, and API off or API error when not.

NextCore Browser

• Listens only on 127.0.0.1; other machines on the network cannot call it.
• Every request must have Authorization: Bearer <token>.
• Requests with an Origin header (calls from a web page) are rejected, which stops malicious web pages from controlling your profiles.

curl -H "Authorization: Bearer $NCB_TOKEN" http://127.0.0.1:19880/api/v1/status

#MCP on the Local API: tool categories

Since 0.3.172, every MCP tool has a category (_meta.category). New installs only list the core groups (profiles, common page actions, E2E, Kernel), about 49 tools instead of 213, so agents use less context per session. Machines installed earlier keep every category as before.

• To add categories: use the machine setting mcp.toolsets (agents change it through ncb_settings), or connect MCP with /mcp?toolsets=a,b (all means every category).
• Calling a tool in a category that is turned off ⇒ error NCB-1006, with the category name and how to turn it on in _meta.
• Calls through the station to a sub-machine are not filtered by category.

Repo attribution (setting repoAttribution, off by default): when on, NextCore E2E results include a line for the agent to write to .ncb/e2e/dau-an.md in your repo, and the commit trailer Verified-by: NextCore E2E (N trang, kiểm lại xanh) only when the run found no errors. When off, nothing is written to the repo.

#Endpoints

This port also serves MCP at /mcp for AI assistants; since 0.3.166 /mcp?lang=en returns English tool names and errors with NCB-xxxx codes, see MCP.

proxy accepts exactly the same formats as the interface. rows and cols must be given together; omit both ⇒ automatic grid. Profiles running Firefox return null for debugPort/wsEndpoint and cannot be arranged.

#Controlling a profile with Playwright

import { chromium } from 'playwright'

const API = 'http://127.0.0.1:19880/api/v1'
const H = { Authorization: `Bearer ${process.env.NCB_TOKEN}`, 'Content-Type': 'application/json' }

const p = await (await fetch(`${API}/profiles`, { method: 'POST', headers: H, body: JSON.stringify({ group: 'Farm máy 1' }) })).json()
const run = await (await fetch(`${API}/profiles/${p.id}/start`, { method: 'POST', headers: H })).json()

const browser = await chromium.connectOverCDP(run.wsEndpoint)
const page = browser.contexts()[0].pages()[0] ?? (await browser.contexts()[0].newPage())
await page.goto('https://homestaynextcore.org')
console.log(await page.title())

await browser.close() // disconnects CDP, the profile stays open
await fetch(`${API}/profiles/${p.id}/stop`, { method: 'POST', headers: H })

Puppeteer: puppeteer.connect({ browserWSEndpoint: run.wsEndpoint }).

#Sample recipes

Python: create profiles from a proxies.txt file (one proxy per line), then open the first 5 and arrange them in a grid:

import os, requests

API = "http://127.0.0.1:19880/api/v1"
H = {"Authorization": f"Bearer {os.environ['NCB_TOKEN']}"}

ids = []
for i, line in enumerate(open("proxies.txt", encoding="utf-8").read().split()):
    p = requests.post(f"{API}/profiles", headers=H, json={"name": f"Shop {i+1:02}", "group": "Farm máy 1", "proxy": line}).json()
    ids.append(p["id"])

for pid in ids[:5]:
    run = requests.post(f"{API}/profiles/{pid}/start", headers=H).json()
    print(pid, run["wsEndpoint"])

requests.post(f"{API}/arrange", headers=H, json={"ids": ids[:5]})

PowerShell: close every open profile (for the end of the day):

$H = @{ Authorization = "Bearer $env:NCB_TOKEN" }
$api = "http://127.0.0.1:19880/api/v1"
Invoke-RestMethod "$api/running" -Headers $H | ForEach-Object {
  Invoke-RestMethod "$api/profiles/$($_.profileId)/stop" -Method Post -Headers $H
}

Node: back up a whole group to D:\sao-luu (schedule it to run every night):

const API = 'http://127.0.0.1:19880/api/v1'
const H = { Authorization: `Bearer ${process.env.NCB_TOKEN}`, 'Content-Type': 'application/json' }
const list = await (await fetch(`${API}/profiles?group=Farm%20m%C3%A1y%201`, { headers: H })).json()
for (const p of list) {
  const r = await fetch(`${API}/profiles/${p.id}/backup`, { method: 'POST', headers: H, body: JSON.stringify({ password: process.env.NCB_BACKUP_PASS, dest: 'D:\\sao-luu' }) })
  console.log(p.name, (await r.json()).file ?? 'lỗi')
}