Build OpenAList from Source with Localtonet Access

Understand what you are building

OpenAList is an independently maintained, community-driven fork that originated from Alist v3.45.0. It provides a browser-accessible file listing and management service that can work with local storage, cloud drives, object storage, and virtual storage drivers. The project reports support for more than 60 storage drivers and also advertises WebDAV, FTP, SFTP, and S3-compatible access.

This article deliberately focuses on the HTTP web interface. The documented default web address is http://localhost:5244, which gives us a specific endpoint that can be built, started, and tested consistently. Although OpenAList supports additional access protocols, the available evidence does not establish their ports or complete configuration procedures. We therefore do not guess those details or treat an HTTP tunnel as a substitute for a native WebDAV, FTP, SFTP, or S3-compatible connection.

Building from source is useful when you want to inspect the code you are compiling, test a particular revision, contribute changes, or avoid depending on a prebuilt package. It also places more responsibility on the operator. You must install a compatible Go toolchain and C compiler, retain the application data, manage startup and restarts, decide how updates will be reviewed, and protect any service you expose beyond the local machine.

How the completed workflow fits together

OpenAList runs on the host and listens for web requests on its local endpoint. A browser on that host can use http://localhost:5244 directly. For remote access, the Localtonet client must run on the same device or on another device that can reach the OpenAList IP address and port. The HTTP tunnel then forwards requests arriving at its assigned public HTTPS address to that local target.

These are separate layers. OpenAList remains responsible for its users, storage configuration, file permissions, application behavior, and data. Localtonet provides the network path to the local HTTP service. Creating a tunnel does not install OpenAList, configure storage, or replace application authentication.

Prepare the OpenAList build system

The documented source build has three tool requirements: Git, Go 1.27.1 or later, and a C compiler for SQLite and CGO. You also need enough local storage for the repository, Go module downloads, the compiled executable, the application data directory, and any local files you later connect to OpenAList.

You can check the two versioned command-line tools with:

git --version
go version

Compiler installation and detection differ by operating system and toolchain. The project evidence requires a C compiler but does not establish one universal compiler package or installation command. Install the compiler recommended for your operating system and Go environment rather than copying a package-manager command intended for a different platform.

Choose a service account and working directory

Decide which operating-system account will own the OpenAList process and data. For a durable installation, avoid building and running the service from a temporary directory. The documented default data directory is relative to the current working directory, so changing that directory can affect which ./data folder the process uses.

This detail matters during later restarts. Starting the same executable from a different working directory can cause the application to find or create a different relative data directory. Keep the executable, working directory, and data backup procedure clearly documented for your host.

Decide whether to build a moving branch or a reviewed revision

A plain clone followed by a build compiles the revision currently checked out by Git. For repeatable deployments, record the exact commit or release tag that you reviewed and built. Do not assume that rebuilding a moving branch at a later date will produce the same binary or dependency set.

Release tags provide a useful review boundary, but the operator should still inspect the selected release notes and verify that the revision is appropriate for the deployment. The source repository also includes a build.sh file, but the project states that this script is intended for release and CI workflows and requires an explicit build mode. It is not the normal local build command used in this guide.

Build and start OpenAList from source

The official source workflow is concise: clone the repository, enter it, build the current package with the required tag, and start the generated executable. Run these commands as the operating-system account that will own the working files, unless your deployment process intentionally separates building from runtime operation.

git clone https://github.com/AlliotTech/openalist.git

cd openalist

go build -tags=jsoniter -o alist .

./alist server

The build can download Go modules declared by the project, so the build environment needs access to the dependency locations used by the Go toolchain. If the build stops during dependency resolution, distinguish an internet, proxy, certificate, or module-fetching problem from a compiler error in OpenAList itself.

The command syntax shown above is the project-documented source workflow. Executable invocation conventions can differ across operating systems. If your platform names or launches executables differently, use the platform-appropriate form while preserving the same server argument. The supplied project evidence does not provide separate source-build commands for every operating system, so we do not invent platform-specific variants.

What a successful first start should establish

A successful start should leave the server process running and make the documented web address available at http://localhost:5244. The default data directory is ./data, relative to the process working directory, and the default configuration file is data/config.json.

Do not immediately edit configuration values merely because the file now exists. First preserve a copy, inspect the generated structure, and identify the exact setting you need to change. Configuration formats can evolve between revisions, so using the file generated by the version you actually built is safer than pasting an old example from an unrelated release.

Configure credentials, storage, and application behavior

OpenAList stores its default configuration in data/config.json. Configuration can also be supplied through environment variables prefixed with ALIST_. The evidence does not provide a complete environment-variable reference, so use only variable names documented for the OpenAList version you are running. Do not infer a variable name by converting a JSON key and assuming it will work.

Establish administrator control

A new installation needs a protected administrator account before it is exposed remotely. The Docker workflow explicitly documents that a random administrator password is printed in container logs, along with Docker-specific commands for setting or resetting that password. Those Docker commands do not apply to a source-built process, and the available source-build evidence does not establish an equivalent password retrieval or reset command.

