Test SPA & Policy APIs with Local Relay Server

Where this fits

You're building an agent that needs to interact with a SPA frontend or its admin/policy API, but you don't want to depend on a remote deployment for every test. Instead, you want a local relay server that mimics the production setup—serving the embedded frontend and exposing the policy endpoints. This skill gives you the exact steps to build and run the portal-tunnel relay-server locally, so you can validate HTTP flows, browser interactions, and policy changes in a controlled environment.

Why agents benefit

• Deterministic local testing: Agents can spin up the relay server with a single command, ensuring the frontend and API are available at a known address (https://localhost:4017) without external dependencies.
• Live-editable frontend: With PORTAL_FRONTEND_DIR set, the SPA is served from a directory with caching disabled—agents can modify assets and see changes immediately, enabling rapid iteration.
• Full policy API coverage: The skill documents GET/POST /api/policy with Bearer token auth, letting agents verify policy updates (e.g., approval mode, UDP/TCP port settings) against a real endpoint.
• Self-signed TLS handling: Agents learn to use curl -k and manage the ADMIN_TOKEN environment variable, avoiding common pitfalls when testing secure local services.
• Port flexibility: The skill highlights the need to override --sni-port (default 443) to an unprivileged port, preventing binding failures—critical for agent automation in sandboxed environments.

Practical scenarios

Scenario 1: Testing policy API changes in CI

An agent runs a CI job that builds the relay server, starts it with a temporary ADMIN_TOKEN, and then sends a series of POST /api/policy requests to verify that changes to approval_mode or udp.max_leases are correctly persisted and returned via GET /api/policy. The local server makes these assertions fast and repeatable.

Scenario 2: Browser-based SPA smoke test

An agent uses a headless browser to load the SPA from https://localhost:4017, checks that the landing page renders, and then exercises a user flow. Because the frontend is served from a live-editable directory, the agent can swap in test fixtures or mock data without rebuilding.

Scenario 3: Debugging startup errors

When the server fails to start because frontend assets are missing, the agent reads the error message and runs make build-frontend automatically. This skill's build instructions give the agent the exact sequence to recover from common setup issues.

Add it to your agent workflow

Install the skill with:

npx skills add gosuda/portal-tunnel --skill testing-relay-server

Then, in your agent's code, follow the README to build and run:

export PATH=$PATH:/usr/local/go/bin
make build-frontend
make build-server-bin
ADMIN_TOKEN=testtoken IDENTITY_PATH=/tmp/pt-id ./bin/relay-server serve --sni-port 8443

After that, the API and frontend are available at https://localhost:4017 (use curl -k). For more context, see the skill page at https://www.openagentskill.com/skills/gosuda-testing-relay-server.

Compare before adopting

Before integrating this skill, compare it with alternatives like running the production server in a container or mocking the API. Check the repository's freshness (last commit, open issues), the clarity of the build steps, and whether the skill matches your agent's testing workflow. Also verify that the Go and Node version requirements align with your environment.

Why it is worth tracking

This skill is backed by a small but active repository (263 stars) and provides precise, version-aware instructions—a good sign of maintenance. As your agent grows to handle more complex frontend or API testing, having a reliable local relay server becomes essential. Track it now to stay ready for scenarios where you need to validate policy changes or SPA behavior without external dependencies.