Gateway

What is the Gateway?

The Gateway is a local Fastify HTTP server (default port 7787) bundled into the @redplanethq/corebrain CLI. It runs on your laptop, on a Docker host you control, or on Railway, and exposes your browser, coding agents, shell, and a registered set of folders to CORE over an authenticated HTTP + WebSocket API. CORE never touches your machine directly. Every action CORE takes on your environment, opening a tab, running a test, editing a file, spawning Claude Code, goes through this gateway. It’s the bridge between CORE’s cloud intelligence and your local environment.

Looking for the runbook? See Gateway Setup for a linear, copy-pasteable guide. This page is the conceptual overview.

Why connect a Gateway?

Without a gateway, CORE is a memory and reasoning layer in the cloud. With one, CORE can act on your actual machine and accounts. Concrete examples:

Remote coding from your phone

Message CORE on WhatsApp, “Fix the auth timeout in the API.” CORE spawns Claude Code on your gateway, pulls context from memory, and works on the bug while you’re on the train.

Authenticated browser automation

Log in to LinkedIn once on your personal Playwright profile. CORE can research leads, scrape your dashboards, or drive a checkout flow without you re-authenticating.

Live terminal in the webapp

Watch a coding session stream into the webapp’s terminal pane in real time, attach, type, and resize, with a Chrome DevTools-style live view of the browser running alongside.

Scheduled local actions

“Every morning at 9am, run the test suite and summarize failures.” A reminder fires exec_command against your repo and posts the result back to your channel of choice.

The gateway is what turns CORE from “an LLM that remembers” into “an assistant that gets things done on your stack.”

What does it expose?

The gateway advertises a manifest of capability slots. Each slot can be turned off in corebrain gateway config; disabled slots aren’t just hidden, their HTTP routes are not registered.

Slot	Tools exposed	Use this for
Browser	`browser_navigate`, `browser_snapshot`, `browser_click`, `browser_fill`, `browser_type`, `browser_press_key`, `browser_select_option`, `browser_screenshot`, `browser_scroll`, `browser_go_back`, `browser_go_forward`, `browser_wait_for`, `browser_evaluate`, `browser_create_session`, `browser_list_sessions`, `browser_delete_session`, `browser_close_session`, `browser_close_all`	Authenticated scraping, form automation, dashboard reads, live browser viewing in the webapp
Coding	`coding_ask`, `coding_read_session`, `coding_list_sessions`, `coding_search_sessions`, `coding_list_agents`, `coding_close_session`, `coding_close_all`	Spawn or resume Claude Code / Codex sessions remotely; isolated git worktrees for autonomous work
Exec	`exec_command`	Shell commands gated by allow/deny patterns and folder scopes
Files	`files_read`, `files_write`, `files_edit`, `files_glob`, `files_grep`	File reads, edits, glob, ripgrep, all scoped to registered folders
Utils (always on)	`sleep`	Pause between polling tool calls

In addition the gateway exposes a few HTTP routes the webapp uses directly:

GET /manifest: full capability manifest the webapp reads on every poll.
WS /api/coding/coding_xterm_session: terminal stream for coding sessions and the per-gateway shell.
WS /api/browser/cdp/:session: Chrome DevTools Protocol proxy for the live browser viewer.
POST /api/folders/local, POST /api/folders/git, DELETE /api/folders/:idOrName: folder management.
POST /api/shell/spawn: general-purpose PTY for the shell tab.

Every request requires Authorization: Bearer gwk_<key>. There is no localhost bypass, the same flow applies whether the gateway is on 127.0.0.1, behind a tunnel, or on a public Docker host. For the protocol details and a route-by-route reference, see packages/gateway-protocol/README.md.

Install (quick path)

For the full step-by-step including Tailscale / ngrok install, see Gateway Setup.

Install the CLI

npm install -g @redplanethq/corebrain
corebrain login

Run the wizard

corebrain gateway setup

Pick where the gateway should run:

Native: this machine. Installs a launchd (macOS) / systemd (Linux) service and gives full access to local browser, shells, and folders. Native gateways listen on 127.0.0.1 and need a tunnel (Tailscale or ngrok) before CORE’s cloud can reach them. See Tunnels or the Setup runbook for the tunnel install steps you must run first.
Docker: local or remote Docker host. Drops docker-compose.yaml + .env into ~/.corebrain/gateways/<name>/ (templates fetched from main so they stay in sync), runs docker compose up -d, and optionally exposes via Tailscale Funnel.
Railway: managed cloud. Detects (or installs) the Railway CLI, runs railway init + railway deploy -t core-gateway, and provisions a public domain.

For docker / railway the wizard also prompts (optional) for CLAUDE_CODE_OAUTH_TOKEN, OPENAI_API_KEY, and GITHUB_TOKEN so the coding + git slots work out of the box.

