> ## Documentation Index
> Fetch the complete documentation index at: https://docs.getcore.me/llms.txt
> Use this file to discover all available pages before exploring further.

# Gateway

> Run a local agent on your machine that connects CORE to your development environment

## 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](/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:

<CardGroup cols={2}>
  <Card title="Remote coding from your phone" icon="mobile">
    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.
  </Card>

  <Card title="Authenticated browser automation" icon="browser">
    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.
  </Card>

  <Card title="Live terminal in the webapp" icon="terminal">
    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.
  </Card>

  <Card title="Scheduled local actions" icon="clock">
    "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.
  </Card>
</CardGroup>

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`](https://github.com/RedPlanetHQ/core/blob/main/packages/gateway-protocol/README.md).

***

## Install (quick path)

For the full step-by-step including Tailscale / ngrok install, see [Gateway Setup](/gateway/setup).

<Steps>
  <Step title="Install the CLI">
    ```bash theme={null}
    npm install -g @redplanethq/corebrain
    corebrain login
    ```
  </Step>

  <Step title="Run the wizard">
    ```bash theme={null}
    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](/gateway/tunnels) or the [Setup runbook](/gateway/setup) 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](/gateway/tunnels).
    * **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.
  </Step>

  <Step title="Register the gateway with a tunnel">
    Native installs need a tunnel before the cloud can reach them:

    ```bash theme={null}
    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.**
  </Step>

  <Step title="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.

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

  <Step title="Verify">
    ```bash theme={null}
    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
    ```
  </Step>
</Steps>

### 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

[![Deploy on Railway](https://railway.com/button.svg)](https://railway.com/deploy/core-gateway)

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](/gateway/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](/gateway/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](/gateway/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.

```bash theme={null}
# 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](/gateway/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](/gateway/setup): linear copy-paste guide from zero to connected.
* [Tunnels](/gateway/tunnels): Tailscale Funnel and ngrok deep-dive.
* [Browser](/gateway/browser), [Coding](/gateway/coding), [Exec](/gateway/exec): per-capability references.
* [Gateway protocol README](https://github.com/RedPlanetHQ/core/blob/main/packages/gateway-protocol/README.md): full HTTP / WebSocket reference.