Merge pull request #406 from MiniMax-AI/stop-publishing-core-admin-port

Stop publishing Core's admin port on the host

Author: RyanLee-Dev

AGENTS.md

@@ -8,6 +8,8 @@ OpenAgentCore is protocol-first and modular. Core orchestrates operations that p
 
 OpenAgentCore is infrastructure. Change a boundary only when the existing protocol cannot express the behavior, and make that the smallest change that leaves the design intact. Hold the code to the standard of a careful, widely used open-source service.
 
+Keep it concise. Write elegant code that reuses existing code and standard SDKs as far as possible, and avoid redundant code. Expose nothing that does not need to be exposed: no port, route, command or setting without a caller.
+
 ### Protocols at every boundary
 
 - Each boundary between components has exactly one protocol: one code file (interface, wire types and validators) and one document. A protocol change edits both and every implementation in one change, reviewed on its own.

deploy/compose/ports.yaml

@@ -1,9 +1,6 @@
-# Host installation publishes Web and Core's loopback admin API for scripts on
-# the host. Hosting platforms omit this file and route to web:8080 themselves.
+# Host installation publishes Web. Hosting platforms omit this file and route
+# to web:8080 themselves.
 services:
   web:
     ports:
       - "${OAC_HOST:-127.0.0.1}:${OAC_WEB_PORT:-8080}:8080"
-  core:
-    ports:
-      - "127.0.0.1:8091:8091"

deploy/compose/test_compose.py

@@ -83,14 +83,14 @@ def test_public_url_can_be_configured_after_initial_startup(self):
                     {service: [item.get('target') for item in spec.get('volumes', [])]
                      for service, spec in self.compose['services'].items()})
 
-    def test_host_ports_publish_web_and_loopback_core(self):
+    def test_host_ports_publish_only_web(self):
         env = dict(os.environ, OAC_DATA_DIR='/tmp/oac-compose-fixture', OAC_HOST='0.0.0.0')
         hosted = json.loads(subprocess.check_output(
             ['docker', 'compose', '--env-file', os.devnull, '-f', str(self.compose_file),
              '-f', str(ROOT / 'deploy/compose/ports.yaml'), 'config', '--format', 'json'], env=env))
         published = {name: [(port.get('host_ip'), port['published']) for port in service.get('ports', [])]
                      for name, service in hosted['services'].items() if service.get('ports')}
-        self.assertEqual(published, {'web': [('0.0.0.0', '8080')], 'core': [('127.0.0.1', '8091')]})
+        self.assertEqual(published, {'web': [('0.0.0.0', '8080')]})
 
     def test_platform_network_injection_keeps_the_file_valid(self):
         # Dokploy isolated deployments attach a project network to every service.

deploy/install.dev.sh

@@ -103,11 +103,8 @@ pins = json.loads((root / "deploy/compose/smoke-pins.json").read_text())
     "RELEASE_BASE": pins["release_base"],
     "ARCHIVE_CHECKSUM": pins["archive_checksum"],
 }))
-# The release ports.yaml also publishes Core on 127.0.0.1:8091. A local trial
-# reaches Core through Web, so only Web is published.
-(dest / "ports.yaml").write_text(
-    "services:\n  web:\n    ports:\n      - \"${OAC_HOST:-127.0.0.1}:${OAC_WEB_PORT:-8080}:8080\"\n")
 PY
+cp "$repo_root/deploy/compose/ports.yaml" "$install_dir/ports.yaml"
 
 umask 077
 cat >"$install_dir/.env" <<EOF

deploy/install.sh

@@ -73,7 +73,12 @@ fi
 
 cleanup() {
   if [[ "$kept" != 1 && -d "$install_dir" ]]; then
-    (cd "$install_dir" && docker compose down --remove-orphans) >/dev/null 2>&1 || true
+    (
+      cd "$install_dir"
+      docker compose down --remove-orphans
+      # Containers own data/; remove it from a container as well.
+      if [[ -d data ]]; then docker compose run --rm --no-deps --entrypoint find init /data -mindepth 1 -delete; fi
+    ) >/dev/null 2>&1 || true
     rm -rf "$install_dir"
   fi
 }
@@ -104,7 +109,6 @@ umask 077
   docker compose pull
   docker compose create core
   docker compose cp core:/usr/local/bin/oac ./oac
-  chmod 755 ./oac
   docker compose up -d --wait
 )
 kept=1

docs/api/index.md

