Set Up Atomic Chat on Linux and Connect with Localtonet

How Atomic Chat and Localtonet fit together

Atomic Chat is an open-source local AI desktop application and inference engine. Its current repository documents an OpenAI-compatible server at http://localhost:1337/v1. Applications that support the OpenAI API format and allow a custom base URL can point to this local endpoint instead of a hosted API.

Chat completion requests use http://localhost:1337/v1/chat/completions. Atomic Chat binds the service to 127.0.0.1 by default. Loopback binding means a process on the same Linux computer can reach the service, while another computer cannot connect to it directly through the LAN.

Atomic Chat also documents changing the host to 0.0.0.0 for LAN exposure. That broader binding is not required for this Localtonet layout. When our client runs on the same Linux computer, it can forward requests to 127.0.0.1:1337 while Atomic Chat remains unavailable through the host's ordinary LAN interfaces.

The Localtonet client establishes an outbound connection to a Localtonet relay server. An HTTP tunnel provides a public HTTPS URL and forwards incoming HTTP traffic to the configured local IP address and port. This avoids inbound router port forwarding, firewall changes, VPN setup, and a public IP requirement. The public path exists only while the selected client is connected and the tunnel is running.

For current project information, use the official Atomic Chat website and the Atomic Chat repository documentation. Product behavior can change between releases, so compare the installed release with the current project documentation before exposing any service.

Prerequisites for Linux x86_64

The current Atomic Chat download page identifies its Linux desktop download as Linux x86_64. This article does not claim Linux ARM support or compatibility with every Linux distribution because the supplied project evidence does not establish either point. Confirm the machine architecture before downloading the application:

uname -m

An x86_64 system commonly reports x86_64. If the command reports an ARM architecture such as aarch64, do not assume the x86_64 desktop download will run. Check the current project releases for a separately documented artifact that matches the computer.

The project lists local model families such as Llama, Gemma, Qwen, Mistral, and Phi. Availability can change, and an individual model may have its own license, access conditions, storage requirements, or hardware expectations. Start with a model appropriate for the available computer rather than assuming every listed model will fit.

Download and install the current Atomic Chat desktop release

Begin with the official Atomic Chat download page. It currently presents a Linux x86_64 download. You can also inspect the project's latest GitHub release before installation.

Release packaging can change. The current web evidence confirms the Linux x86_64 download but does not expose enough release-asset detail to guarantee that every current or future Linux download uses the same filename or package format. Check the downloaded filename before applying package-specific instructions.

If the downloaded file is an AppImage

Use the following workflow only when the current official asset actually has an .AppImage filename. The AppImage quick-start guidance explains the same basic executable-permission requirement.

chmod u+x "/full/path/to/the-downloaded-file.AppImage"
"/full/path/to/the-downloaded-file.AppImage"

Replace the example path with the real filename and location. Quoting the path prevents spaces from being interpreted as separate shell arguments.

If the official download uses another package format

Do not rename it to .AppImage or apply AppImage commands to it. Follow the package instructions attached to that release. The supplied evidence does not establish a universal package-manager command for every Linux distribution or every possible Atomic Chat artifact, so this article does not invent one.

Load a model and prepare the inference service

Once the Atomic Chat window opens, choose a model that fits the computer. The project's basic user workflow is to download Atomic Chat, pick a model, and start chatting. Complete that desktop workflow before testing the HTTP API.

Atomic Chat exposes its inference engines through the same documented API base URL. Compatible tools do not need to know which engine is active underneath the API. The model field must still identify a model recognized by the running application.

Verify the OpenAI-compatible API locally

Local verification is the most important checkpoint. A tunnel cannot start Atomic Chat, load a model, correct a model identifier, or resolve a local port conflict. Do not continue until the same Linux computer can reach the API directly.

With Atomic Chat running and a model loaded, replace the model placeholder and send the documented chat completion request:

curl http://localhost:1337/v1/chat/completions \
  -H "Content-Type: application/json" \
  -d '{
    "model": "<model-id-loaded-in-atomic-chat>",
    "messages": [
      {
        "role": "user",
        "content": "Say hello in one word"
      }
    ]
  }'

A successful result should be structured JSON in an OpenAI-compatible chat completion format. Generated text and response time depend on the model and hardware. The important result is that the server accepts the request, recognizes the model, performs inference, and returns a completion instead of a connection or model error.

Optional Python client check

Atomic Chat's repository also demonstrates the OpenAI Python client with a custom base_url. The value not-needed is only a placeholder for client libraries that require a nonempty API-key setting.

from openai import OpenAI

client = OpenAI(
    base_url="http://localhost:1337/v1",
    api_key="not-needed",
)

response = client.chat.completions.create(
    model="<model-id-loaded-in-atomic-chat>",
    messages=[
        {
            "role": "user",
            "content": "Say hello in one word",
        }
    ],
)

print(response.choices[0].message.content)

This check assumes Python and a compatible OpenAI package are already installed. Those are client-side dependencies, not AppImage or Atomic Chat runtime requirements. Use curl first when you want the smallest diagnostic path.

Create a temporary Localtonet HTTP tunnel

This section directly publishes Atomic Chat's unauthenticated API for a short connectivity test. Do not treat the resulting URL as a protected endpoint. Keep the test supervised, avoid sensitive prompts, and stop the tunnel immediately after verification.

