Self-Host AI Maestro with Localtonet Remote Access

Choose the right AI Maestro deployment path

AI Maestro is an open-source orchestration platform for terminal-based AI agents. Its current project material advertises four deployment modes: local tmux, Docker, AWS EC2, and AWS ECS Fargate. Those are distinct operational models, not interchangeable installation commands.

This tutorial deliberately narrows its hands-on scope to the local tmux quick start on Linux and Windows through WSL2. These are the installation paths for which the supplied project evidence provides concrete prerequisites, commands, and a local dashboard endpoint. The guide does not present the quick-start commands as the only complete ways to deploy AI Maestro.

The AI Maestro website also describes use on a MacBook, and the project states that it runs where Node.js and tmux are available. However, the evidence supplied for this revision does not provide a complete, current macOS installation and service-lifecycle procedure. We therefore do not turn Linux package commands into unverified macOS instructions. macOS users should consult the current AI Maestro repository and its project documentation before selecting a deployment method.

Understand the local-first architecture

AI Maestro is designed around a browser dashboard that can discover and organize agents, present terminal activity, retain operational context, and support communication between agents. The project lists Claude Code, Codex, Grok Build, Cursor, OpenClaw, Hermes, Droid, and other terminal-based agents as examples of tools that can fit this model.

An agent is treated as a persistent member of a working environment rather than as a disposable task. It can have a name, working directory, memory, inbox, and responsibility for one or more repositories or processes. The dashboard gives the operator a central place to see and switch between these agents.

Multi-machine operation does not mean that every agent shares one filesystem. The project recommends independent working copies and Git-based collaboration. When two agents need the same repository, each can use its own clone and branch, then integrate work through push, review, and merge. That model continues to work when agents move between laptops, servers, containers, and cloud hosts.

In this architecture, AI Maestro is the application and Localtonet is the connectivity layer. Our client establishes an outbound connection from the selected device, so you do not need inbound router port forwarding or a public IP address. The application must still be healthy and reachable from the device running our client.

Keep those responsibilities separate while troubleshooting. First make AI Maestro respond locally. Next verify the Localtonet client or VPN connection. Only then test from the remote device. A connectivity layer cannot repair missing dependencies, a stopped application, or an occupied local port.

Prepare Linux or Windows WSL2

The current AI Maestro quick start lists Node.js 18 or newer and tmux as requirements. The remote installer is described as installing the dashboard and service, the agent messaging components, and a Claude Code plugin with associated skills and scripts. Claude Code is optional for the general dashboard, although Claude-specific functionality naturally requires a compatible Claude Code installation.

Choose a host that remains available whenever you need its agents. If the computer sleeps, shuts down, loses connectivity, or stops AI Maestro, the dashboard will not be reachable. Localtonet does not change the host's uptime or application lifecycle.

Prepare a Debian or Ubuntu-style Linux host

Update package metadata according to your normal administration policy, then install the two Linux packages explicitly identified by the project:

sudo apt install tmux build-essential

That command does not install Node.js, Git, or Yarn. Install those through the version and package-management method approved for your distribution or organization. A universal Node.js command would be misleading because distribution repositories and supported versions vary.

Check the required commands before continuing:

node --version
tmux -V
git --version
yarn --version

The Node.js result must show version 18 or newer. The remaining commands should return version information rather than a command-not-found error.

Install WSL2 on Windows

AI Maestro's documented Windows path uses WSL2. Open PowerShell as Administrator and use Microsoft's current installation command:

wsl --install

Restart Windows if prompted, open the installed Ubuntu environment from the Start menu, and complete the Linux preparation inside that Ubuntu shell. Microsoft documents the current requirements, supported Windows versions, distribution selection, and troubleshooting in its WSL installation guide.

Run the AI Maestro installer and development commands inside WSL2, not directly in PowerShell or Command Prompt. Keep agent working directories in the Linux filesystem, such as:

~/agents/<agent-name>

The AI Maestro project recommends this location instead of a mounted C:\ directory because access to Windows-mounted project files can be slower from WSL. Windows can browse the Ubuntu home directory through a path such as:

\\wsl.localhost\Ubuntu\home\<your-user>\agents

Replace Ubuntu if your installed distribution uses another name.

Install and start AI Maestro

The current project landing page provides a remote quick-start installer and a manual source workflow. They are two quick-start choices within a project that also advertises Docker, EC2, and ECS Fargate deployment modes. Select one method appropriate to this Linux or WSL2 scope, and do not mix both methods in the same working directory.

Option 1: run the remote quick-start installer

curl -fsSL https://raw.githubusercontent.com/23blocks-OS/ai-maestro/main/scripts/remote-install.sh | sh

The project describes this installer as providing the dashboard and service, Agent Messaging Protocol components, and Claude Code plugin components. Installer behavior is version-sensitive, so read its completion output instead of assuming that a returned shell prompt means every component started successfully.

