Give automated clients a narrow public API without publishing the controls meant for administrators
AI agents need callable endpoints, but they rarely need the dashboard, configuration pages, debug tools, or privileged controls that accompany a local application. This guide explains how to separate a machine-facing API from the human-facing admin interface, apply authentication and authorization at the application layer, verify the boundary locally, and then expose only the intended API through a Localtonet HTTP tunnel. The tunnel supplies public connectivity while your application remains responsible for deciding who may call each operation.
📋 What's in this guide
Why agents and administrators need different access boundaries
A local development application often combines several surfaces. It may have a browser dashboard, an administrative API, a health endpoint, debug pages, and a set of business operations. That arrangement can be convenient while every request originates from the same machine. It becomes risky when the entire listener is assigned a public address merely because an agent needs to call one or two operations.
An automated client is not just a faster human user. It can retry requests, invoke operations in an unexpected order, follow incorrect model-generated instructions, or continue using a credential after the original task has finished. It may also be operated through an orchestration system that stores prompts, tool definitions, request traces, and secrets differently from a browser-based application.
The correct design objective is therefore not simply to expose localhost. It is to expose the smallest useful machine interface while leaving administrative functions outside that interface. A public URL is a transport mechanism. It is not an authorization decision.
The strongest practical separation is usually two independently reachable listeners or services. One listener serves the narrow agent API. The other serves the admin UI and its privileged routes. The Localtonet tunnel points only to the agent listener. The admin listener remains bound to a private interface appropriate to the deployment, such as the loopback interface when administration happens on the same machine.
A second option is to place both surfaces in one application while enforcing a strict route boundary. For example, machine operations could live under a dedicated API prefix while administrative routes remain elsewhere. This can work, but the public listener still receives requests for both route families unless a separate frontend or listener rejects the admin paths. A mistake in routing, middleware order, static-file serving, or fallback behavior can expose more than intended.
A third option is to expose the complete application and rely only on login protection. This is the least desirable arrangement for agent access. Authentication may prevent successful use of an admin page, but the page, route behavior, metadata, login mechanism, and attack surface are still publicly reachable. It also makes it easier to accidentally issue an agent credential with broader privileges than intended.
| Architecture | Isolation | Operational tradeoff |
|---|---|---|
| Separate API and admin listeners | The tunnel targets only the machine API listener | Requires maintaining a clear service or listener boundary |
| One listener with strict route separation | Application middleware rejects access outside the agent route set | A routing or middleware error can weaken the boundary |
| Entire application behind one public endpoint | Depends mainly on login and route authorization | Publishes unnecessary administrative attack surface |
Localtonet forwards traffic to the local target you configure. Your application must authenticate the caller, validate its request, authorize the requested operation, and reject everything else. Do not treat possession of the public URL as proof of identity or permission.
Define the machine API before making it public
Start by writing down the exact tasks the agent must perform. Avoid exposing a generic administrative endpoint when a purpose-built operation can express the task more safely. An agent that needs to create a draft record should receive a create-draft operation, not unrestricted database commands or access to a general settings controller.
Build an explicit route inventory
Classify every route served by the application. A useful inventory distinguishes public machine operations, private administrative operations, authentication endpoints, health checks, static assets, diagnostics, and undocumented framework routes. The public agent listener should serve only the first category and any deliberately designed readiness endpoint.
Use an allowlist rather than trying to enumerate everything that should be blocked. With an allowlist, a newly added application route remains unavailable until someone intentionally includes it in the agent surface. A denylist can fail in the opposite direction because new routes may become reachable by default.
Public agent surface
/agent-api/tasks
/agent-api/tasks/{task-id}
/agent-api/actions/{action-name}
Private human surface
/admin
/settings
/users
/credentials
/debug
/logsThese paths are illustrative architecture examples rather than Localtonet configuration requirements. Choose names that fit your application, and verify the actual route table generated by your framework. Pay particular attention to wildcard handlers, single-page application fallbacks, automatic API documentation, development exception pages, and static-file directories.
Prefer task-oriented operations
Agent tools should have narrow inputs and predictable effects. A broad endpoint such as “execute action” can quietly become equivalent to administrative access if it accepts arbitrary action names or unvalidated parameters. Narrow endpoints make authorization, input validation, logging, and review easier.
Separate read operations from state-changing operations. A credential that only needs to retrieve status should not also be able to delete, approve, publish, or modify data. For sensitive workflows, separate preparation from commitment. An agent can prepare a change and receive a preview, while a human or separately authorized service approves the final action.
Return structured and bounded responses
Machine callers benefit from stable status codes, explicit error objects, documented field types, and bounded response sizes. Avoid returning internal stack traces, source paths, database errors, environment details, or administrative links. Errors should tell the caller how to correct an input without revealing internal implementation details.
Validate request bodies against a strict schema. Reject unknown fields when practical, constrain string and collection sizes, validate identifiers, and normalize data before it reaches privileged code. Tool descriptions and model instructions are usability aids, not security controls. The server must enforce every rule even when the agent ignores its tool schema.
Keep health information minimal
A readiness route can help distinguish an unavailable tunnel from a failed application, but it should reveal as little as possible. A simple ready or not-ready result is often sufficient. Detailed dependency status, software versions, configuration dumps, and internal hostnames belong in private monitoring rather than the public machine interface.
The API and admin UI may run in one process if the framework can provide a reliable listener and middleware boundary. What matters is that the local target selected for the tunnel cannot serve administrative content. Test that property directly instead of assuming a route prefix provides isolation.
Security controls for an agent-facing API
Once the route boundary is clear, protect it as a machine-to-machine interface. The appropriate mechanisms depend on the application and identity system, but the control objectives remain consistent: establish identity, constrain authority, limit abuse, make repeated operations safe, record meaningful events, and provide a fast revocation path.
Use dedicated machine credentials
Do not give an agent an administrator's browser password, session cookie, or personal access credential. Create a dedicated identity for each agent, integration, environment, or deployment where practical. Separate identities allow one integration to be disabled without interrupting every other caller.
Credentials should be delivered through the agent runtime's supported secret-management mechanism rather than embedded in prompts, source files, tool descriptions, URLs, or logs. Never place a bearer credential in a query string. URLs are commonly retained in histories, telemetry, proxies, and diagnostics.
The application should verify credentials on every protected request. It should also distinguish an invalid credential from an authenticated identity that lacks permission, while ensuring public error responses do not disclose unnecessary account information.
Authorize capabilities, not just identities
Authentication answers which identity made the request. Authorization answers whether that identity may perform this operation on this resource. Both checks are necessary.
Define scopes or capabilities around real tasks. Examples might include reading task status, creating drafts, submitting a specific job type, or canceling jobs created by the same identity. Avoid a single all-powerful “agent” role if the callers perform different work.
Resource-level checks are as important as route-level checks. Permission to retrieve one project should not imply permission to retrieve every project. If an agent acts on behalf of a human, the server should enforce the delegated boundary rather than trusting a user identifier supplied in the request body.
Set request and resource limits
Automated callers can produce bursts through retries, loops, parallel tool calls, or malformed plans. Apply limits appropriate to the operation and the capacity of the local service. Relevant controls can include request-rate limits, concurrent-operation limits, payload-size limits, execution deadlines, pagination limits, and caps on the number of resources changed by one request.
There is no universal safe number. Base thresholds on expected workload, the cost of each operation, and recovery behavior. Expensive operations may need tighter limits than read-only status checks. When rejecting excess traffic, return a stable machine-readable error so the client can stop or back off instead of retrying aggressively.
Design state changes for retries
Network failures create ambiguity. A client may submit a request, lose the response, and retry without knowing whether the first attempt succeeded. For operations that create charges, send messages, modify records, or launch work, support an idempotency mechanism or an equivalent application-level deduplication strategy.
Bind the idempotency record to the authenticated identity and normalized operation input. Reusing the same key for a different payload should fail rather than silently applying a different action. Retain deduplication state for a period that matches the client's realistic retry window, and document that behavior for the agent developer.
Not every method is automatically safe merely because it uses a particular HTTP verb. Verify the actual application behavior. A status request should not mutate state, and a repeated update should have a defined result.
Record security-relevant events
Audit records should help answer who called which operation, when it happened, what resource was targeted, whether authorization succeeded, and what high-level result occurred. Include a request or correlation identifier so related events can be traced across the application.
Avoid recording raw credentials, complete authorization headers, private prompt content, or sensitive payload fields. Logging everything can create a second security problem. Prefer structured records with deliberate redaction and an established retention policy.
Plan revocation before exposure
Know how to disable an agent identity, rotate its credential, remove a capability, stop the Localtonet tunnel, and invalidate pending work. These controls solve different problems. Stopping the tunnel removes the public route while it is stopped, but it does not invalidate a leaked application credential. Revoking a credential blocks that identity, but it does not close an accidentally exposed administrative route.
| Control | Risk addressed | Where it belongs |
|---|---|---|
| Machine authentication | Anonymous or impersonated callers | Application or approved identity layer |
| Scoped authorization | Authenticated callers exceeding their role | Application authorization logic |
| Input validation | Malformed, oversized, or unsafe requests | API boundary before business logic |
| Rate and concurrency limits | Loops, bursts, retries, and resource exhaustion | Application or controlled API layer |
| Idempotency controls | Duplicate effects after retries | State-changing application operations |
| Audit logging | Untraceable access and weak incident investigation | Application and supporting observability systems |
| Tunnel stop or deletion | Continued public reachability | Localtonet tunnel lifecycle |
Verify the isolation locally before creating a tunnel
Public exposure should be the final integration step, not the first test. Run the application locally and confirm that the dedicated API listener behaves correctly from the same device that will run the Localtonet client.
The following checks are technology-neutral. Adapt the exact request syntax to your authentication mechanism and operating environment. Replace placeholders with values from your own local application. Do not paste real credentials into shell history on a shared machine.
Start the agent API and private admin surface
Confirm which local IP address and port belong to each listener. The port selected later in Localtonet must be the agent API port, not the admin UI port.
Test an intentionally public API route
Send a valid authenticated request directly to the local agent listener. Confirm that the response contract, authorization scope, and audit record are correct.
Test unauthenticated and unauthorized requests
Verify that missing, invalid, expired, and insufficiently scoped credentials fail before protected application logic runs.
Request administrative paths through the API listener
Try the real admin, settings, credential, debug, documentation, and static-asset paths used by the application. They should not return administrative content from the machine listener.
Exercise limits and duplicate handling
Test oversized input, invalid fields, repeated state-changing requests, concurrency behavior, and application-defined limits in a controlled environment.
Review logs for secret leakage
Confirm that credentials and sensitive payload fields are redacted while identity, operation, resource, result, timestamp, and correlation information remain useful.
A generic local request might use a structure like the following. The URL, header, route, and credential format are placeholders. Use only the authentication mechanism implemented by your application.
curl -i \
-H "Authorization: Bearer REPLACE_WITH_A_TEST_CREDENTIAL" \
-H "Content-Type: application/json" \
-X POST \
--data '{"operation":"approved-test-value"}' \
"http://LOCAL_API_ADDRESS/agent-api/tasks"Then test a private path against the same listener:
curl -i "http://LOCAL_API_ADDRESS/admin"The important result is not a particular status code mandated by Localtonet. It is that the agent listener does not serve the admin UI or execute administrative behavior. Choose consistent status codes that fit your application and avoid redirects that unexpectedly lead automated clients to login pages.
A route may appear private in source code while still being reachable through a framework fallback, reverse-proxy rule, static-file handler, or development-only component. Send real requests to every sensitive path through the exact local IP address and port that the tunnel will target.
Expose only the agent API with a Localtonet HTTP tunnel
After the local security boundary passes testing, use a Localtonet HTTP tunnel to provide remote connectivity. Our client runs on a device that can reach the local API and establishes an outbound connection to a Localtonet relay server. This means the workflow does not require inbound router port forwarding, a public IP address, VPN setup, or inbound firewall changes.
An HTTP tunnel points to a local IP address and port. HTTP tunnels can use Random Sub Domain, Custom Sub Domain, or Custom Domain process types, and each serves the configured content at a public HTTPS address. Availability and configuration details can vary, so use the options currently presented in the dashboard. Exact custom-domain DNS instructions should be taken from current documentation rather than inferred.
The documented lifecycle is important: creating a tunnel does not mean it is running. It must be started, and the selected Localtonet client device must remain connected. The tunnel is available only while that client is connected and the tunnel is running.
Install and run the Localtonet client
Install the Localtonet application on the device that can reach the agent API listener. Keep the client running for as long as remote access is required. Current installation choices should be obtained from our platform because commands and packages can vary by operating system and client version.
Authenticate or select the device
Use the device-specific auth token associated with the client that will run the tunnel. Treat the token as a secret. Do not place it in source code, examples, agent prompts, screenshots, or shared logs.
Select an available relay server
Choose from the server or region values currently available in the Localtonet dashboard. Do not copy a server code from an unrelated tutorial because availability can change by plan, client version, region, or deployment.
Create the HTTP tunnel configuration
Select the appropriate HTTP process type and enter the local IP address and port of the dedicated agent API listener. Verify again that these values do not point to the administrative listener.
Start the tunnel
Use the Start control after reviewing the target. Once the tunnel is running and the selected client is connected, use the assigned public HTTPS address for remote testing.
Stop or delete the tunnel when appropriate
Stop the tunnel when temporary testing is complete. Delete it when the configuration is no longer needed. Stopping or deleting public access does not replace revocation of application credentials that may have been disclosed.
For the current dashboard workflow, consult the Localtonet HTTP tunnel documentation. The application architecture and security checks described in this guide should be completed before starting the public endpoint.
With Localtonet, the tunnel provides the public address and forwards requests to the configured local target. Your API remains responsible for machine identity, credentials, scopes, resource authorization, request validation, rate controls, idempotency, business rules, and audit records.
Test the public endpoint as an untrusted client
Local success does not prove that the public route exposes only what you intended. Repeat the security tests through the assigned HTTPS address from a separate client or network. This validates the complete route from the remote caller through the tunnel to the application listener.
Begin without a credential
Request a protected agent route without authentication. It should fail consistently and should not execute any operation. Repeat the test using malformed and revoked credentials. Confirm that the response does not reveal valid identity names, authorization rules, stack traces, or configuration details.
Test least-privilege access
Use a valid low-privilege agent credential. Verify that it can perform exactly the intended operations and cannot call adjacent routes, access another identity's resources, elevate its role, or supply an alternate owner identifier. Test both obvious and encoded path variations if the framework performs path normalization.
Probe administrative paths
Request every known administrative path through the public hostname. Include login pages, settings, user management, credential management, API documentation, metrics, health details, debug routes, framework consoles, static bundles, and common fallback paths used by the actual application.
Do not consider an admin redirect harmless. If the public endpoint redirects to a working administrative login page, then the admin surface is exposed even if authentication is required. The preferred result is that the agent listener does not serve that surface at all.
Confirm host and origin behavior
If the application validates host or origin headers, configure those checks deliberately for the public address rather than disabling them globally. Browser-focused cross-origin controls are not a substitute for machine authentication because non-browser clients are not bound by browser origin enforcement.
Test retry and timeout behavior
Deliberately interrupt or repeat a state-changing request in a safe test environment. Confirm that the same idempotency identifier does not cause duplicate effects. Also verify that a client cannot hold expensive work indefinitely and that failed requests produce bounded, actionable responses.
curl -i \
-H "Authorization: Bearer REPLACE_WITH_A_TEST_CREDENTIAL" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: REPLACE_WITH_A_UNIQUE_TEST_VALUE" \
-X POST \
--data '{"operation":"approved-test-value"}' \
"https://PUBLIC_HTTPS_ADDRESS/agent-api/tasks"The header name above is an illustrative application design. Localtonet does not require that idempotency header. Your server and client must agree on the mechanism, and the server must enforce it.
Start with a test identity, non-sensitive data, restricted permissions, and reversible operations. Validate the endpoint manually before adding it to an autonomous workflow or tool registry.
Operate the agent endpoint safely
Secure publication is an ongoing process. Routes change, agents receive new tools, credentials age, and application dependencies behave differently under automated load. Treat the endpoint as a maintained integration rather than a one-time tunnel configuration.
Keep an ownership record
Record who owns the endpoint, which agent or workflow uses it, which Localtonet tunnel targets it, which application identity is assigned, what scopes are allowed, and how access can be disabled. Avoid recording secret values in that inventory.
Review changes to routes and permissions
A new API route should not become public merely because it shares a prefix. Include route exposure and authorization in code review. Re-run negative tests after framework upgrades, routing changes, authentication middleware changes, and admin UI deployments.
Rotate and revoke independently
Maintain separate procedures for application credentials and the tunnel lifecycle. If a credential is exposed, revoke or rotate it at the identity layer. If the endpoint itself should no longer be reachable, stop or delete the tunnel. During an uncertain incident, doing both can provide immediate containment while the cause is investigated.
Monitor outcomes, not only traffic volume
Useful monitoring distinguishes authentication failures, authorization denials, validation errors, limit rejections, repeated idempotency keys, unusual resource access, and successful state changes. A rising request count alone does not explain whether an agent is functioning normally or trapped in a loop.
Keep the Localtonet device under control
The device auth token identifies the client that runs the tunnel and must remain secret. Limit access to the machine and dashboard account, remove unused tunnel configurations, and confirm which local process owns the target port. If another process later binds to that port, the tunnel could forward to an unintended service.
Use a shutdown checklist
For temporary development access, stop the tunnel when testing ends, confirm the public endpoint is no longer reachable, revoke short-lived test credentials if appropriate, review the test audit trail, and remove sensitive test data. If the tunnel is permanent, document maintenance and incident contacts instead of leaving it as an ownerless development artifact.
Troubleshooting without weakening the boundary
The public URL does not respond
Confirm that the selected Localtonet client is connected and that the tunnel has been started. Creating a tunnel alone does not make it active. Next, verify that the local application is running and reachable from the device hosting the Localtonet client at the exact configured local IP address and port.
If the service runs in a container, virtual machine, or another device on the LAN, test reachability from the Localtonet client device rather than only from inside the service environment. Do not change the target to the admin listener merely because that port happens to respond.
The root address returns a not-found response
This may be correct. A machine API does not need to serve a home page. Test the documented agent route or a deliberately minimal readiness route. Avoid adding a dashboard to the API root simply to make browser testing look friendly.
The agent receives an HTML login page
The request may be reaching the human-facing application, an authentication redirect, or a single-page application fallback. Verify the local target port and inspect routing behavior. Machine endpoints should generally return structured API errors rather than browser login HTML.
Authorized requests fail remotely but work locally
Compare the complete request, including method, path, content type, authorization header, host handling, and payload. Check whether the application has explicit host validation or generates redirects for an internal address. Correct the application configuration deliberately rather than disabling security checks wholesale.
The admin UI is reachable through the public address
Stop the tunnel while correcting the architecture. Confirm that it targets the dedicated agent listener. If both surfaces share one listener, add a reliable boundary or separate them before restarting. Review logs to determine whether the exposed paths were requested and rotate credentials if disclosure is possible.
Repeated requests create duplicate work
This is an application-level idempotency problem. Do not rely on the tunnel to deduplicate state changes. Implement and test a server-side mechanism that recognizes retries for the same authenticated caller and operation.
The API becomes unstable under agent use
Inspect concurrency, request cost, payload size, retry behavior, and downstream dependencies. Introduce bounded queues, deadlines, rate controls, or operation-specific limits appropriate to the service. Return explicit retry guidance only when the server can support retries safely.
Opening an admin port, disabling authentication, accepting every host, or publishing debug routes may make a test appear successful while removing the protections this architecture is designed to provide. Diagnose each layer separately: local service, application security, Localtonet client connection, tunnel state, and remote request.
Frequently asked questions
Does a Localtonet HTTP tunnel authenticate my AI agent?
No. The HTTP tunnel provides public connectivity to the configured local IP address and port. Your application must authenticate the machine identity, validate credentials, enforce scopes and resource permissions, and reject unauthorized requests.
Can the API and admin UI run in the same application?
They can, but separate listeners or services provide a clearer boundary. If they share one process, ensure the tunnel targets a listener that cannot serve administrative routes. Test the real public endpoint for admin pages, static assets, debug routes, documentation, redirects, and framework fallbacks.
Is keeping the public URL secret enough?
No. A URL can appear in logs, histories, messages, configuration, or telemetry. Treat the address as reachable by untrusted clients and require dedicated machine authentication and authorization for every protected operation.
Should an agent use my administrator account?
No. Give the agent a dedicated machine identity with only the capabilities required for its task. This reduces impact, improves audit clarity, and allows independent credential rotation or revocation.
Does stopping the tunnel revoke an agent credential?
No. Stopping the tunnel removes public reachability through that tunnel while it remains stopped, but the application credential still exists. Revoke or rotate the credential separately if it is compromised or no longer needed.
Why do agent APIs need idempotency controls?
Automated clients may retry after a timeout without knowing whether the first request succeeded. An application-level idempotency or deduplication mechanism helps prevent repeated requests from creating duplicate state changes.
Do I need router port forwarding or a public IP address?
No. The Localtonet client establishes an outbound connection to a Localtonet relay server, so this workflow does not require inbound router port forwarding, inbound firewall changes, VPN setup, or a public IP address.
When is the public endpoint available?
The endpoint is available only while the selected Localtonet client device is connected and the tunnel is running. Creating the tunnel configuration does not start it automatically.
Publish the API boundary you intended
Separate the agent API from administrative controls, verify authentication and authorization locally, and then use a Localtonet HTTP tunnel to provide the approved machine endpoint with a public HTTPS address.
Get Started Free →