For that reason, inspect the startup output and the administration flow presented by the exact source-built version. Confirm that you can authenticate as the administrator and replace any temporary or generated credential with a strong, unique password before creating a Localtonet tunnel. If the expected credential information is not present, consult the matching OpenAList version documentation rather than attempting Docker-only commands against the source installation.

Add storage carefully

OpenAList supports local storage and numerous external storage providers. Each provider can have different credentials, permissions, redirect requirements, token lifetimes, and path conventions. Use local tools or provider-approved authorization methods to obtain credentials. Do not submit cloud storage tokens, refresh tokens, cookies, or account passwords to untrusted online token generators.

Apply least privilege to every connected storage account. If an OpenAList user only needs to browse or download files, avoid giving the underlying provider credential unnecessary write or administrative permissions. If uploads are required, limit access to the relevant directory or bucket wherever the provider supports that restriction.

OpenAList supports protected routes and authentication for specific paths, but exact setup details are version-specific and are not included in the supplied evidence. Verify those controls in the administration interface of the version you built. Do not assume that every listed directory is private simply because the administrator interface requires a login.

Understand migration behavior

If this is a fresh OpenAList installation, the migration warning from upstream Alist does not apply. If you are reusing an existing Alist data directory, back it up before starting OpenAList. OpenAList uses a different static password salt from upstream Alist, so existing password hashes in that reused data directory will no longer validate.

After switching from Alist, reset the administrator password and then reset the passwords of other local users through the administration interface as needed. Do not expose the migrated service until you have tested account access and confirmed that old credentials are not leaving users unexpectedly locked out.

Verify the local OpenAList service

Local verification proves that the application is working independently of Localtonet. Perform these checks from the OpenAList host before diagnosing tunnels, DNS, or remote browser behavior.

Open the documented local address

On the same machine as the running process, open:

http://localhost:5244

The OpenAList web interface should load. If it does, confirm that page assets render correctly, administrator authentication works, and the administration area is accessible only with the intended credentials. Add a limited test storage target or inspect an already configured target, then verify that file listings and intended operations behave correctly.

A page that loads is necessary but not sufficient. Test the particular workflow you plan to use remotely. For example, if the deployment is intended for read-only browsing, verify directory navigation and a permitted download. If uploads are intended, test them with a non-sensitive file and confirm where the file is stored. Remove the test file afterward if it is no longer needed.

Confirm the runtime directory

Verify that data/config.json and the rest of the ./data directory are being created or read beneath the intended working directory. Restarting from another directory can change the meaning of a relative path, so record the directory from which ./alist server is launched.

Test from the Localtonet client host if it is different

When the Localtonet client runs on the OpenAList machine, the tunnel can normally target the loopback service at 127.0.0.1 on port 5244. If the client runs on another device, 127.0.0.1 would refer to that other device, not the OpenAList host. In that topology, the client device must be able to reach an appropriate local network address for the OpenAList host.

The project evidence establishes the default localhost endpoint, but it does not establish the exact OpenAList listener configuration required for access from another LAN device. Do not assume the service is listening on all network interfaces. Either run the Localtonet client on the same host or verify the relevant OpenAList listener configuration for your installed version before using a separate tunnel device.

Run, back up, and update the source-built service

The documented command ./alist server runs the application directly. During initial testing, foreground operation is useful because messages remain visible. For unattended operation, use a process supervisor appropriate to your operating system, but define it around the verified executable, working directory, runtime user, and data directory.

The available project evidence does not specify a universal system service definition. Service managers differ across Linux distributions, Windows, macOS, containers, and NAS platforms, so this guide does not fabricate one. Whatever supervisor you select should start OpenAList from the same working directory used during testing, retain logs, restart it according to your policy, and avoid running it with unnecessary operating-system privileges.

Back up the persistent data

Treat the ./data directory as persistent application state. Before migration, configuration changes, or upgrades, create a recoverable backup using a method appropriate to your filesystem and deployment. Protect backups because configuration data can contain sensitive provider details or references to connected storage.

A backup is only useful if restoration has been tested. On a non-production copy, confirm that the backed-up data can be restored with the expected ownership and permissions. Keep the OpenAList version associated with each backup so that you can reason about configuration compatibility during recovery.

Plan controlled source updates

A source installation does not update itself merely because the repository has a newer release. A controlled update should identify the target revision, review its release information, back up the current data, stop the running process cleanly, build the selected source, and verify the new executable locally before restoring remote access.

Retain the previously working executable or another tested rollback path until the update has passed local and remote checks. Avoid rebuilding directly over the only known-good binary without a recovery plan. If an update changes storage drivers or authentication behavior, test those areas explicitly rather than relying only on the home page loading.

Know the alternative installation methods

Docker image variants are published with different bundled components: the standard image contains OpenAList, the ffmpeg variant includes FFmpeg, the aria2 variant includes aria2, and the aio variant includes OpenAList, FFmpeg, and aria2. Published Docker images cover Linux AMD64 and ARM64. Those image variants do not change the source-build procedure in this article.