Option 2: use the manual source workflow

The manual workflow creates a visible checkout of the official AI Maestro repository. This is useful when you need to inspect the source and dependency files before installation.

git clone https://github.com/23blocks-OS/ai-maestro.git
cd ai-maestro
yarn install
yarn dev

For this manual path, stopping the foreground development process normally means returning to its terminal and sending the terminal interrupt, commonly with Ctrl+C. Restart it by returning to the same repository checkout and running yarn dev again. This is a development lifecycle, not a boot-persistent deployment design.

Before adopting AI Maestro as a continuously available service, choose and validate one of the project's documented deployment modes. Define how it starts after reboot, where state is stored, how logs are retained, how health is checked, and how updates are rolled back. Those decisions differ substantially between tmux, Docker, EC2, and ECS Fargate.

Verify the local dashboard

Open a browser on the AI Maestro host and visit:

http://localhost:23000

A successful result is the AI Maestro dashboard, not a connection error, an unrelated application, or a generic web server page. This confirms that an HTTP service is accepting connections on the documented local endpoint.

With the manual workflow, keep the terminal running yarn dev visible. Build errors, stack traces, and startup failures there are usually more useful than a browser's generic connection message. If the process exits, investigate its first meaningful error before restarting it.

Request the local endpoint from the command line

curl -I http://localhost:23000

The exact response status and headers may change with current application routing, so this guide does not require one specific status code. A connection-refused error usually means no process is listening on that address and port. An HTTP response confirms that the TCP connection reached a web service, but you should still open the page and confirm that it is AI Maestro.

Verify inside WSL2 first

If the Windows browser cannot reach the service, run the command-line check from the WSL2 Ubuntu shell where AI Maestro is running. If it works inside WSL but not from Windows, investigate current Windows-to-WSL localhost integration. If it fails inside WSL too, return to the AI Maestro startup output before changing networking settings.

Check for a port collision

If startup reports that the address is already in use, identify the process occupying port 23000. Do not terminate an unknown service until you know what it is. The supplied evidence does not document a supported alternative-port setting, so this guide does not invent an environment variable or command-line flag.

Create and validate your first agent

Loading the dashboard proves that the web service responds. Creating an agent validates more of the actual workflow. The current project material describes a guided creation process using the plus button in the sidebar.

AI Maestro can auto-discover tmux sessions, so tmux must be available to the same user and in the same environment as the dashboard. The project also describes heartbeat-based standalone agents, but the integration details depend on the agent and are outside this Linux and WSL2 quick-start scope.

Avoid making several agents modify the same working directory unless you have deliberately designed that workflow. Separate clones and branches reduce the chance that one agent overwrites another agent's uncommitted changes. Use Git as the explicit integration boundary.

Use Localtonet VPN Manager for private remote access

The available AI Maestro documentation does not establish that the dashboard requires users to authenticate or enforces authorization between viewers. For that reason, our recommended remote-access design is a private mesh through Localtonet VPN Manager rather than a public HTTP URL.

VPN Manager is Localtonet's private mesh VPN feature. It can connect authorized devices and bridge local networks, with granular firewall rules controlling permitted traffic. This is different from a standard HTTP, TCP, UDP, or File Server tunnel. Those tunnel types expose a specific service through a public address, while VPN Manager creates private network connectivity between approved participants.

Install the Localtonet client on the reachable host

Sign in to your Localtonet account and download the current client package for the operating system that will participate in the private network. Run the package using the normal installer mechanism for that platform, launch the client, and associate it with the device-specific authentication token supplied through your account.

Install the client either on the AI Maestro host or on another authorized device that can already reach it. Keep the client active whenever remote connectivity is required. Client packaging and installation commands can change by platform and release, so obtain them from the current dashboard rather than copying an old package URL or unverified command.

Build the private-access policy

Use the current VPN Manager interface to create or select the private mesh, add only the devices that require access, and apply firewall rules that limit the remote client to the AI Maestro host and dashboard port. The intended policy is narrow:

• The operator's approved remote device may reach the AI Maestro host.
• Access is limited to TCP port 23000 unless another service is explicitly required.
• Unrelated mesh participants should not receive dashboard access by default.
• The AI Maestro host should not gain unnecessary access to other private devices.

Exact rule names and interface fields can change, so copy the current device and network values from your own dashboard. Do not reuse example addresses from another deployment. For the maintained product overview, see our VPN Manager private mesh guide.

Test from an authorized remote device

Connect the remote device to the same authorized VPN Manager network. Open the AI Maestro dashboard using the private VPN address assigned or routed to the AI Maestro host, followed by port 23000. Do not use localhost on the remote computer because that name always refers to the remote computer itself.