Native installs need a tunnel before the cloud can reach them:

corebrain gateway register --tunnel tailscale
# or
corebrain gateway register --tunnel ngrok
# or, bring your own URL:
corebrain gateway register --tunnel none --baseUrl https://gateway.example.com

The CLI prints a baseUrl and a securityKey (gwk_...). The raw key is shown exactly once.

Paste URL + key into the CORE app

This is the step that links the gateway to your workspace. Without it, the gateway is reachable but CORE doesn’t know it exists.

Open https://app.getcore.me (or your self-hosted instance).
Sidebar → Gateways → + New gateway.
Paste the Base URL and the Security key from the CLI output.
Click Submit. The gateway should show Connected within a few seconds.

Verify

corebrain gateway list           # all gateways your workspace knows about
corebrain gateway status         # native gateway on this machine
corebrain gateway status <id>    # any gateway by id

Skipping the wizard

corebrain gateway setup --kind native|docker|railway jumps straight into one path. Useful for headless installs and CI.

One-click Railway deploy

Railway prompts for the env vars, provisions the service + public domain, and the security key appears in the deploy logs on first boot. You still need to paste the URL + key into Sidebar → Gateways in the CORE app (Step 4 above). The required env vars:

COREBRAIN_API_URL: your CORE instance URL (e.g. https://app.getcore.me)
COREBRAIN_API_KEY: a Personal Access Token from the webapp
COREBRAIN_GATEWAY_NAME: name shown in the webapp
COREBRAIN_GATEWAY_SECURITY_KEY: (optional) leave empty and Railway will auto-generate one

Gateway Commands

Top-level (work on any gateway)

Command	Use this when
`corebrain login`	First-time setup, or after rotating your Personal Access Token.
`corebrain gateway setup`	Spinning up a new gateway from scratch (interactive wizard).
`corebrain gateway setup --kind native\|docker\|railway`	Headless install / CI / scripted setup.
`corebrain gateway list`	Checking which gateways your CORE workspace knows about, across all your machines.
`corebrain gateway status`	Quick health check of the native gateway running on this machine.
`corebrain gateway status <id>`	Inspecting any gateway’s manifest, slot config, and tunnel state by id.

Native gateway lifecycle (this machine only)

Command	Use this when
`corebrain gateway register`	After `setup`, to generate the URL + security key and (optionally) start a tunnel. Also used to rotate the key if it leaks or is lost.
`corebrain gateway register --tunnel tailscale\|ngrok\|none`	Picking how the gateway is exposed. `none` means you supply your own URL.
`corebrain gateway start`	Installing the gateway as a system service so it boots with the machine.
`corebrain gateway start --foreground`	Debugging the gateway attached to your terminal (Docker / ad-hoc).
`corebrain gateway stop`	Shutting the service down and tearing down the managed tunnel.
`corebrain gateway restart`	Picking up a config change or recovering from a hung process.
`corebrain gateway config`	Toggling slots (browser / coding / exec / files), changing exec patterns, registering folders.

The folder, browser, coding, and exec command groups configure the native gateway’s slots and only run when one is set up on this machine. They print a redirect to corebrain gateway setup otherwise.

Folders and scopes

Command	Use this when
`corebrain folder add <path>`	Granting the gateway access to a directory. Scopes default to `files,coding,exec`.
`corebrain folder add <path> --scopes coding,exec`	Pinning narrower scopes (e.g. read-only, or coding-only).
`corebrain folder list`	Auditing what the gateway is allowed to touch.

Browser (Playwright)

Command	Use this when
`corebrain browser install`	First-time install of the Playwright Chromium binary (or refreshing it).
`corebrain browser create-profile <name>`	Creating a new persistent identity (cookies, localStorage). Max 5 profiles.
`corebrain browser create-session <name> --profile <profile>`	Binding a named task (e.g. `linkedin`) to a profile. Max 10 sessions.
`corebrain browser open <session> --headed`	Logging in manually so the profile captures auth state.
`corebrain browser set-browser brave\|chrome\|default\|custom`	Switching the executable used by Playwright.
`corebrain browser status`	Inspecting session list and current browser binary.

See Browser for the full reference.

Coding (Claude Code, Codex)

Command	Use this when
`corebrain coding setup`	Adding a coding agent (claude-code or codex-cli) and logging it in.
`corebrain coding setup --default claude-code`	Setting which agent runs when callers don’t specify one.

See Coding for the full reference and the coding_ask payload shape.

Exec (shell)

Command	Use this when
`corebrain exec config`	Editing the allow / deny pattern list (e.g. `Bash(git )`, `Bash(npm run )`).

See Exec for the security model.

Folders and scopes

Folders are registered paths the gateway is allowed to touch. Each folder carries one or more scopes:

Scope	Allows
`files`	`files_*` tools and the file-system browser in the webapp
`coding`	`coding_ask` / interactive sessions targeting paths inside it
`exec`	`exec_command` working dirs

When at least one folder is registered, a request that names a path outside any matching-scope folder is rejected with FOLDER_SCOPE_DENIED / PATH_OUTSIDE_FOLDER. With zero folders registered the gateway runs in permissive first-run mode.

# Register the current directory with all three scopes
corebrain folder add .

# Or pin scopes
corebrain folder add /Users/me/repos/api --scopes coding,exec

# Or clone a repo through the API (Docker hosts)
curl -X POST $GATEWAY/api/folders/git \
  -H "Authorization: Bearer $KEY" \
  -d '{"url":"https://github.com/RedPlanetHQ/core.git"}'

Security

Bearer-only auth. The gateway stores sha256(securityKey) on disk; the webapp encrypts the raw key at rest. Constant-time comparison; no localhost bypass.
Slot toggles. Disabled slots are not just hidden, their HTTP routes are not registered, so a leaked key still cannot hit them.
Folder scopes. Coding / exec / files tools are pinned to registered folders with the matching scope.
Exec patterns. exec_command validates each command against allow / deny globs (Bash(<glob>)) plus a built-in deny list for unsafe primitives.
Browser profiles. Stored locally; auth state never leaves your machine.
Tunnels for native gateways. Native installs always need HTTPS to be reachable from CORE’s cloud. Use Tailscale Funnel, ngrok, or your own reverse proxy. See Tunnels.

All traffic between CORE and the gateway is authenticated; use HTTPS or a tunnel for non-loopback deployments.

Environment Variables (Headless / Docker)

When running without an interactive corebrain login flow, the gateway reads:

Variable	Purpose
`COREBRAIN_API_URL`	CORE instance URL
`COREBRAIN_API_KEY`	Personal access token
`COREBRAIN_GATEWAY_NAME`	Gateway name shown in the webapp
`COREBRAIN_GATEWAY_DESCRIPTION`	Optional gateway description
`COREBRAIN_GATEWAY_SECURITY_KEY`	Bearer key. Auto-generated and printed once if absent.
`COREBRAIN_GATEWAY_HTTP_PORT`	Port to listen on (default `7787`)
`COREBRAIN_DEFAULT_WORKSPACE`	Auto-registered as a folder with `files,coding,exec` scopes
`COREBRAIN_DEPLOY_MODE`	`native` or `docker`, surfaces in the manifest for UI gating
`ANTHROPIC_API_KEY`	Lets `claude-code` skip OAuth
`OPENAI_API_KEY`	Lets `codex-cli` skip OAuth
`GITHUB_TOKEN`	Used by `POST /api/folders/git` to clone private repos

Bootstrap is idempotent. Values you set manually inside the container are never overwritten.

Where next?

Gateway Setup runbook: linear copy-paste guide from zero to connected.
Tunnels: Tailscale Funnel and ngrok deep-dive.
Browser, Coding, Exec: per-capability references.
Gateway protocol README: full HTTP / WebSocket reference.

Overview

Deployment

Capabilities

LLM Proxy

Networking

Integrations

Load

TUI

Search

What is the Gateway?

Why connect a Gateway?

Remote coding from your phone

Authenticated browser automation

Live terminal in the webapp

Scheduled local actions

What does it expose?

Install (quick path)

Skipping the wizard

One-click Railway deploy

Gateway Commands

Top-level (work on any gateway)

Native gateway lifecycle (this machine only)

Folders and scopes

Browser (Playwright)

Coding (Claude Code, Codex)

Exec (shell)

Folders and scopes

Security

Environment Variables (Headless / Docker)

Where next?

​What is the Gateway?

​Why connect a Gateway?

Remote coding from your phone

Authenticated browser automation

Live terminal in the webapp

Scheduled local actions

​What does it expose?

​Install (quick path)

​Skipping the wizard

​One-click Railway deploy

​Gateway Commands

​Top-level (work on any gateway)

​Native gateway lifecycle (this machine only)

​Folders and scopes

​Browser (Playwright)

​Coding (Claude Code, Codex)

​Exec (shell)

​Folders and scopes

​Security

​Environment Variables (Headless / Docker)

​Where next?

What is the Gateway?

Why connect a Gateway?

What does it expose?

Install (quick path)

Skipping the wizard

One-click Railway deploy

Gateway Commands

Top-level (work on any gateway)

Native gateway lifecycle (this machine only)

Folders and scopes

Browser (Playwright)

Coding (Claude Code, Codex)

Exec (shell)

Folders and scopes

Security

Environment Variables (Headless / Docker)

Where next?