@@ -12,7 +12,7 @@ Core serves three namespaces. Each has one kind of caller and its own credential
 
 A credential used in another namespace gets 401: a Project API key on `/core/v1` or `/api/v1`, the Core key on `/v1` or `/api/v1`. How Projects and keys behave is in [Projects own assets](../concepts.md#projects-own-assets).
 
-**Routing.** Web forwards `/v1`, `/api/v1` and `/docs` to Core unchanged ([console server](../web/console-server.md)). A signed-in browser reaches `/core/v1` through Web, which adds the Core key. Operator scripts call `/core/v1` on `127.0.0.1:8091` ([script the Core API](../getting-started/operations.md#script-the-core-api)).
+**Routing.** Web forwards `/v1`, `/api/v1` and `/docs` to Core unchanged ([console server](../web/console-server.md)). A signed-in browser reaches `/core/v1` through Web, which adds the Core key. Operator scripts call `/core/v1` inside Core's network namespace on the Core host ([script the Core API](../getting-started/operations.md#script-the-core-api)).
 
 **API reference.** Core serves a read-only Swagger UI of the three namespaces at `/docs`, and the documents at `/docs/openapi.yaml`, `/docs/core.openapi.yaml` and `/docs/runtime.openapi.yaml`. No credential is required, and the page sends no API requests. Open it on the console origin, for example `http://localhost:8080/docs`. The browser loads Swagger UI from `unpkg.com`.
 

docs/configuration.md

@@ -46,7 +46,7 @@ To change it, point the reverse proxy at the new address first, then edit `OAC_P
 | `OAC_PUBLIC_URL` | `http://localhost:8080` | Origin applications, nodes, sandboxes and self-hosted executors use. Managed domain setup writes the HTTPS origin and recreates Core and Web |
 | `OAC_HOST` | `127.0.0.1` | Address published by `ports.yaml`. `install.sh` sets `0.0.0.0` |
 | `OAC_WEB_PORT` | `8080` | Host port of Web |
-| `COMPOSE_FILE` | `compose.yaml:ports.yaml` | The Compose files. `ports.yaml` publishes Web and Core's loopback admin API; hosting platforms omit it |
+| `COMPOSE_FILE` | `compose.yaml:ports.yaml` | The Compose files. `ports.yaml` publishes Web; hosting platforms omit it |
 | `OAC_LOG_LEVEL` | `info` | `debug`, `info`, `warn` or `error` |
 | `OAC_LOG_FORMAT` | `auto` | `auto`, `text` or `json` |
 | `OAC_LOG_ADD_SOURCE` | unset | `1` adds source locations |
@@ -135,7 +135,7 @@ The installer creates the installation directory, `~/.oac/core` by default, with
 | `data/state/` | Private Provider state, including E2B receipts | Core |
 | `.oac.lock` | The installation lock | Mutating `oac` commands |
 
-The Compose project is named `oac-<10 hex digits>`. Its services are `init`, `database`, `core` and `web`. Core applies database migrations when it starts. `web` serves the console and forwards `/v1` and `/api/v1` to Core, and it is the only service that publishes `OAC_WEB_PORT`. Host installs also publish Core's admin API on `127.0.0.1:8091`. No service receives a Docker socket. Apart from Docker's storage, nothing is written outside the installation directory.
+The Compose project is named `oac-<10 hex digits>`. Its services are `init`, `database`, `core` and `web`. Core applies database migrations when it starts. `web` serves the console and forwards `/v1` and `/api/v1` to Core, and it is the only service with a published port, `OAC_WEB_PORT`. No service receives a Docker socket. Apart from Docker's storage, nothing is written outside the installation directory.
 
 ## Appendix: Core environment without the installer
 

docs/getting-started/install-options.md

@@ -70,7 +70,7 @@ The installer saves no sandbox backend. After signing in, open **System** → **
 
 ## Listeners and access
 
-The default installation publishes Web on `--web-port` (8080) at `--host 0.0.0.0`. Core's admin API stays on `127.0.0.1:8091`. PostgreSQL stays private. `--host` is an IPv4 or IPv6 address, without a port, scheme or zone. Use a concrete server IP in the browser, not a wildcard.
+The default installation publishes Web on `--web-port` (8080) at `--host 0.0.0.0`. Core and PostgreSQL stay private. `--host` is an IPv4 or IPv6 address, without a port, scheme or zone. Use a concrete server IP in the browser, not a wildcard.
 
 `--public-url` sets `OAC_PUBLIC_URL`, the origin applications, nodes and executors use. Set it to the HTTPS origin your reverse proxy serves.
 

docs/getting-started/install.md

@@ -19,7 +19,7 @@ This page follows the default path. Every flag, existing reverse proxies and off
 - Linux amd64 and curl.
 - Docker Engine with Docker Compose 2.26.0 or newer (`docker compose version`).
 - An account that can run `docker` and write to its home directory. Ordinary users and root both work; the installer never calls sudo.
-- Free port 8080 for Web. Core's admin API uses `127.0.0.1:8091`. See [ports](./install-options.md#ports). Docker must be able to publish them; the installer does not change host policy.
+- Free port 8080 for Web. See [ports](./install-options.md#ports). Docker must be able to publish it; the installer does not change host policy.
 - For anything off this machine, the origin in `OAC_PUBLIC_URL` must be the address browsers, nodes and executors use. You can sign in on this machine first.
 
 The Core host needs no KVM; nodes that run microsandbox do.
@@ -40,7 +40,7 @@ The script downloads that release's Compose files, checks their SHA-256, and:
 
 1. checks Linux amd64, Docker Compose 2.26 or newer, and that the ports it will publish are free;
 2. creates the [installation directory](../configuration.md#installation-directory), `~/.oac/core`, writes `.env`, and copies the `oac` command out of the Core image;
-3. starts the services with Docker Compose. Web serves the console on port 8080 and forwards `/v1`, `/api/v1` and `/docs` to Core. Core's admin API stays on `127.0.0.1:8091`. PostgreSQL is not published.
+3. starts the services with Docker Compose. Web serves the console on port 8080 and forwards `/v1`, `/api/v1` and `/docs` to Core. Core and PostgreSQL are not published.
 
 It saves no sandbox backend, adds no node, creates no Project or key and makes no model request. It ends by printing the console address and how to read the Core key.
 

docs/getting-started/operations.md

@@ -20,7 +20,7 @@ docker compose -f ~/.oac/core/compose.yaml ps
 | `oac apply` | Runs `oac-core check-config`, then `docker compose up -d --wait`. A failed check changes no service |
 | `oac core-key [--show]` | Prints the Core key path, or the key itself with `--show` |
 | `oac rotate-core-key` | Replaces the Core key and restarts Core and Web |
-| `docker compose down --rmi all` | Removes the containers and images. Delete the installation directory afterwards |
+| `docker compose down` | Removes the containers. Data is kept; to delete it, [uninstall](#uninstall) |
 
 For a second installation, use its directory, such as `~/.oac/second`.
 
@@ -70,14 +70,15 @@ Keep it private. Web reads `data/secrets/web/core.key`. Core reads only its SHA-
 
 ### Script the Core API
 
-Run scripts on the Core host against Core's loopback port. This helper reads the key from its file, keeping it off the command line:
+Core publishes no host port. On the Core host, this helper runs `curl` in Core's network namespace and passes the key on stdin, keeping it off the command line:
 
 ```sh
-core() {  # core METHOD PATH [JSON body]
-  curl -fsS -X "$1" "http://127.0.0.1:8091/core/v1$2" \
-    -H @<(printf 'Authorization: Bearer %s\n' "$(~/.oac/core/oac core-key --show)") \
-    -H 'Content-Type: application/json' ${3:+-d "$3"}
-}
+core() (  # core METHOD PATH [JSON body]
+  cd ~/.oac/core
+  ./oac core-key --show | sed 's/^/Authorization: Bearer /' |
+    docker run -i --rm --network "container:$(docker compose ps -q core)" curlimages/curl \
+      -fsS -X "$1" "http://127.0.0.1:8091/core/v1$2" -H @- -H 'Content-Type: application/json' ${3:+-d "$3"}
+)
 ```
 
 | Task | Command |
@@ -136,11 +137,14 @@ Never prune Docker volumes or delete native harness history to make a retry pass
 ## Uninstall
 
 ```sh
-docker compose -f ~/.oac/core/compose.yaml down --rmi all --remove-orphans
-rm -rf ~/.oac/core
+cd ~/.oac/core
+docker compose down --remove-orphans
+docker compose run --rm --no-deps --entrypoint find init /data -mindepth 1 -delete
+docker compose down --rmi all
+cd && rm -rf ~/.oac/core
 ```
 
-`down` removes the containers and images. `rm` removes the installation directory. Do the first only when you mean to delete the data.
+The containers own `data/`, so the `init` image deletes its contents; then `down --rmi all` removes the images and `rm` removes the installation directory. Run these only when you mean to delete the data.
 
 All data goes with it: Projects and API keys, Session history, stored credentials and the Core key. To keep the data, stop the installation with `docker compose stop` instead, or [back it up](#back-up) first.
 
@@ -183,7 +187,7 @@ Mutating `oac` commands hold `.oac.lock`. If another command holds it, retry aft
 | Listener | Host installation | Behind a reverse proxy |
 | --- | --- | --- |
 | Web and the API | Web publishes `OAC_WEB_PORT` (8080) on `OAC_HOST` | Web publishes `OAC_WEB_PORT` on `OAC_HOST`. Your proxy should use `127.0.0.1` |
-| Core admin API | `127.0.0.1:8091`. Web forwards `/v1`, `/api/v1` and `/docs` | `127.0.0.1:8091`. Web forwards `/v1`, `/api/v1` and `/docs` |
+| Core | No published port. Web forwards `/v1`, `/api/v1` and `/docs` | No published port. Web forwards `/v1`, `/api/v1` and `/docs` |
 | PostgreSQL | No published port | No published port |
 
 Web signs administrators in with the Core key, checks the origin of every request, and forwards signed-in `/core/v1` requests to Core with the Core key, which stays on the server. It forwards `/v1` and `/api/v1` to Core unchanged, with the caller's own credential, serves only the non-secret node payload at `/node-install/`, and has no Docker or KVM access. Machine routes under `/api/v1` use their own enrollment and connection credentials. No service receives a Docker socket.