Build an AgentOS platform locally, validate its REST API, and expose only the service you intend to share
Agno provides an SDK, the AgentOS runtime, and a control plane for building and operating agent platforms. Its recommended starter workflow uses an official deployment template and a coding agent to prepare a Docker-based local platform. This guide explains that evidence-backed workflow, shows how to verify the resulting API without guessing its port or routes, and then treats remote access with Localtonet as a separate next step. Because the selected Agno starter controls important configuration details, we also identify exactly which values must come from its current README and runtime output.
📋 What's in this guide
Understand what the Agno starter installs
Agno describes itself as an SDK for building agent platforms. The complete stack separates application development, runtime behavior, and management into three related layers. The Agno SDK is where developers build agents, teams, and workflows. AgentOS runs the platform as an API and MCP server. The Control Plane provides the AgentOS user interface for monitoring and management.
The official starter workflow is broader than installing a single Python package. The recommended template produces a platform that runs locally with Docker and includes a REST API for serving agents, a PostgreSQL database for data and traces, an MCP server, and a control plane. That distinction matters when planning remote access. An HTTP tunnel should point to the running web service that you deliberately select, not automatically to every container or supporting component in the stack.
Agno also documents storage for sessions, memory, knowledge, and traces, OpenTelemetry observability, run history, audit logs, human approval controls, interfaces for chat platforms, scheduling, and more than 100 integrations. These capabilities do not mean that every new starter deployment is automatically configured for a particular production policy. The template, its environment configuration, and the agents you add determine what the running platform actually does.
Complete the Agno setup and prove that its API works locally before creating a tunnel. Localtonet provides connectivity to an existing service. It does not install AgentOS, repair an unhealthy container, select an AI model, or determine the API route exposed by the starter.
Prepare the local host without guessing template requirements
The extracted official instructions establish that the recommended Agno platform runs locally using Docker and that a coding agent is the preferred setup interface. They do not establish a universal minimum Docker version, a fixed operating-system list, CPU or memory minimums, a required Git version, or one set of model-provider credentials. Those details can change between starter repositories and revisions, so they must come from the README and setup skill in the exact template you select.
Before beginning, prepare a machine on which you are authorized to run containers and expose services. Confirm that Docker is installed and functioning according to the requirements in the selected starter. You also need enough local storage for container images and persistent database data. If the template asks for API credentials or other secrets, obtain them directly from the applicable provider and keep them out of source control, terminal transcripts, screenshots, and tunnel configuration.
Agno's recommended workflow is designed for coding agents such as Claude Code, Cursor, or Codex. The coding agent needs permission to clone the selected public repository, read its files, and perform the documented setup actions. Review proposed shell commands and file changes before approving them, especially when the agent requests elevated privileges, modifies environment files, or starts containers.
| Requirement | What is established | What you must verify |
|---|---|---|
| Docker environment | The recommended starter runs the platform locally using Docker. | Supported Docker version, compose behavior, host compatibility, and resource requirements in the selected starter. |
| Coding agent | Agno recommends giving its setup prompt to Claude Code, Cursor, Codex, or a comparable coding agent. | The agent's local permissions and every command it proposes before execution. |
| Starter repository | Agno maintains deployment-specific AgentOS starter repositories. | The current README, setup skill, deployment scripts, and branch or revision you intend to use. |
| Application secrets | The platform can connect to model providers and external integrations. | The exact variables, credentials, and provider configuration requested by your chosen implementation. |
| Network endpoint | The completed platform provides a REST API. | The actual local hostname, bound interface, port, API route, and authentication policy reported by your starter. |
| Localtonet client | The client establishes an outbound connection to our relay infrastructure. | The current installation instructions for your operating system and an authorized device token from your account. |
Use the secret-management mechanism documented by the starter and your development environment. Inspect generated configuration before starting the platform. Never place a Localtonet device token, model-provider key, database password, JWT signing secret, or private endpoint in public source control.
Choose the official Agno starter that matches your destination
Agno's main repository recommends the agentos-railway starter in its introductory example. The documentation also provides deployment-specific templates for Docker, AWS, Fly, GCP, Kubernetes through Helm, Azure, Render, and Modal. The main Agno README notes that the starter templates are identical except for deployment scripts, but you should still use the repository intended for your target because its setup and deployment instructions can differ.
For a local-first workflow where the immediate goal is to start AgentOS with Docker and then share its API from the same machine, agentos-docker is the clearest template name. If the platform will eventually be deployed to Railway or another supported destination, selecting that destination's starter avoids replacing deployment scripts later.
| Starter | Intended destination | Selection guidance |
|---|---|---|
agentos-docker |
Container-based Docker deployment | Use when Docker is the target and the platform will first run on your own machine or container host. |
agentos-railway |
Railway | This is the starter used in the main Agno repository's recommended introductory example. |
agentos-aws, agentos-gcp, or agentos-azure |
Major cloud platforms | Select the repository corresponding to the cloud deployment scripts you plan to use. |
agentos-helm |
Kubernetes | Use when the target deployment is managed through the documented Helm starter. |
agentos-fly, agentos-render, or agentos-modal |
Named hosting platform | Use the platform-specific repository rather than adapting unrelated deployment scripts. |
This guide uses agentos-docker in the setup prompt because the stated objective is a Docker-based local AgentOS platform. If you choose a different official starter, replace only the repository name in the documented prompt, then follow that repository's own setup skill and README.
Install the Agno platform through the documented starter workflow
The current Agno documentation recommends asking a coding agent to clone the starter into a directory named agent-platform and run the repository's setup-platform skill from .agents/skills/. The public evidence supplied for this article does not expose the commands inside that skill or the starter's current environment files. Reproducing unverified manual commands would therefore be unsafe and likely to become stale.
Give your coding agent the following documented prompt for the Docker starter:
Help me set up my agent platform and build my first agent. Clone https://github.com/agno-agi/agentos-docker into a folder called agent-platform, cd in, and run the setup-platform skill (in .agents/skills/).Keep the coding agent in the project directory, allow it to inspect the complete repository, and ask it to explain requested values before you provide them. The setup skill and README are authoritative for the starter revision that was actually cloned.
Confirm the selected starter
Use agentos-docker for the Docker-oriented workflow shown here, or replace it with the official deployment-specific starter that matches your intended destination. Avoid mixing setup files from multiple starters.
Submit the official setup prompt
Give the prompt above to your coding agent. It instructs the agent to clone the repository as agent-platform, enter that directory, and run the included setup-platform skill.
Review the repository instructions and proposed changes
Require the coding agent to read the starter's README and skill files before acting. Review dependency installation, environment-file creation, secret requests, volume configuration, and container commands rather than approving them blindly.
Supply only the configuration the starter requests
Enter model-provider or integration settings through the mechanism documented by the repository. Do not invent variable names or copy configuration from a different starter. Keep all secrets out of committed files.
Start the Docker-based platform
Allow the coding agent to run the starter's documented startup procedure after you have reviewed it. Wait for the runtime and required supporting services, including PostgreSQL, to become ready.
Record the actual local endpoint
Capture the hostname or IP address, host port, API route, and authentication behavior shown by the starter's output. These values are required for local verification and the later Localtonet HTTP tunnel.
A successful setup should leave you with a running AgentOS platform rather than merely a cloned repository. The official description says the local result includes a REST API, PostgreSQL storage for data and traces, an MCP server, and a control plane. Verify each component using the starter's own status output, but do not assume that all components share a port or should be remotely reachable.
The supplied Agno material does not state a universal local hostname, port, health route, API route, container name, or compose filename. Those details must be read from the current starter and its runtime output. A fixed value in this article would be a guess and could send traffic to the wrong process.
Account for Agno telemetry
Agno states that it sends one telemetry event per agent run to help prioritize model providers. It also states that prompts, messages, and outputs are never sent through that telemetry. If your policy requires telemetry to be disabled, Agno documents the following environment setting:
AGNO_TELEMETRY=falseApply it through the environment mechanism used by the selected starter, then restart the affected runtime as instructed by that repository. Do not assume that editing an arbitrary file will change an already running container.
Verify the Agno API locally before sharing it
Local verification separates application problems from tunnel problems. If the API cannot be reached from the same host that will run the Localtonet client, creating a public URL will not repair it. First inspect the startup output for a successful runtime initialization, database readiness, the published host port, and any reported API documentation or health route.
Next, test a route that the selected starter explicitly documents. Use the exact local base URL and path printed by the runtime or given in the starter README. A generic request pattern looks like this:
curl -i <LOCAL_BASE_URL_AND_DOCUMENTED_API_PATH>
Replace the entire placeholder, including its angle brackets, with the verified local URL. Do not assume that the API root returns a success response. Many APIs return a legitimate 404 at the root while documented application routes work correctly. Likewise, an authentication response such as 401 or 403 can prove that the HTTP service is reachable while also showing that credentials or permissions are required.
Run the test from the same device that will host the Localtonet client. If AgentOS runs in Docker but publishes a port on the host, target the published host address and port. If it is reachable only inside a Docker network, the Localtonet client running directly on the host may not be able to use that container-only address. Adjust the starter's documented port publishing or run the client in a network position that can reach the target, without exposing unrelated services.
Interpret common local test results
| Result | Likely meaning | Next check |
|---|---|---|
| Connection refused | No process accepts connections at the tested address and port. | Check container state, startup logs, and the host port published by the starter. |
| Request times out | The target may be unreachable, blocked, unhealthy, or bound to a different interface. | Test from the service host, then from the Localtonet client host, and compare the results. |
404 Not Found |
The server responded, but the requested path is not a valid route. | Use an API path explicitly documented by the starter instead of guessing one. |
401 or 403 |
The service is reachable and is enforcing an authentication or authorization decision. | Use an authorized test identity and verify JWT or role configuration without weakening access controls. |
| Server error response | The request reached AgentOS, but an application dependency or agent action failed. | Review runtime, database, model-provider, and tool-integration logs. |
| Expected success response | The documented route is working locally. | Record the exact target and proceed to remote access configuration. |
Share the verified Agno REST API with Localtonet
Once the API works locally, an HTTP tunnel is the natural Localtonet option for its REST interface. Our client runs on a device that can reach the Agno service and establishes an outbound connection to a Localtonet relay server. The resulting tunnel provides a public HTTPS address without requiring inbound router port forwarding, a public IP address, VPN setup, or inbound firewall changes.
This tunnel should target the host-side IP address and port you verified in the previous section. It should not target PostgreSQL, a container-only address that the client cannot reach, or an administrative interface unless remote administrative access is a deliberate and secured requirement.
Install and run the Localtonet client
Install our client on the Agno host or another authorized device that can reach the verified API address and port. Keep the client running for as long as the remote endpoint must remain available.
Authenticate the correct device
Select or authenticate the device with its own Localtonet token. Tokens are device-specific and must not be guessed, copied into this article's examples, exposed in logs, or committed to the Agno repository.
Select an available relay server
Choose from the current server or region values shown in your Localtonet dashboard. Availability can vary, so do not substitute a hardcoded server code from an old tutorial.
Create an HTTP tunnel to the local API
Create the HTTP configuration using the verified local IP address and host port for AgentOS. HTTP tunnels can use a random subdomain, a custom subdomain where supported, or a custom domain. Check the current dashboard and documentation for option availability and any custom-domain DNS requirements.
Start the tunnel
Creating a tunnel does not make it active. Use the Start action and wait until the selected device and tunnel are connected. The tunnel remains available only while the client is connected and the tunnel is running.
Test the assigned public HTTPS address
Append the same documented API path used for local verification to the assigned public address, then test it with the same expected authentication behavior. Stop or delete the tunnel when remote access is no longer required.
For the current dashboard workflow and field descriptions, consult our Localtonet HTTP tunnel documentation. Use the documentation together with the actual Agno endpoint you recorded. Never substitute a sample port for the port published by your starter.
Treat the Localtonet address as network reachability, not as permission to use the Agno API. Keep AgentOS authentication and authorization enabled, use least-privilege roles, protect administrative routes, and avoid exposing the control plane or MCP service unless they have been separately reviewed and secured.
Apply a security boundary before inviting remote clients
Agent platforms can invoke tools, retrieve private knowledge, preserve sessions, and interact with external systems. A remotely reachable endpoint may therefore carry more risk than an ordinary static web page. Review both the network path and the application policy before distributing the public URL.
Require application-level authorization
Agno documents JWT-based role-based access control and multi-user, multi-tenant isolation. Confirm that the starter's actual configuration enforces the controls you expect. Test both an authorized request and an unauthorized request. A successful request proves functionality, while a rejected unauthorized request proves that the boundary is active.
Assign the smallest role needed for each client. An application that only invokes one agent should not automatically receive platform-administration permissions. Separate development, test, and production identities, and rotate any credential that has appeared in source control, logs, screenshots, or chat history.
Separate public API routes from management surfaces
The REST API, MCP server, control plane, and PostgreSQL database have different purposes. Do not expose the database through the HTTP tunnel. Do not make the control plane public merely because its container started alongside the API. If a management surface needs remote access, evaluate it as a separate service with its own authentication, authorization, and exposure decision.
Review agent tools and data access
Agno supports more than 100 integrations and can connect agents to systems such as GitHub, Slack, and PostgreSQL. Remote API access can indirectly activate those capabilities if an agent is allowed to use them. Restrict tool credentials, require human approval where appropriate, and avoid giving an internet-reachable agent broad administrative permissions.
Inspect what sessions, memory, knowledge, and traces the platform stores. Apply retention, access, and backup policies suitable for the data handled by your agents. The presence of PostgreSQL in the starter does not define those organizational policies for you.
Operate and troubleshoot the combined setup
The finished request path has several independent parts: the remote client, the public Localtonet address, our relay, the connected Localtonet client device, the local AgentOS listener, and its dependencies. Troubleshoot in that order only after confirming the local service first. A tunnel status and an application status answer different questions.
If local requests fail
Stop troubleshooting Localtonet and inspect the Agno deployment. Confirm that the Docker-based platform is running, that the database is ready, and that the expected host port is published. Review the startup logs for missing environment values, rejected provider credentials, unavailable integrations, or database initialization failures. Use a route documented by the starter rather than assuming that the root path is valid.
If local requests work but public requests fail
Confirm that the Localtonet client is connected and that the tunnel has been started. Check that the tunnel points to the same IP address and port used by the successful local test. If the client runs on a different device, repeat the local request from that device because an address reachable from the Docker host may not be reachable from another machine.
Also distinguish an HTTP application response from a connectivity failure. A remote 401, 403, or 404 means an HTTP server answered. Compare the public request path, headers, and credentials with the successful local request before changing tunnel settings.
If API calls start but agent runs fail
Inspect AgentOS and integration logs. The network path may be healthy while a model provider, external tool, database operation, or agent configuration fails. Confirm that required credentials exist in the running container environment and that the intended account has permission to use the requested resource. Avoid printing complete secret values while debugging.
If behavior changes after an update
Agno is actively released, and updates can add features, fixes, and deprecations. For example, the supplied release evidence for version 3.0.11 includes API, MCP, workflow, retrieval, provider, parsing, and compatibility changes. Review release notes and starter changes before updating a working environment. Preserve a rollback path for the repository revision, dependency state, environment configuration, and database.
After any update, repeat the local verification before testing the public endpoint. Confirm the documented API path, authentication behavior, port publication, and container health. Do not assume that a previously recorded endpoint remains correct after deployment scripts or runtime configuration change.
Routine operating checklist
| Task | What to inspect | Safe practice |
|---|---|---|
| Start the platform | AgentOS runtime, database readiness, and published host endpoint | Wait for dependencies to become healthy before opening remote access. |
| Start remote access | Correct Localtonet device, relay selection, target IP, and target port | Start the tunnel only after the local API test succeeds. |
| Test access | Documented route, expected status, and authorization behavior | Test both permitted and rejected requests without exposing credentials. |
| Monitor activity | Run history, traces, audit information, and integration failures | Investigate unusual tool usage and repeated authorization failures. |
| End a session | Active tunnel and any temporary client credentials | Stop the tunnel and revoke credentials that are no longer needed. |
| Upgrade Agno | Release notes, starter changes, dependency changes, and migrations | Back up relevant state, preserve rollback information, and verify locally again. |
Saving a Localtonet tunnel configuration does not start it. The public endpoint is available only while the selected client device is connected and the tunnel is running. If access unexpectedly stops, verify both conditions before changing the Agno deployment.
Frequently asked questions
What exactly does the official Agno starter create?
Agno states that its recommended starter workflow runs an agent platform locally using Docker and provides a REST API for serving agents, PostgreSQL for data and traces, an MCP server, and a control plane. The precise containers, ports, files, and startup commands must be taken from the current selected starter.
Can I install this Agno platform without a coding agent?
Agno presents the coding-agent workflow as the recommended way to set up a complete platform. Its main repository also notes that developers can build an agent by hand, but the supplied evidence does not contain the complete manual starter installation procedure. For the platform described here, follow the chosen starter's current README and setup skill rather than inventing manual commands.
Which local port does AgentOS use?
No universal port is established by the evidence available for this guide. Read the selected starter's README and runtime output, then verify the published host address and port locally. Use that verified value as the Localtonet HTTP target.
Why should I use an HTTP tunnel for the Agno REST API?
The service being shared is an HTTP-based REST API, so an HTTP tunnel matches that interface and provides a public HTTPS address. Our client reaches the local service through an outbound relay connection, so the workflow does not require inbound router port forwarding or a public IP address.
Does the Localtonet public URL replace Agno authentication?
No. A tunnel provides network reachability to the configured service. Keep AgentOS authentication and authorization enabled, use least-privilege roles, and test that unauthorized requests are rejected. Do not treat an unlisted or difficult-to-guess URL as an access-control mechanism.
Should I expose PostgreSQL, the MCP server, or the Control Plane too?
Not as part of this REST API workflow. PostgreSQL is a supporting data service, while the MCP server and Control Plane are separate interfaces with different security implications. Expose only the REST endpoint required by remote clients. Evaluate any additional service separately and apply its own authentication and authorization policy.
Will the public endpoint remain available if I close the Localtonet client?
No. The tunnel is available only while the selected client device is connected and the tunnel is running. AgentOS must also remain healthy and reachable from that device.
Can I use a custom domain for the Agno API?
Localtonet HTTP tunnels can use a random subdomain, a custom subdomain where supported, or a custom domain. Availability can vary, and exact DNS requirements should be checked against the current Localtonet dashboard and documentation before changing records.
Share your verified Agno API with Localtonet
Finish the AgentOS starter setup, confirm its documented API route locally, and then create an HTTP tunnel to the exact verified host address and port. Keep application authentication active and stop the tunnel whenever remote access is no longer required.
Get Started Free →