Review the current Localtonet documentation for the supported Linux client installation path. The supplied evidence does not include a stable distribution-specific installation command that we can safely reproduce for every Linux system, so we do not invent a package command here. Install and run the current Localtonet client on the same Linux x86_64 computer that is running Atomic Chat.

For the tunnel itself, use the Localtonet HTTP tunnel documentation alongside the sequence below. Current server and region choices must come from the dashboard rather than from hardcoded examples.

If the assigned public origin were represented as https://your-assigned-host.example, the API base would conceptually be:

https://your-assigned-host.example/v1

The hostname above is deliberately illustrative and is not a real Localtonet endpoint. Copy the actual public URL from the running tunnel. Test the chat completion path with a non-sensitive prompt:

curl "https://your-assigned-host.example/v1/chat/completions" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "<model-id-loaded-in-atomic-chat>",
    "messages": [
      {
        "role": "user",
        "content": "Reply with the word connected"
      }
    ]
  }'

Replace both placeholders. A successful result proves public connectivity to the local API. It does not prove caller authentication because the request contains no credential that Atomic Chat validates.

Understand transport security, URL secrecy, and caller authorization

These are separate controls and should not be treated as interchangeable. An HTTPS URL protects transport differently from an application credential, and an unlisted hostname is not an identity check.

A Localtonet HTTP tunnel does not transform the placeholder key into authentication. For recurring use, multiple users, unattended operation, or access to sensitive prompts, do not point the public tunnel directly at Atomic Chat. Place a separately verified authentication gateway in front of the local API and point Localtonet at that protected target.

This article does not provide a gateway configuration because no specific gateway product, version, installation method, credential format, or policy has been established by the supplied evidence. A partial example would create the false impression of an operational authorization solution. Before publishing a protected endpoint, verify both of these outcomes:

• A request without valid credentials is rejected by the gateway and never reaches Atomic Chat.
• A request with valid credentials is accepted and returns a completion through the same protected path.

Also apply the controls appropriate to the selected gateway and environment, including least privilege, credential rotation, rate or request limits, logging that avoids prompt leakage, and a process for revoking access.

Operate and stop the service reliably

The end-to-end request path has four runtime layers: the Atomic Chat desktop process, the loaded model and inference engine, the Localtonet client, and the HTTP tunnel. Remote requests fail if any layer is unavailable.

Start each layer in a testable order

1. Open Atomic Chat.
2. Load the intended model and test it in the desktop interface.
3. Run the local curl request against localhost:1337.
4. Start the Localtonet client.
5. Start the configured HTTP tunnel.
6. Run the controlled remote request.

This order gives you a known working checkpoint before each new layer is introduced. If the final request fails, repeat the local curl test before changing the tunnel.

Stop exposure without stopping local inference

Stopping the Localtonet tunnel removes the public route while Atomic Chat can continue serving local applications. Creating a tunnel does not mean it is running, and a stopped tunnel can be started again later if the configuration is retained. Delete configurations that will not be reused.

Handle model changes carefully

Client requests name a model. If the active model changes, the client may need a different model identifier even though the /v1 base URL remains the same. Verify the replacement model locally before starting another remote test.

Allow for local inference latency

Model startup and generation time depend on the model, context, inference engine, and hardware. A remote client can time out while Atomic Chat is still working. Measure the local response first and adjust the client according to observed behavior rather than assigning an arbitrary universal timeout.

Keep the local health check

Preserve the curl request as a routine diagnostic. If it succeeds while the remote request fails, investigate the Localtonet client, selected device, tunnel state, public URL, or remote client configuration. If it fails locally, troubleshoot Atomic Chat before changing Localtonet.

Troubleshoot installation, API, and tunnel failures

Remember what loopback means

Test 127.0.0.1:1337 on the computer running Atomic Chat. Testing that address from another computer reaches the other computer's own loopback interface, not the Atomic Chat host.

Check for a duplicate API path

Many OpenAI-compatible clients expect a base URL such as https://assigned-host/v1 and append /chat/completions themselves. Entering the full completion route into a base URL field can produce a duplicated and invalid path.

Separate tunnel state from application state

A connected Localtonet client does not prove that Atomic Chat is responding. A working Atomic Chat desktop chat does not prove that the HTTP tunnel is started. Test each layer independently and avoid changing multiple settings at once.

Separate future authorization errors from inference errors

If you later add an authenticated gateway, an authorization rejection should occur before Atomic Chat handles the request. A model error indicates that the request progressed to an application layer that evaluated the model field. Test both layers independently.

When to build Atomic Chat from source instead

Most users should start with the released Linux desktop download. Building from source is more appropriate for contributors, developers inspecting implementation details, or users testing unreleased changes.

The current repository contains development documentation and a Makefile, but the supplied evidence does not expose the current contents needed to verify every prerequisite version, dependency-installation command, system package, and development target. Earlier instructions should not be treated as current merely because they once named particular Node.js, Yarn, Rust, or Make versions.

Before attempting a source build, inspect the current Atomic Chat development documentation, the repository's current package metadata, and the instructions for the exact commit or release you intend to build. Follow those files as a single versioned set rather than combining commands from unrelated releases.

Frequently asked questions