Connect OpenAList through a Localtonet HTTP tunnel

Once http://localhost:5244 works reliably, you can add remote access. With Localtonet, the client application on the selected device establishes an outbound connection to one of our relay servers. This means you do not need to configure inbound router port forwarding, change inbound firewall rules, set up a VPN, or obtain a public IP address for this workflow.

An HTTP tunnel is the appropriate choice for the documented OpenAList browser endpoint. It forwards web traffic to the local IP address and port you configure. It does not automatically expose OpenAList's separate WebDAV, FTP, SFTP, or S3-compatible protocols, and it should not be described as a VPN.

HTTP tunnels can use a Random Sub Domain, Custom Sub Domain, or Custom Domain process type. All three serve the configured content at a public HTTPS address. Availability can vary by plan or current product configuration, and custom-domain DNS requirements must be checked against current documentation before making DNS changes.

For the current dashboard workflow and available options, consult our Localtonet HTTP tunnel documentation. Use the dashboard values shown for your account instead of relying on server names, region codes, or options copied from an older guide.

Apply a layered security checklist

Remote access should preserve the principle that each layer has a separate responsibility. OpenAList controls application users, paths, storage drivers, and file operations. The operating system controls the process account and local files. Localtonet carries requests between the public endpoint and the configured local target. Securing one layer does not remove the need to secure the others.

Keep tokens and provider credentials out of diagnostics

Troubleshooting information can contain secrets. Before sharing OpenAList logs, configuration excerpts, screenshots, or Localtonet dashboard captures, remove authentication tokens, provider credentials, private URLs, cookies, user names, and sensitive paths. Do not commit generated configuration or secrets to a public source repository.

Use separate accounts for separate people

Avoid sharing the administrator credential for routine file access. Where the installed OpenAList version supports the required user and path controls, create accounts with permissions aligned to each person's task. Administrative access should be reserved for configuration and maintenance.

Do not expose development mode as production

The OpenAList development workflow starts a Go backend and frontend development server together. It requires a separate frontend repository, Node.js 22.22.1 or later, pnpm 11, and normally expects the backend and frontend repositories to be sibling directories. That workflow is intended for development and contribution work, not as a shortcut for the source-built service described here.

Troubleshoot build, startup, and tunnel failures

The Go build reports an unsupported version

Run go version in the same shell used for the build. OpenAList requires Go 1.27.1 or later according to the supplied project documentation. If multiple Go installations exist, verify that the shell resolves the intended executable rather than an older copy earlier in the system path.

The build fails around CGO, SQLite, or a C compiler

Confirm that a compatible C compiler is installed and available to the Go toolchain. A Go-only setup is not sufficient for the documented SQLite and CGO requirement. The exact compiler package varies by operating system, so use the toolchain recommended for the host rather than guessing from another distribution.

Go cannot download modules

Check outbound network access, DNS resolution, proxy settings, certificate trust, and any organization-specific Go module policy. A module-fetching error occurs before or during dependency resolution and is different from a source compilation error. Preserve the exact error text when diagnosing it, but redact private proxy addresses or credentials before sharing it.

./alist server does not start

Confirm that the build completed and that the alist executable exists in the current directory. Verify that the runtime account can execute it and write to the intended working directory. Read the process output for a specific configuration, database, permission, or port error rather than repeatedly restarting it without changing the underlying condition.

The browser cannot open localhost:5244

First confirm that the OpenAList process is still running. Then verify that you are testing from the same host and using the exact HTTP URL and port. If another process already occupies port 5244, inspect the conflict before changing application settings. The evidence establishes the default port but does not provide a complete port-change procedure, so follow the configuration reference for the exact OpenAList version if a different port is necessary.

OpenAList starts with an unexpected empty configuration

Check the current working directory. Because the default data location is ./data, launching the executable from another directory can point it at a different relative data directory. Stop the process before moving or replacing state, verify your backups, and restart it from the intended working directory.

The local interface works but the Localtonet URL does not

Confirm that the Localtonet client is connected, the correct device token was selected, the HTTP tunnel is started, and the local target is correct. If both processes run on the same host, verify 127.0.0.1 and port 5244. If they run on different devices, test the OpenAList address directly from the Localtonet client device before blaming the public tunnel.

Also remember that tunnel creation and tunnel startup are separate actions. A saved configuration does not provide a live public endpoint until it has been started, and the endpoint remains available only while the selected client is connected and the tunnel is running.

The public page loads but login or file operations fail

Compare the same action locally and remotely. If it also fails locally, investigate OpenAList users, route protection, storage credentials, provider permissions, and application logs. If it fails only through the public address, capture the browser behavior and relevant logs while removing secrets. Avoid broadening storage or user permissions merely as a diagnostic shortcut.

Passwords fail after migrating from Alist

This is expected when reusing an upstream Alist data directory because OpenAList uses a different static password salt. Restore from backup if needed, reset the administrator password using the procedure appropriate to the installed OpenAList version, and reset other local user passwords through the administration interface. Fresh installations are not affected by this migration-specific issue.

Frequently asked questions