Run Magic locally, verify its backend, and connect the complete HTTP service through a controlled public tunnel
Magic is an open-source, self-hosted platform for building full-stack applications, secured REST APIs, database-backed tools, and AI-agent workflows. This guide follows Magic’s documented Docker Compose quick start on a Debian 12 or Ubuntu 22.04 or newer Linux host, verifies the dashboard and backend locally, and installs the Localtonet client as a systemd service. We then publish the Magic backend on port 4444 through a Localtonet HTTP tunnel without inbound router port forwarding, firewall changes, VPN setup, or a public IP address. The tunnel exposes the HTTP service on that port at the network layer, so Magic authentication, roles, and route-level authorization remain essential.
📋 What's in this guide
How the Magic installation and tunnel are structured
The Magic repository describes an open-source platform that combines databases, secured APIs, authentication, role-based access control, business logic, frontend hosting, automation, and AI-agent-oriented workflows. Its current quick start uses Docker Compose to start the required services and then directs the user to two local ports.
The browser dashboard is opened at http://localhost:5555. The dashboard is then pointed at localhost:4444, which is the Magic backend. These ports have different roles and should not be treated as interchangeable.
http://localhost:5555.
Configuring the tunnel for 127.0.0.1:4444 forwards the Magic HTTP service listening on port 4444. Localtonet does not narrow this configuration to only /YOUR_API_PATH. Every backend route reachable through that public origin may become reachable at the network layer. Use Magic authentication, role-based access control, and route-level authorization to restrict what remote callers can actually access.
Keeping the dashboard on port 5555 local still reduces the number of published services. It does not mean that only one backend route is exposed. Port 4444 can serve multiple routes, including routes that may have different authentication requirements. Review the backend as a whole before publishing it.
Localtonet provides the network path. It does not replace Magic’s identity system or application policy. A secret URL is also not an authorization mechanism because URLs can be copied, logged, disclosed, or discovered.
In the Magic quick start, localhost means the machine running Docker. In the Localtonet target, it means the environment running our client. This guide installs Docker, Magic, and the Localtonet Linux service on the same host, so 127.0.0.1:4444 is the intended target. If you change that architecture, use an address the Localtonet client can actually reach.
Why local verification comes first
A public tunnel cannot repair an application that failed to start, a port conflict, an incorrect backend address, or a nonexistent API route. Testing locally separates application failures from tunnel failures. Once the backend and a real route both work through localhost:4444, you can repeat the same request through the public URL.
These tests prove different things. A connection to the backend root demonstrates that an HTTP server answered. A request to a real route tests routing and method selection. An authenticated request also tests credentials and authorization. Keep those layers separate while diagnosing a failure.
Prepare a supported Linux host
This tutorial uses the Localtonet installable DEB package on Debian 12 or Ubuntu 22.04 or newer, with an x64 or ARM64 processor. Current Localtonet package requirements include systemd 247 or newer and OpenSSL 3. The same host runs Docker, Magic, and the Localtonet service, which avoids ambiguity about the loopback target.
For Docker, install Docker Engine and the Docker Compose plugin using the instructions for your distribution. Docker maintains separate primary-source instructions for Debian and Ubuntu. Those instructions cover Docker’s supported repository and package installation paths. Do not assume that an unrelated distribution package provides the same current Compose behavior.
Before starting Magic, confirm all of the following:
- The host is Debian 12, Ubuntu 22.04 or newer, or another environment that satisfies the package requirements. This tutorial’s commands use the Debian or Ubuntu package path.
- The architecture is x64 or ARM64, and you will download the matching Localtonet DEB package.
- systemd is version 247 or newer and is the active service manager.
- OpenSSL 3 is installed.
- Docker Engine is installed and its daemon is running.
- The current user is permitted to execute Docker commands.
- The Docker Compose plugin is available through
docker compose. curlis installed and can retrieve HTTPS content.- Ports 5555 and 4444 are not already occupied by unrelated services.
- The host can retrieve the Magic Compose definition from
hyperlambda.dev. - You have a browser or another approved way to reach the dashboard on the host.
- You are authorized to publish the applications, data, and APIs connected to this Magic installation.
Run these non-destructive version checks:
docker --version
docker compose version
curl --version
systemctl --version
openssl version
uname -m
On x64 systems, uname -m commonly reports x86_64. On 64-bit ARM systems, it commonly reports aarch64. Use the architecture reported by the host to choose the corresponding Localtonet package.
Confirm that Docker can communicate with its daemon:
docker infoA daemon connection or permission error must be resolved before running Magic. Follow Docker’s supported post-installation guidance if you need to configure non-root access. Do not weaken socket permissions as a shortcut.
| Requirement | Purpose | Verification |
|---|---|---|
| Docker Engine | Runs the Magic containers | docker info reaches the daemon successfully |
| Docker Compose plugin | Reads the supplied multi-container definition | docker compose version succeeds |
| curl | Retrieves the documented Compose definition | curl --version succeeds |
| Ports 5555 and 4444 | Provide the local dashboard and backend | No unrelated process is already using them |
| systemd 247 or newer | Runs the packaged Localtonet service | systemctl --version reports a suitable version |
| OpenSSL 3 | Satisfies the current Localtonet Linux package requirement | openssl version reports version 3 |
Inspect and record the Magic configuration
The Magic quick-start command streams a remote Compose document directly into Docker Compose. The current project file can be reviewed in the Magic repository’s Compose definition. The URL used by the quick-start command is not pinned to a release or commit, so its contents can change independently of this article.
Before using the workflow in a controlled or production environment, inspect the retrieved configuration and record what you deployed. Suitable records can include the date, the project release or commit you reviewed, the Compose content, and the image references resolved at deployment time. This is a change-control recommendation, not a claim that Magic provides a specific upgrade or rollback mechanism.
The evidence available for this tutorial does not establish production sizing, canonical persistence paths, restart policies, backup commands, or a complete upgrade procedure for this installation. Verify those details against the Magic version you deploy before relying on it for important data.
Install and start Magic with Docker Compose
The current Magic quick start gives this command:
curl -fsSL https://hyperlambda.dev/docker-compose.yaml | docker compose -f - up
The curl process retrieves the Compose YAML. The pipe sends it to Docker Compose through standard input. The -f - option tells Compose to read the configuration from standard input, and up creates and starts the declared services.
Run the command from a terminal on the intended Magic host. It remains in the foreground, so keep that terminal open during initial setup. Watch its output for image download failures, port conflicts, permission errors, container exits, and application exceptions. Preparation and log observation are important, but they are not extra Magic quick-start steps.
The documented quick-start sequence is:
Run the Docker Compose command
Execute curl -fsSL https://hyperlambda.dev/docker-compose.yaml | docker compose -f - up on the prepared host and allow the services to initialize.
Open the dashboard on port 5555
Open http://localhost:5555 in a browser on the host.
Point the dashboard at port 4444
Configure the dashboard to use localhost:4444 as instructed by the Magic quick start.
Sign in
Complete the initial local sign-in with username root and password root.
The documented initial credentials are root/root. Use them only for the first local sign-in. Change the password through Magic’s supported account controls, verify that the old password no longer works, and keep the service private if you cannot confirm the change.
Password replacement is a required hardening task, not another step inserted into the upstream quick start. The exact account-management screen can vary with the installed Magic version and is not established by the supplied evidence, so this tutorial does not invent a menu name or button. Perform the change locally using the controls in your installation.
Verify the Magic dashboard and backend locally
Test port 5555 and port 4444 independently before installing the tunnel. A working dashboard does not automatically prove that every backend route works, and an answering backend does not prove that a particular caller is authorized.
Verify the dashboard
Open this address in a browser on the Docker host:
http://localhost:5555
A successful result is a usable Magic dashboard rather than a browser connection error. Point it at localhost:4444, sign in locally, and confirm that it can communicate with the backend.
If the browser is on another computer, its localhost refers to that other computer. This guide does not assume that port 5555 is reachable over the LAN or prescribe an undocumented remote-dashboard configuration.
Verify backend transport
From the Docker host, request the backend root:
curl -i http://localhost:4444The exact root status and body are not fixed by the evidence used here. An authentication response, redirect, application message, or route-specific not-found response can still show that an HTTP server answered. A connection-refused result means nothing is accepting the connection at that address. A timeout indicates that the connection was not completed.
Verify a real API route
Use a known, preferably read-only route from your own Magic application. Match the route’s actual HTTP method, content type, request body, and authentication scheme. The following is only a pattern because your route and credential format are application-specific:
curl -i \
-H "Authorization: Bearer YOUR_APPLICATION_CREDENTIAL" \
http://localhost:4444/YOUR_API_PATHDo not substitute a real credential into public documentation, screenshots, a shared shell history, support posts, or source control. If your Magic route uses a different authentication method, use the method configured by the application rather than assuming bearer authentication.
A 401 or 403 response can prove that the request reached Magic while showing that the caller was not accepted. A 404 can indicate that the backend answered but the requested path was wrong. Record the local result so you can compare it with the later public request.
Secure the entire backend before publishing port 4444
Internet reachability changes the threat model. Once the backend is public, it can receive automated scans, malformed requests, login attempts, and calls to routes other than the one you intended an integration to use. Review every relevant route exposed by the backend origin, not only the route in your first test command.
root/root locally and verify that the old password is rejected.
Keep the dashboard local by default
Port 5555 is an administrative and development surface. Publishing it creates a broader exposure than the API-only architecture in this guide. Leave the dashboard local unless you have a separately reviewed operational requirement and have verified the complete remote browser workflow.
A remote browser cannot use its own localhost:4444 to reach the backend on the Magic host. Remote dashboard use may also depend on Magic’s browser-origin and deployment behavior. Those requirements are not established here, so tunneling both ports should not be assumed to be a complete or safe solution.
Keep connectivity separate from authorization
Localtonet forwards requests to the configured local HTTP service. Magic must still authenticate the caller and authorize the requested route and operation. Do not use an administrative identity as a general integration credential, and do not rely on possession of the public URL as proof of identity.
Install and verify the Localtonet client on Debian or Ubuntu
Download the correct DEB package from the Localtonet documentation and download page. Choose localtonet-linux-x64.deb for an x64 host or localtonet-linux-arm64.deb for an ARM64 host. The package workflow documented here requires systemd 247 or newer and OpenSSL 3.
Install the downloaded package
Open a terminal in the directory containing the downloaded DEB file. For x64, run sudo apt install ./localtonet-linux-x64.deb. For ARM64, use the matching localtonet-linux-arm64.deb filename.
Set the device AuthToken and check the configuration
Edit /etc/localtonet/auth-token as root, replace DUMMY_AUTH_TOKEN with the device-specific token on a single line, protect the file with mode 600, and run the documented configuration check.
Enable and start the service
After the configuration check succeeds, enable and start localtonet.service, then inspect its journal to verify that the service is running and connecting.
For an x64 host, install the package from its download directory:
sudo apt install ./localtonet-linux-x64.debFor ARM64, use:
sudo apt install ./localtonet-linux-arm64.debEdit the token file as root using an editor approved for your environment. Put only the device-specific AuthToken on one line in place of the package placeholder. Do not include the actual token in a copied terminal transcript or article.
Protect the file and validate the configuration:
sudo chmod 600 /etc/localtonet/auth-token
sudo localtonet --headless --authtoken-file /etc/localtonet/auth-token --check-configDo not start the service until the configuration check succeeds. If it reports an invalid or missing token, correct the file rather than placing the token directly in a publicly visible command.
Enable and start the standard tunnel service:
sudo systemctl enable --now localtonet.service
sudo systemctl status localtonet.service
sudo journalctl -u localtonet.service
The status command should show that the service is active. The journal provides startup and connection details. Exit the journal view using the normal controls of your pager. This HTTP tunnel workflow uses localtonet.service, not the separate VPN service.
The AuthToken identifies the Localtonet client device. Keep /etc/localtonet/auth-token restricted, do not commit it to source control, and do not paste it into screenshots, issue reports, or application configuration. It is not a Magic API credential.
Create the Localtonet HTTP tunnel
Continue only after Magic answers locally on 127.0.0.1:4444, the default password has been replaced, and the Localtonet service is connected. The current Localtonet HTTP tunnel documentation is the primary reference for dashboard-specific configuration.
HTTP and File Server tunnels have Process Type choices such as Random Sub Domain, Custom Sub Domain, and Custom Domain. They provide a public HTTPS address for the same selected content. Available options can vary by the current product, deployment, and plan. For a first connectivity test, select an option currently available in your dashboard. Check current DNS instructions before using a custom domain.
| Service or resource | Decision for this guide | Security meaning |
|---|---|---|
| Magic backend on port 4444 | Target it with one HTTP tunnel | All routes served through that origin may become network-reachable |
| Magic dashboard on port 5555 | Keep it local | The administrative interface is not required by a normal API consumer |
| Individual Magic route | Restrict it in Magic | Authentication and authorization control route-level access |
| Database service | Do not publish it for this workflow | Remote consumers should call the application API instead of receiving direct database connectivity |
Select the connected Linux device
In the Localtonet dashboard, select the device authenticated by the token configured in /etc/localtonet/auth-token. Confirm that it is connected.
Select an available relay server or region
Choose a value currently offered in the dashboard. Do not copy a hardcoded server code from an article because available values can vary.
Create an HTTP tunnel
Select the HTTP tunnel family and an available Process Type appropriate for the deployment.
Enter the local backend target
Set the local IP address to 127.0.0.1 and the port to 4444. This is valid for the architecture in this guide because the Localtonet service and Docker host are the same machine.
Start the tunnel
Creating the configuration does not start it. Use the Start control and wait for the tunnel to enter its running state.
Copy the assigned public URL
Use the public HTTPS address shown for the running tunnel as the base URL for authorized Magic requests.
Do not treat a successful request to one intended API path as proof that every other route on port 4444 is safely configured. Test access without credentials, with invalid credentials, and with a low-privilege identity. Confirm that Magic denies routes and operations the caller should not use.
Remote access works only while Magic is healthy on the local target, the selected Localtonet device is connected, and the tunnel is running. Test these layers separately when diagnosing an outage.
Test the Magic backend through its public URL
Begin with a network-level request to the assigned public base URL:
curl -i https://YOUR_ASSIGNED_PUBLIC_URL
The root response can show that an HTTP application answered, but it does not validate every route. Compare it with the result from curl -i http://localhost:4444.
Next, repeat the same known request that succeeded locally. Change only the base URL:
curl -i \
-H "Authorization: Bearer YOUR_APPLICATION_CREDENTIAL" \
https://YOUR_ASSIGNED_PUBLIC_URL/YOUR_API_PATHPreserve the method, path, query parameters, headers, content type, and body. This controlled comparison makes it easier to distinguish tunnel problems from application problems.
Interpret common results
| Observed result | Likely meaning | Next check |
|---|---|---|
| Expected application response | The request reached the route and was accepted | Confirm that the returned data and permissions match the intended caller |
| 401 Unauthorized | The service answered but did not accept authentication | Check the configured authentication scheme and credential |
| 403 Forbidden | The identity may lack the required permission | Review Magic roles and route-level authorization |
| 404 Not Found | The backend may be reachable but the path is unavailable | Compare the remote path exactly with the local test |
| Method not allowed | The route does not accept the chosen HTTP method | Use the method defined by the endpoint |
| Gateway or upstream failure | The tunnel can be running while Magic is unavailable | Retest 127.0.0.1:4444 on the Linux host |
| Name or connection failure | The URL may be wrong, or the device or tunnel may be offline | Check the exact URL, service state, device state, and tunnel state |
Test from another network
Repeat a non-destructive request from an authorized device outside the Magic host’s local network. Confirm both successful and denied behavior. A missing credential should not receive protected data. A low-privilege identity should not perform administrative operations. An unsupported method should not modify data.
These negative tests validate Magic’s policy across the publicly reachable backend. They are especially important because the tunnel publishes the port 4444 service rather than filtering access to only the path used in your first test.
Operate, stop, and troubleshoot the deployment
Operate the foreground Magic process
The documented Compose command runs in the foreground. The standard terminal interrupt, commonly Ctrl+C, asks the foreground Compose process to stop. Observe the output and confirm that the services shut down.
This tutorial does not prescribe a detached-mode command, production service unit, container restart policy, or automated startup configuration because the supplied Magic evidence does not define a canonical production procedure for them. Establish those behaviors against the version and configuration you actually deploy.
Preserve deployment and persistence information
Because the quick-start Compose document is streamed from a mutable, unpinned URL, do not assume that running the same command later uses the same configuration or image versions. Retain a reviewed copy or another approved record of the deployed configuration and identify the release or commit associated with your review.
The available evidence does not establish the exact data-volume layout, backup process, migration sequence, or rollback procedure for this deployment. Before production use, identify where the deployed version stores databases, generated applications, configuration, uploaded files, and credentials. Build and test backup and recovery around the verified layout rather than guessing.
Do not remove containers, volumes, or host files while assuming the important state is disposable. Verify Magic’s current persistence and migration requirements for the release you use before changing a production installation.
Stop remote access independently
Stop the tunnel in the Localtonet dashboard when public access is temporarily unnecessary. Delete it when the public endpoint should no longer exist. Stopping Magic makes the local upstream unavailable, but stopping the tunnel is the clearer way to withdraw remote access intentionally.
The Localtonet Linux client can continue running while an individual tunnel is stopped. Conversely, stopping localtonet.service disconnects that client and affects tunnels assigned to it. Choose the lifecycle action that matches the scope of the maintenance.
Check the Localtonet Linux service
If the device appears disconnected, inspect systemd and the service journal:
sudo systemctl status localtonet.service
sudo journalctl -u localtonet.serviceIf configuration is in doubt, rerun the documented check:
sudo localtonet --headless --authtoken-file /etc/localtonet/auth-token --check-config
Do not reveal the token while collecting logs. If you reinstall or upgrade the package, follow the current Localtonet documentation. The current package documentation states that upgrades use the new package followed by sudo systemctl restart localtonet, with configuration preserved.
Troubleshoot Magic before the tunnel
If http://localhost:5555 does not load, inspect the foreground Compose output. Relevant categories include image retrieval failure, Docker daemon access failure, insufficient permission, a required port already in use, or a container exiting during startup.
If the dashboard loads but cannot use the backend, confirm that it points to localhost:4444. Then request http://localhost:4444 directly. Resolve a local backend failure before changing Localtonet settings.
Troubleshoot the tunnel target
For this same-host installation, target 127.0.0.1:4444. If the architecture has changed and the Localtonet client now runs on another device or in another container, its loopback address no longer refers to the Magic host. Test the proposed target from the client’s actual network context.
A separate container has its own loopback namespace. This guide does not provide a Compose service-name target because current network and service names can change with the mutable Compose definition. Do not guess them.
Troubleshoot local success but remote failure
- Confirm that
curl -i http://localhost:4444still receives an HTTP response. - Confirm that the exact API route still succeeds locally with the intended credential.
- Confirm that
localtonet.serviceis active and the device is connected. - Confirm that the HTTP tunnel has been started, not merely created.
- Confirm that the target is
127.0.0.1on port4444. - Copy the current assigned public URL again and check the hostname and path.
- Preserve the locally verified HTTP method, headers, query parameters, and body.
- Compare the remote status code and response body with the local result.
If the public root responds but a route fails, routing, authentication, authorization, or request construction is usually more relevant than basic tunnel connectivity. If the public origin does not respond at all, return to Magic health, client connectivity, tunnel state, and target selection.
Keep credentials separate
A Localtonet AuthToken identifies the client device that establishes the tunnel. A Magic application credential identifies or authorizes a caller using the backend. Neither token can substitute for the other.
Store integration credentials using the secret-management mechanism appropriate to the calling environment. Avoid command examples that leave secrets in shared shell history, and remove or rotate credentials when an integration is retired or compromised.
Understand end-to-end availability
Availability depends on the Magic containers and their dependencies, the Docker host, the local port mapping, the Localtonet Linux service, the device connection, and the running tunnel. Monitor these layers separately so an outage can be assigned to the correct component.
Localtonet also supports platform-wide Token and Tunnel webhooks for Connected and Disconnected status changes in a selected Token Group. Those notifications describe Localtonet lifecycle state. They are not Magic API request logs or application events.
Review screenshots before following interface-specific details
The figures in this article illustrate the architecture, Compose startup, tunnel flow, and remote API verification. Magic and Localtonet interfaces can change independently of these concepts. Before publication or operational use, compare interface screenshots with the current releases and rely on current product labels when a screenshot differs.
Frequently asked questions
Which Magic port should I expose through Localtonet?
For this remote API workflow, target the Magic backend on port 4444. Port 5555 is the dashboard and remains local. Publishing port 4444 makes the HTTP service on that port reachable through the public origin, not only one selected API path.
Does Localtonet restrict the tunnel to the API path in my curl command?
No. The documented configuration forwards to the HTTP service at 127.0.0.1:4444. Other routes served by that origin may also be network-reachable. Magic must enforce authentication, roles, and route-level authorization.
What are the initial Magic credentials?
The current quick start uses username root and password root. Use them only for the initial local sign-in, change the password through Magic’s supported account controls, and verify that the old password fails before publishing the backend.
Does an HTTP tunnel replace Magic authentication?
No. Localtonet provides connectivity to the backend. Magic remains responsible for authenticating callers and authorizing each route and operation. Use least-privilege application identities for integrations.
Why does localhost work for Magic but fail from another client device?
localhost refers to the environment running the process. In this tutorial, Magic and Localtonet run on the same host, so 127.0.0.1:4444 is appropriate. If the client moves to another device or container, that loopback address points somewhere else.
Do I need router port forwarding or a public IP address?
No. The Localtonet client initiates an outbound connection to our relay. This workflow does not require inbound router port forwarding, firewall changes, VPN setup, or a public IP address.
Why does the public URL return 401, 403, or 404?
These responses often mean an HTTP application answered. A 401 usually indicates missing or rejected authentication, a 403 indicates insufficient permission, and a 404 indicates that the requested path was not found. Compare the method, path, headers, and credential with the locally verified request.
Does creating a tunnel make it immediately available?
No. Creating the configuration does not start the tunnel. Use the Start control. The public endpoint remains available only while the selected device is connected, the tunnel is running, and Magic is reachable on the configured local target.
Can I use a custom domain for the Magic backend?
Localtonet HTTP tunnels support Random Sub Domain, Custom Sub Domain, and Custom Domain Process Types. Availability can vary by the current product and plan. Check the current dashboard and documentation for the applicable DNS requirements before configuring a custom domain.
Is the streamed Magic Compose configuration pinned?
No release or commit pin appears in the quick-start URL. Treat it as mutable. Inspect the current Compose definition and record the configuration, release, or commit reviewed for your deployment. Do not assume that rerunning the command later reproduces the same environment.
Does this guide define Magic backups and upgrades?
No. The available evidence does not establish a complete persistence layout, backup process, migration sequence, or rollback procedure for this quick-start deployment. Identify the behavior of the specific Magic version and Compose configuration you deploy before production use.
Connect your verified Magic backend with Localtonet
Start Magic on the Linux host, verify port 4444 locally, replace the default credentials, review every backend route, and then create a Localtonet HTTP tunnel for the complete secured service.
Get Started Free →
