Angel Codex Loopback

Safe macOS LaunchAgent tooling for running codex app-server on a localhost-only WebSocket endpoint.

This project helps developers run Codex automation locally for tools such as Angel/OpenClaw without exposing the app-server to the public internet or the local network.

Why this exists

codex app-server can be useful for local coding workflows, but binding developer automation services to broad network interfaces is risky. This repository provides a small, auditable macOS setup that:

• starts Codex app-server through a user LaunchAgent
• binds only to 127.0.0.1
• exposes health checks for quick verification
• includes start, stop, status, test, install, and uninstall scripts
• avoids storing tokens, SSH keys, or credentials in the repository

Default endpoint:

ws://127.0.0.1:18790

Health checks:

http://127.0.0.1:18790/readyz
http://127.0.0.1:18790/healthz

Requirements

• macOS
• Codex installed at /Applications/Codex.app/Contents/Resources/codex
• launchctl, plutil, curl, and lsof from macOS

Quick start

git clone https://github.com/mrakaadith/angel-codex-loopback.git
cd angel-codex-loopback
./scripts/install-launchagent.sh
./scripts/status.sh

Commands

Install and start the LaunchAgent:

./scripts/install-launchagent.sh

Start an installed LaunchAgent:

./scripts/start.sh

Stop the LaunchAgent:

./scripts/stop.sh

Check service status, listener binding, and readiness:

./scripts/status.sh

Run simple health checks:

./scripts/test.sh

Uninstall the user LaunchAgent:

./scripts/uninstall-launchagent.sh

Configuration

The scripts support environment overrides:

PORT=18791 ./scripts/install-launchagent.sh
CODEX_BIN=/path/to/codex ./scripts/install-launchagent.sh
WORKING_DIRECTORY="$HOME/Documents" ./scripts/install-launchagent.sh

By default, HOST is 127.0.0.1. Keep it that way unless you have a clear network security model.

Files

• launchagents/com.openai.codex.app-server.ws-loopback.plist.template: macOS LaunchAgent template.
• scripts/common.sh: shared configuration and helper functions.
• scripts/install-launchagent.sh: renders and installs the LaunchAgent.
• scripts/start.sh: starts or restarts the service.
• scripts/stop.sh: stops the service.
• scripts/status.sh: prints LaunchAgent state, port listener, and readiness.
• scripts/test.sh: checks /readyz and /healthz.
• scripts/uninstall-launchagent.sh: stops and removes the LaunchAgent.

Security model

The default setup is intentionally loopback-only:

ws://127.0.0.1:18790

Do not change the host to 0.0.0.0 unless you also enforce strict firewall rules and understand who can reach the service.

If another machine or VM needs access, prefer an SSH tunnel or a tightly restricted private network binding.

Never commit:

• private SSH keys
• GitHub tokens
• OpenAI API keys
• local credentials
• generated logs containing sensitive data

Verify manually

launchctl print "gui/$(id -u)/com.openai.codex.app-server.ws-loopback"
lsof -nP -iTCP:18790 -sTCP:LISTEN
curl -f http://127.0.0.1:18790/readyz
curl -f http://127.0.0.1:18790/healthz

Expected listener binding:

TCP 127.0.0.1:18790 (LISTEN)

License

MIT