Build one controlled ingress while keeping AI workers, tools, queues, and model backends private
A distributed AI agent swarm can span coordinators, specialist workers, local LLM servers, tool runners, queues, databases, and observability systems. Publishing every component creates unnecessary attack surface and makes failures harder to isolate. In this guide, we design explicit trust boundaries, protect public callbacks, expose only a coordinator or callback receiver through a Localtonet HTTP tunnel, and explain when VPN Manager is the separate path for private connectivity across machines or LANs. We also establish practical verification, tracing, incident response, and debugging procedures for model, orchestration, tool, network, and tunnel failures.
📋 What's in this guide
A safer distributed AI agent architecture
An AI agent swarm is not one application merely because it pursues one objective. It is a distributed system whose components can fail, stall, disagree, duplicate work, or receive hostile input independently. A planner may choose the wrong tool. A worker may be healthy while its model backend is overloaded. A callback can arrive twice. A tool can complete after the coordinator has already timed out. Networking should make these boundaries visible rather than flattening every service into one public surface.
The safer default is a single controlled ingress. External clients, webhook providers, or remote orchestrators send requests to one coordinator, gateway, or dedicated callback receiver. That entry point authenticates the caller, validates the original request bytes, assigns an operation identifier, applies application policy, and dispatches bounded work to private components. Worker APIs, local LLM endpoints, queues, databases, browser automation processes, administrative interfaces, and trace viewers remain inaccessible from the public internet unless there is a specific and reviewed reason to expose one.
A typical request path looks like this:
External client or callback provider
|
v
Public coordinator endpoint
|
v
Signature, freshness, and policy checks
|
v
Private queue or task dispatcher
| |
v v
Specialist worker Specialist worker
| |
v v
Tool service Local LLM backend
\ /
v v
Results returned to coordinator
|
v
Final response or status updateWith Localtonet, the public coordinator can remain on a machine behind NAT or a firewall. Our client establishes an outbound connection to a Localtonet relay server, and an HTTP tunnel provides the public address for the selected local service. This avoids inbound router port forwarding, firewall changes, VPN setup, and the need for a public IP address. The tunnel is available only while the selected client device is connected and the tunnel is running.
Separate the control plane from the work plane
The coordinator belongs to the control plane. It accepts work, checks policy, decomposes tasks, chooses workers, records state, and aggregates results. Workers belong to the work plane. They execute bounded operations such as retrieval, code analysis, document processing, browser automation, or model inference.
This distinction prevents workers from becoming unreviewed public gateways. A worker should normally accept requests only from the coordinator, queue, or another explicitly authorized internal service. If a worker can invoke tools, its tool permissions should reflect its narrow role. A summarization worker does not need access to a deployment API, and a read-only retrieval worker should not receive database write credentials.
Reachability, authentication, and authorization are separate controls
A tunnel makes a selected endpoint reachable. It does not prove who sent a request, decide whether that caller may perform an operation, or determine whether model-generated arguments are safe. Transport reachability, application authentication, and operation-level authorization are separate layers, and all three must be designed deliberately.
The public coordinator should reject requests that are unauthenticated, malformed, too large, stale, replayed, or outside the caller's permissions. Internal services should also authenticate their callers. Private network placement reduces exposure, but a private address is not an identity and must not become the only authorization rule.
An endpoint that accepts an arbitrary tool name and arbitrary arguments can become a remote execution boundary. Use a fixed allowlist of tools, strict schemas, caller authorization, argument constraints, execution time limits, idempotency controls, and auditable results. Do not pass model-generated input directly to a shell, database, file path, browser session, or privileged API.
Define trust boundaries before connecting the swarm
Begin with a data-flow inventory. List every component, who can call it, what data crosses the connection, which credentials it can use, and what happens if it is compromised. This exercise determines which endpoint, if any, should be public and which connections should be denied even inside the private environment.
| Component | Recommended reachability | Primary controls | Failure or exposure concern |
|---|---|---|---|
| Coordinator or callback receiver | Public only when external requests must reach it | Authentication, signature verification, replay prevention, authorization, rate controls, deadlines | Untrusted input enters the system here |
| Planner | Private | Structured output validation, task limits, deterministic policy checks | Can generate invalid, excessive, or unsafe plans |
| Specialist worker | Private | Service identity, narrow authorization, concurrency limits | May hold tool credentials or process sensitive data |
| Local LLM server | Private | Authorized callers, resource limits, bounded context and output sizes | Resource exhaustion and unintended data disclosure |
| Tool runner | Private | Allowlisted operations, schema validation, sandboxing, approval gates | Tool arguments can trigger real-world side effects |
| Queue or task broker | Private | Producer and consumer authorization, retention controls, dead-letter handling | Task theft, duplication, backlog growth, or replay |
| Database or state store | Private | Least-privilege credentials, query constraints, backup and recovery procedures | Persistent corruption or sensitive-data access |
| Observability interface | Private or separately protected | Access control, redaction, retention limits | Logs and traces can reveal prompts, tokens, or private content |
Assign identity and permissions at every hop
Network location alone is a weak identity signal. A request coming from a private address does not prove that it came from the intended worker. Each service should authenticate its callers using an identity method suitable for the application and deployment. Store credentials outside prompts and model-visible state. Rotate them according to your operational policy, and never place them in logs, traces, URLs, task envelopes, or error messages.
Authorization should describe permitted actions, not just permitted connections. One worker may read selected records while another can create a draft but cannot publish it. A coordinator may enqueue a task without receiving unrestricted access to every downstream database and administrative API.
Constrain data movement
Prompts and tool outputs can contain customer records, source code, documents, access tokens, or secrets accidentally returned by a tool. Pass only the fields required for the next operation. Redact sensitive values before logging. Define whether complete prompts, model responses, tool arguments, and tool results may be retained, who may view them, and when they must be deleted.
Treat retrieved documents, web pages, email bodies, issue descriptions, queue messages, and tool output as untrusted data. Preserve the distinction between application policy, authenticated user instructions, retrieved context, and tool results. Untrusted content does not gain authority merely because it appears inside a model context window.
Use private networking for distributed internal components
Components on one host can often communicate through loopback or an isolated local network. Components on separate machines or LANs need a deliberate private connectivity design. Localtonet VPN Manager provides a free private mesh VPN with granular firewall rules and can bridge local LANs. It is the Localtonet feature intended for controlled private networking across locations.
Standard HTTP, TCP, UDP, TLS, and File Server tunnels are not VPN functionality. Use an HTTP tunnel for a selected public web endpoint. Consider VPN Manager when multiple private nodes or LAN resources need controlled private connectivity.
This guide uses VPN Manager only as an architecture choice. It does not configure a VPN topology because verified addresses, participating devices, and firewall rules are deployment-specific. Follow the official VPN Manager guide, then test every intended allow rule and deny rule before relying on the private path.
Threat-model public agent ingress and internal tool execution
A distributed agent combines ordinary web security risks with model-specific risks. The public endpoint receives attacker-controlled bytes. The model may also consume instructions hidden in documents, web pages, tickets, source code, images converted to text, or tool responses. Finally, an agent may have enough agency to turn an unsafe interpretation into a real side effect.
Distinguish direct and indirect prompt injection
Direct prompt injection occurs when a caller deliberately includes instructions intended to override the application's task or policy. Indirect prompt injection occurs when hostile instructions are embedded in content the agent retrieves later, such as a web page, file, message, database record, or tool result.
Both forms must be handled as untrusted input. Label data by source, limit what is placed into model context, and avoid combining trusted policy with untrusted content in a way that obscures their roles. Where practical, extract facts through constrained parsers or typed fields instead of asking a model to interpret an entire untrusted document and immediately take action.
Prompts cannot enforce authorization boundaries
A system prompt can guide model behavior, but it is not an authorization mechanism. Do not rely on instructions such as “never access other accounts” or “only call safe tools” as the control that protects data or infrastructure. Application code must determine the authenticated identity, allowed resources, permitted tool set, argument limits, and whether approval is required.
Treat every model response as a proposal. Validate the tool name against an allowlist, parse arguments into a strict schema, apply authorization using trusted application state, enforce resource scope, and reject unknown fields or values. The model must not be allowed to choose its own permissions, tenant, credential, approval status, or network policy.
Limit excessive agency
The more actions an agent can perform without review, the larger the consequence of a mistaken or manipulated decision. Separate read operations from write operations. Give workers the smallest tool collection required for their role. Limit the number of tool calls, execution duration, spending or resource budgets, affected objects, and fan-out depth.
Require a human or deterministic approval service for consequential actions such as publishing externally, deleting data, changing infrastructure, sending messages to large audiences, moving money, altering access controls, or disclosing sensitive information. Approval must cover the final normalized action and arguments, not merely a model-generated summary of what it plans to do.
Restrict outbound requests and defend against SSRF
A browser, fetch tool, URL previewer, or HTTP client can become a server-side request forgery path. Apply an outbound destination policy outside the model. Prefer explicit destination allowlists for narrow integrations. Validate schemes, ports, hostnames, resolved addresses, and redirects. Block destinations that should never be reachable by the tool, including local administrative services, private resources outside the worker's role, and infrastructure credential endpoints.
Revalidate the destination after redirects and resolution changes. Limit response size, content type, connection time, total duration, and redirect count. Run high-risk network tools in a network segment with no default access to sensitive internal services. A prompt telling the model not to access private addresses is not an egress control.
Sandbox code, files, and browser automation
Tool runners that execute code, process archives, render documents, or automate browsers should use an isolation boundary appropriate to the risk. Restrict filesystem access, process capabilities, network egress, CPU, memory, execution time, and writable storage. Use disposable workspaces for untrusted jobs where possible, and do not mount broad host directories or credential stores into a general-purpose execution environment.
Validate file paths after normalization, reject traversal outside the assigned workspace, and control archive extraction. Do not let a model choose arbitrary executable paths or command-line fragments. If a workflow genuinely requires command execution, map approved operations to fixed application functions with structured parameters.
Protect secrets and sensitive data
Give each component separate least-privilege credentials. A model process should not automatically inherit the host's cloud credentials, deployment keys, browser sessions, or Localtonet device token. Retrieve a credential only at the application layer when an authorized operation needs it, and keep the secret out of prompts and model output.
Classify data before sending it to models or tools. Remove unnecessary fields, redact secrets, and prevent cross-tenant retrieval. Logs and traces should record decisions and identifiers without becoming a second copy of every confidential prompt and document.
The safety boundary must remain in deterministic application code, service permissions, egress policy, sandboxing, and approval workflows. Model instructions can support these controls, but they cannot replace them.
Protect public callbacks with signed-request verification
When an external provider supports signed callbacks, verification should happen before JSON parsing, event dispatch, queue publication, or any side effect. Header names, signature encodings, and signing formats vary by provider, so this guide does not invent provider-specific fields. Implement the provider's documented format while preserving the framework-neutral sequence below.
Apply transport and payload limits
Accept only the required method and route. Enforce a small, explicit maximum body size and a short read deadline before buffering the raw body. Reject unsupported content types and incomplete requests. These checks reduce resource exhaustion, but they do not authenticate the sender.
Capture the exact raw request body
Preserve the original bytes used by the sender when calculating the signature. Do not parse and reserialize JSON before verification because whitespace, ordering, and encoding changes can produce different bytes.
Extract and validate signature metadata
Read the provider-defined signature, signed timestamp, and key identifier if the protocol includes one. Reject missing, malformed, unsupported, or ambiguous values before selecting a secret or calculating a digest.
Enforce a replay window
Compare the signed timestamp with a trusted server clock and reject requests outside your documented acceptance window. Monitor clock synchronization. A timestamp check limits reuse of captured requests but does not by itself prevent replay inside the accepted window.
Calculate and compare the expected signature
Reconstruct the provider-defined signed message from the timestamp, raw body, and any other documented fields. Calculate the expected signature with the configured secret and algorithm. Compare decoded values with a constant-time comparison function rather than ordinary string equality.
Block replay inside the allowed window
Store a provider event identifier or a digest of stable signed request data for at least the accepted replay period. Atomically reject a value already seen. Keep this replay record separate from business idempotency because an authentic event can also be redelivered legitimately.
Parse, validate, and authorize the event
Only after signature and freshness checks succeed should the application parse the body. Validate a strict schema, accepted event type, resource scope, tenant mapping, and caller permissions. Unknown event types and extra privileged fields should not be dispatched automatically.
Apply business idempotency before side effects
Atomically associate the event or operation identifier with processing state. Return the recorded result for completed work, avoid parallel duplicate execution, and reconcile uncertain outcomes rather than repeating a consequential action blindly.
Rotate callback secrets without creating a verification gap
Maintain an active secret and, for a short controlled overlap, the previous secret. If the provider supplies a trustworthy key identifier, use it to select the expected key. Otherwise, verify against the small configured set without revealing which key matched. Stop accepting the old secret after the provider transition and the maximum delivery and replay windows have passed.
Store callback secrets in an application secret store, not in source code, prompts, task messages, URLs, or logs. Record rotation time, owner, affected integrations, and verification results. If a secret is suspected to be compromised, rotate it immediately, revoke the old value where supported, inspect accepted events, invalidate related sessions or credentials, and reconcile side effects that may have been triggered.
Keep authenticity, replay defense, and idempotency distinct
| Control | Question answered | What it does not prove |
|---|---|---|
| Signature verification | Was the signed request created by a party holding an accepted secret, and was signed content unchanged? | That the event is fresh, authorized for every action, or safe to execute twice |
| Timestamp window | Is the signed request recent enough under the configured clock policy? | That the same recent request has not already been submitted |
| Replay record | Has this signed delivery already been accepted during the replay period? | That a business operation was not previously completed through another delivery |
| Business idempotency | Can this operation be processed without repeating its side effects? | That the original request was authentic |
If a provider does not support signed callbacks, use the strongest authentication mechanism it documents and compensate with narrow routes, high-entropy credentials, strict source and schema controls where appropriate, payload limits, rate controls, replay-aware event processing, and minimal endpoint authority. Do not describe an unsigned endpoint as authenticated merely because its URL is difficult to guess.
Make agent execution reliable before making it remote
Networking does not create reliability. It can reveal existing reliability problems by adding latency, disconnections, duplicate delivery, and partial completion. Build the local workflow around explicit contracts before introducing public callbacks or distributed workers.
Define a task envelope
Every task should carry enough metadata to identify, validate, schedule, trace, and safely repeat it. The exact schema depends on the application, but a useful conceptual envelope includes:
{
"operation_id": "application-generated unique identifier",
"task_id": "application-generated unique identifier",
"parent_task_id": "optional parent identifier",
"task_type": "allowlisted operation name",
"created_at": "timestamp",
"deadline": "timestamp",
"attempt": 1,
"input": {
"validated_fields": "task-specific data"
}
}This is an application-level pattern, not a Localtonet configuration. Generate identifiers in trusted application code, validate their format at every boundary, and preserve them when work moves between processes. Do not let untrusted callers use an identifier to gain access to another operation.
Propagate deadlines, not only timeout durations
A chain of independent timeouts can run much longer than the caller intended. If a coordinator has 30 seconds to complete a request but starts a worker with a fresh 30-second timeout after 25 seconds, the operation has already exceeded the original budget. Propagate an absolute deadline or calculate the remaining budget at each hop.
Set separate limits for connection establishment, model inference, tool execution, queue waiting, and the complete operation. When a deadline expires, stop issuing new side effects and attempt cancellation where the component supports it. Record whether cancellation was requested and whether the underlying operation actually stopped.
Retry selectively and in one responsible layer
Retries are appropriate for transient failures, not every failure. A temporary connection interruption or unavailable dependency may justify a bounded retry. Invalid arguments, denied authorization, unknown tools, expired tasks, and deterministic validation errors should normally fail immediately.
Use a maximum attempt count, delay between attempts, randomization, and a total deadline. If the client, coordinator, queue, worker, and tool wrapper all retry independently, one request can multiply into many executions. Assign retry ownership to one layer for each operation.
Design idempotency around side effects
A caller can time out after a tool completes but before the result arrives. Retrying may repeat the side effect. Operations that send messages, create records, charge accounts, publish content, or modify infrastructure need an idempotency strategy.
Associate the requested side effect with a stable operation or idempotency key. Before executing, the tool service checks atomically whether that key has completed or is in progress. If it completed, return the stored outcome. If its status is uncertain, route the task to reconciliation instead of assuming success or failure.
Trace work across independently failing components
Distributed agent debugging becomes manageable when every event can be tied to one operation and its causal parent. Use standard trace context across HTTP where your framework supports it, while retaining application-level operation and task identifiers for durable business correlation. Trace identifiers describe execution, while operation identifiers can survive retries, delayed callbacks, and long-lived workflows.
Handle inbound trace context as untrusted input
Public callers can supply malformed or deliberately chosen trace identifiers. Validate incoming trace context against the standard format and your platform's limits. Apply sampling and baggage restrictions, and reject oversized or unsupported values. If the context is invalid, untrusted by policy, or likely to create correlation with another tenant, start a new local trace and store the inbound value only in a safely bounded diagnostic field if it is needed.
Do not let inbound trace data determine authorization, tenancy, log access, or data ownership. Avoid propagating arbitrary baggage fields into private services because they can increase request size or carry attacker-controlled data. Regenerating a local trace does not prevent you from returning a safe application correlation ID to the caller.
Preserve parent-child relationships across HTTP and queues
For a synchronous HTTP call, create a child span from the current coordinator span and propagate the validated trace context to the private service. For an asynchronous queue, inject trace context into approved message metadata when publishing. When a worker receives the message, extract and validate that context and create a consumer span related to the producing operation.
Queue waiting time and worker execution time should remain distinguishable. If a task is retried, create a new attempt span rather than rewriting the original attempt. Keep the same business operation ID, assign an attempt number, and preserve the relationship to the original task. For batch consumers or messages influenced by multiple producers, use the tracing system's supported relationship mechanism rather than pretending there is one false parent.
When a coordinator fans out five worker tasks, they should share the parent operation ID but receive distinct task IDs and child execution contexts. If one worker triggers three tools, each tool call should reference the worker task. This structure identifies the slow branch, duplicate execution, or first failing dependency without reconstructing the flow from timestamps alone.
Separate public errors from protected diagnostics
Public responses should not expose stack traces, internal addresses, credentials, file paths, model configuration, or raw dependency errors. Return a stable error category and application correlation ID. Keep detailed diagnostics in access-controlled logs and traces with an explicit retention policy.
Prerequisites and deployment decisions
Before adding remote access, prepare a locally working architecture. This guide does not require a particular agent framework, programming language, model, queue, or database. Application commands, ports, paths, and environment variables vary, so use the values defined by your selected stack and verify them locally.
- A coordinator or callback receiver that serves HTTP locally.
- A known local IP address and port for that public-facing endpoint.
- Application authentication and operation-level authorization.
- Signed-callback verification when supported by the sender.
- Strict request schemas, body-size limits, and execution deadlines.
- An allowlisted tool registry rather than arbitrary function dispatch.
- Private connectivity from the coordinator to required workers, queues, models, and tools.
- Least-privilege service credentials and restricted outbound network access.
- Timeout, retry, cancellation, replay, and idempotency rules.
- Structured logs with operation, task, attempt, and trace identifiers.
- A Localtonet client installed on the device that can reach the coordinator.
- A device-specific Localtonet authentication token kept private.
If nodes on separate machines or LANs need private communication, design a VPN Manager topology as a separate workstream. Determine which node initiates each connection and which exact private services it must reach. Follow current official VPN Manager material rather than inferring addresses or dashboard steps from this HTTP ingress tutorial.
The authentication token identifies the client device that runs a tunnel. Tokens are device-specific and must not be guessed, embedded in examples, committed to source control, placed in prompts, or exposed in logs. If one is compromised, replace or revoke it through the available account controls, stop affected tunnels, review tunnel and client state, and restore access with a newly protected token.
Build and verify the swarm locally first
A remote tunnel should be the last link added, not the first diagnostic tool applied to an unverified stack. Prove each local boundary in dependency order so that later failures have a smaller search area.
Start the coordinator without public access
Bind it according to your local deployment policy and confirm that the process starts without configuration, dependency, or credential errors. Record the exact local IP address and port that Localtonet will eventually target.
Verify the coordinator endpoint locally
Send a known valid request from the same device. Then test missing authentication, an invalid signature, malformed data, an unknown operation, an oversized request, and an expired deadline. Each should fail safely before work is dispatched.
Verify every private dependency independently
From the coordinator's execution environment, test the queue, worker, local model, tool service, and state store separately. Run a minimal real operation against each dependency instead of relying on process status alone.
Run one deterministic end-to-end task
Choose a bounded task with a predictable result. Follow its operation ID and trace context through ingress, orchestration, queue delivery, worker execution, model or tool use, result storage, and final response.
Exercise expected failure paths
Test an unavailable worker, model timeout, rejected tool argument, replayed callback, duplicate task, and late result. Confirm retries remain bounded and side effects are not duplicated.
Confirm private services are not publicly reachable
Review listening interfaces, firewall policy, container publication, and router configuration. Test from an external network and confirm that workers, models, queues, databases, tools, and observability interfaces cannot be reached.
Test with realistic but non-sensitive data
Test payloads should exercise normal validation and routing without containing production credentials, private customer records, or confidential documents. Include boundary conditions such as empty values, maximum accepted lengths, unusual Unicode, duplicate requests, delayed responses, hostile retrieved instructions, and unauthorized resource identifiers.
Expose only the coordinator with a Localtonet HTTP tunnel
Once the complete path works locally, add a Localtonet HTTP tunnel for the selected coordinator or callback receiver. The Localtonet client must run on a device that can reach the service's local IP address and port. The client establishes the outbound connection to our relay, so inbound router port forwarding and a public IP address are not required.
Tunnel creation and startup are separate lifecycle states. Creating a tunnel does not mean it is running. The public endpoint remains available only while the selected client device is connected and the tunnel is running.
Install and run the Localtonet client
Install the Localtonet application for the operating system on the device that can reach the coordinator. Keep the client running for as long as remote access is required. Use current Localtonet installation instructions rather than an unverified command copied from another environment.
Authenticate or select the client device
Use the device-specific authentication token associated with the client that will run the tunnel. Do not place it in application configuration that workers, tools, or models can inspect.
Select an available relay server
Choose from the relay servers or regions currently available in the dashboard. Availability can vary, so do not hardcode a server code from an article or another deployment.
Create the HTTP tunnel for the coordinator
Configure the tunnel to point to the coordinator's verified local IP address and port. HTTP process types can use a random subdomain, a custom subdomain where supported, or a custom domain. Check current documentation before configuring custom-domain DNS because exact DNS requirements are not established in this guide.
Start the tunnel
Use the Start control after reviewing the selected device, relay, local target, and process type. Creating the configuration alone does not start connectivity.
Test the assigned public endpoint
Send an authenticated and correctly signed test request through the assigned public URL. Confirm that the same operation succeeds locally and remotely, and verify that its application and trace identifiers appear throughout the internal path.
Confirm current interface details in the Localtonet HTTP tunnel documentation.
Choose the narrowest useful public endpoint
If an external system only needs to deliver callbacks, expose a narrow callback receiver instead of the entire coordinator administration interface. If clients need to submit tasks, publish only the required task routes. Keep health diagnostics, metrics, model management, queue administration, trace viewers, and worker control endpoints private.
Assume unknown clients will send malformed or hostile requests. Localtonet supplies reachability to the configured local service, while your application remains responsible for authentication, signed-request verification, authorization, replay prevention, payload limits, and safe task execution.
Verify allowed paths, denied paths, and failure behavior
A successful request proves only one path under one condition. A safety-focused deployment must also demonstrate that prohibited paths remain closed and that connectivity failures do not produce unsafe retries or silent exposure.
| Test | Procedure | Expected result |
|---|---|---|
| Allowed public ingress | Send a valid authenticated request through the public URL | The coordinator accepts it, assigns correlation data, and dispatches only the authorized task |
| Denied public route | Request an administrative, worker, model, or metrics route through the public URL | The route is unavailable or denied without revealing internal details |
| Allowed east-west path | From each authorized node, connect to the exact required private service and port | The intended operation succeeds with the correct service identity |
| Denied east-west path | Attempt an unapproved node-to-service or port combination | The connection or operation is denied and the result is observable |
| External private-service check | From a device outside the local and private mesh networks, test worker, model, queue, database, and observability addresses | No private service is publicly reachable |
| Client disconnection | Disconnect the selected Localtonet client while observing the public route | The public route no longer reaches the local application and no internal service becomes exposed by another path |
| Tunnel stop | Reconnect the client, restore the tunnel, then use Stop | Public reachability is removed while the application remains locally available |
| Replayed callback | Resend the same valid signed request inside and outside the replay window | The replay is rejected or safely recognized without redispatching work |
| Duplicate side effect | Deliver duplicate business events or retry after a simulated response loss | Idempotency returns the recorded result or reconciles uncertainty without repeating the side effect |
| Compromised application secret | Run the documented rotation and revocation exercise using a test secret | The old secret stops working, the new secret works, and accepted events remain auditable |
| Compromised Localtonet token | Exercise the account's replacement or revocation process in a controlled environment | Affected access is stopped, tunnel and device state are reviewed, and a protected replacement is used |
VPN Manager verification belongs to the VPN deployment
If you adopt VPN Manager, create a separate test matrix from the approved data-flow inventory. Verify every allowed source, destination, protocol, and service. Then test representative denied paths, including access to administrative ports and unrelated LAN resources. This article does not claim that VPN Manager has been configured merely because the architecture recommends it.
Debug distributed agent failures from the outside inward
Avoid changing several layers at once. A model error, tool error, coordinator error, private-network failure, and tunnel failure can produce similar user-visible symptoms, but they leave different evidence.
| Observed symptom | Layer to test first | Evidence to inspect | Likely next action |
|---|---|---|---|
| Public URL does not connect | Localtonet lifecycle | Client connection, selected device, tunnel state, local target | Confirm the client is connected, the tunnel is started, and the target works locally |
| Public request is rejected immediately | Ingress security | Method, body limit, timestamp, signature result, replay result, authorization | Correct the caller or policy instead of weakening verification |
| Request is accepted but never completes | Coordinator and queue | Dispatch event, queue time, worker receipt, remaining deadline | Locate the first missing correlated transition |
| Model asks for an unsafe action | Tool authorization boundary | Tool allowlist, schema, resource scope, approval state | Reject the proposal and inspect the untrusted context that influenced it |
| Side effect happens twice | Idempotency handling | Operation key, attempts, completion record, acknowledgement timing | Suppress duplicate execution and reconcile uncertain outcomes |
| Only remote private nodes fail | Private connectivity policy | Approved path, listener, name resolution, firewall decision | Use the VPN Manager deployment's allow-and-deny test plan |
Prove the local service still works
Test the coordinator from the same machine using the exact local target configured for the tunnel. If this fails, stop investigating the public path. Check whether the process is running, listening at the expected address and port, and able to reach its dependencies.
Check the Localtonet lifecycle
Verify that the correct client device is connected and the tunnel is running. Confirm the selected local IP address and port. Creating a tunnel is not equivalent to starting it, and a running configuration cannot forward traffic if its selected client is disconnected.
Find the last correlated event
Search for the operation ID and trace. Determine whether ingress accepted it, the coordinator dispatched it, the queue delivered it, a worker began it, a model responded, authorization approved a tool, and the tool completed. The first missing transition identifies the boundary to test.
Validate model output as untrusted data
A model can return invalid JSON, an unknown tool name, missing fields, incorrect types, an unauthorized resource identifier, or arguments outside allowed ranges. Capture the validation and policy result with a safely redacted representation. Do not loosen schemas or permissions automatically merely to make a failing task pass.
Inspect retry history before replaying
Before manually retrying, check whether a previous attempt may have completed. Use the idempotency record, downstream transaction identifier, or application state. For consequential operations, uncertainty should trigger reconciliation rather than automatic repetition.
Operate the swarm with a reviewed exposure surface
Architecture can drift. A temporary debugging endpoint can become permanent, or a worker can begin listening on a public interface after a deployment change. Review the network inventory regularly and compare it with the intended data-flow diagram.
Use explicit startup and shutdown procedures
Start private dependencies before workers that require them, then start the coordinator, verify local readiness, and finally start the Localtonet tunnel. During shutdown, stop accepting new public work, allow or cancel in-flight operations according to policy, stop the tunnel, and then stop internal components.
Stopping or deleting a Localtonet tunnel removes that public path, but it does not terminate work already accepted by the application. The coordinator still needs a graceful shutdown strategy.
Prepare for compromised credentials
Maintain an inventory of callback secrets, service credentials, tool credentials, and Localtonet device tokens with owners and rotation procedures. If a credential is exposed, stop affected access, rotate or revoke it, search protected logs for use, inspect resulting tasks and side effects, and restore service with a newly protected credential. Avoid assuming rotation alone reverses actions already taken.
Use Localtonet platform webhooks for connectivity monitoring
Localtonet platform-wide Token/Tunnel webhooks fire when a token or tunnel in a selected Token Group changes to Connected or Disconnected. The documented JSON body is a WebHookRequest containing Id, ActionDate, Type, and Status. Type is Token or Tunnel, while Status is Connected or Disconnected. Use these events for connectivity monitoring, not for task tracing, model health, callback authentication, or tool execution records. See the Localtonet webhook documentation.
Run recurring security checks
- Enumerate public URLs and confirm their ownership and purpose.
- Verify that only intended coordinator or callback routes are exposed.
- Test callback signature failure, stale timestamps, replay, and duplicate delivery.
- Review tool allowlists, approval gates, and worker credentials.
- Verify outbound destination restrictions and denied SSRF paths.
- Test allowed and denied private-network paths.
- Confirm externally that private services remain unreachable.
- Search logs and traces for accidental secrets or sensitive payloads.
- Test Localtonet client disconnection and tunnel stop separately.
- Exercise compromised-secret and compromised-token response procedures.
- Review dead-letter and reconciliation queues so failed work does not accumulate unnoticed.
Frequently asked questions
Should every AI worker have its own public endpoint?
Usually not. Publish one coordinator or narrowly scoped callback receiver and keep workers, model servers, queues, tools, databases, and observability interfaces private. Add another public endpoint only for a documented requirement with separate authentication, authorization, and operational ownership.
Does a Localtonet tunnel authenticate my agent API?
Do not treat transport reachability as application authentication. Your coordinator must authenticate callers, verify signed callbacks where supported, authorize each operation, validate schemas, limit payloads, enforce deadlines, and prevent replay according to the application's requirements.
When should I use an HTTP tunnel instead of VPN Manager?
Use an HTTP tunnel when an external client or service must reach one selected local web endpoint. Consider VPN Manager when private nodes or LAN resources need controlled private connectivity. VPN Manager is a separate deployment path and should be configured and tested using its current official guidance.
Can a system prompt prevent unauthorized tool use?
No. A prompt can guide behavior, but authorization must be enforced by application code and service permissions. Validate the model's proposed tool and arguments, apply trusted identity and resource policy, and require approval for consequential actions.
Why verify a webhook signature before parsing JSON?
Providers commonly sign the original request bytes. Parsing and reserializing can change those bytes. Verification before parsing also prevents unverified content from reaching event dispatch or business logic. Apply body limits first, preserve the raw body, verify freshness and signature, block replay, and only then parse and authorize the event.
How should trace context cross a queue boundary?
Inject validated trace context into approved message metadata when publishing. The consumer validates and extracts it, creates a consumer execution span, and preserves the business operation and task identifiers. Retries should use new attempt spans while retaining their relationship to the original task.
How should duplicate callbacks be handled?
Use signed timestamps and a replay record to reject captured deliveries, then use business idempotency to prevent duplicate side effects from legitimate redelivery or retries. Store execution state atomically and reconcile uncertain outcomes instead of executing blindly again.
Why does the public endpoint fail when the tunnel configuration exists?
Creating a tunnel does not start it. Confirm that the selected Localtonet client device is connected, the tunnel is running, and the configured local IP address and port match a service that works locally. The public endpoint is available only while the client is connected and the tunnel is running.
Expose the coordinator, not the entire swarm
Start with a locally verified coordinator, enforce authentication and authorization in application code, keep workers and model backends private, and use a Localtonet HTTP tunnel for the one endpoint that genuinely requires public access. Treat VPN Manager as a separate private-network deployment when distributed nodes need controlled communication across machines or LANs.
Get Started Free →