Confirm that the dashboard works from the approved device and remains unavailable from a device that is not part of the mesh. This positive and negative test verifies both reachability and isolation. If the approved client cannot connect, test the dashboard locally again, check both clients' connection state, verify the destination address, and review the VPN firewall rule.

Use a public HTTP tunnel only with verified access controls

A Localtonet HTTP tunnel can provide a public HTTPS address for an application listening on a local IP address and port. It does not, by itself, establish who is allowed to operate the application behind that address. Because this revision cannot verify native AI Maestro dashboard authentication, direct public tunneling to port 23000 is inappropriate for the default installation described here.

An acceptable public design requires more than a login page that protects only the initial HTML document. The access-control layer must cover the complete application path, including real-time terminal traffic and API requests. It should enforce authenticated identities, restrict authorized users, terminate sessions appropriately, and be maintained as part of the deployment. No such reverse-proxy configuration is supplied in the evidence for this article, so we do not invent one.

Conditional HTTP tunnel sequence

If a qualified administrator has already implemented and tested that independent protection, point Localtonet at the protected local endpoint rather than bypassing it and targeting an unprotected AI Maestro process directly.

Custom-domain DNS requirements are version-sensitive and must be taken from the current Localtonet HTTP tunnel documentation. Do not guess DNS records or validation values.

The public address remains usable only while the selected Localtonet client is connected, the tunnel is running, and the protected local endpoint is healthy. Stop or delete the tunnel when public reachability is no longer required.

Harden the complete deployment

AI Maestro can display or control sensitive operational context. Depending on configuration and agent activity, the dashboard may expose repository names, working directories, terminal output, messages, conversation context, logs, private code, or actions that influence running agents. Treat access to the dashboard as privileged administrative access.

Review project security guidance and releases

Before remote access, review the project's security policy and current releases. Security behavior is version-sensitive, so identify the revision you actually installed rather than relying on a release number mentioned in an older tutorial.

For example, AI Maestro release v0.62.0 documented fixes for unsafe identifiers, path handling, and shell-command construction. Its release note explicitly advised users who expose AI Maestro beyond a trusted network to update. It also documented route-parity corrections and tests involving hostile identifiers and real-server startup.

That release is evidence that version review matters, not a guarantee that v0.62.0 is the newest or sufficient release when you read this. Check later release notes and the current security policy before exposing or upgrading an active installation.

Localtonet provides connectivity, not permission to disregard organizational controls. Obtain authorization before making a workplace service remotely reachable, comply with data-handling requirements, and avoid granting an AI agent broader credentials simply because its dashboard is privately accessible.

Operate, update, and troubleshoot the setup

Troubleshooting is fastest when each layer is tested independently. Begin with the AI Maestro process, then the local HTTP endpoint, then the Localtonet connection, and finally the remote client.

Use a layered diagnostic sequence

1. Confirm that the AI Maestro process is alive.
2. Request http://localhost:23000 from the same environment.
3. Open the dashboard locally and confirm it is the expected application.
4. Check the Localtonet client and private mesh connection state.
5. Confirm that the remote device is authorized by the relevant firewall rule.
6. Test the private destination address and port from that remote device.

This sequence prevents two common mistakes: changing a correct network configuration while the application is stopped, and reinstalling the application when only the remote access path is disconnected.

Understand address scope

localhost always identifies the environment in which the requesting process runs. On the AI Maestro host, it points back to that host. On a remote laptop, it points back to the laptop. If a Localtonet client runs in a container, another virtual machine, or another physical device, its loopback address does not refer to the AI Maestro host.

The supplied evidence confirms the local endpoint but does not establish every supported bind-address, container, or alternative-port setting. If your architecture requires AI Maestro to listen beyond loopback, verify the current project configuration rather than guessing an environment variable.

Update cautiously

Before an update, record the installed revision, preserve important application and agent state using the project's current guidance, and read all intervening release notes. The repository contains update-related scripts, but this article does not claim a stable invocation or rollback contract without verified documentation for those scripts.

After an update, repeat the local checks before restoring remote access. Confirm that the dashboard opens, expected agents appear, and essential operations work. If the update fails, use the rollback procedure documented for the deployment mode you selected. A source checkout, Docker deployment, EC2 host, and ECS task can require different rollback strategies.

Plan for host restarts

Do not assume that yarn dev returns automatically after a reboot. If you are using the manual quick-start path, plan to enter the repository and restart it yourself. For continuous service, move to a documented supervised deployment and test boot recovery before depending on remote availability.

Stop access cleanly

When remote access is no longer required, disconnect the remote device or remove its permission from the private mesh. For a conditional public HTTP tunnel, use the tunnel's Stop control and delete the configuration if it will not be reused. Before stopping AI Maestro, check whether active agents have uncommitted work or incomplete operations.

Frequently asked questions