Set Up Atomic Chat on Linux and Connect with Localtonet

How the Atomic Chat and Localtonet workflow fits together

Atomic Chat is a local AI desktop application and inference engine for running open-weight language models on the user's computer. Its local API follows the OpenAI API format, which allows compatible agents, command-line tools, IDE integrations, and applications to use a locally loaded model by changing their API base URL.

The documented base URL is http://localhost:1337/v1. Chat completion requests are sent to http://localhost:1337/v1/chat/completions. Atomic Chat binds this service to 127.0.0.1 by default. That loopback address means software on the same Linux computer can reach it, but another computer on the LAN cannot connect directly.

This default is useful because it reduces accidental network exposure. A local application can connect to the API while the service remains unavailable on other network interfaces. Atomic Chat documents changing its host to 0.0.0.0 when LAN exposure is required, but that change is not necessary for the preferred Localtonet layout in this guide. When the Localtonet client and Atomic Chat run on the same Linux computer, our client can forward requests to 127.0.0.1:1337.

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

Prerequisites for installing Atomic Chat on Linux

The Atomic Chat download page identifies the Linux desktop package as an x86_64 download. Confirm that the computer uses a compatible architecture before downloading the AppImage. The available evidence does not establish support for Linux ARM packages, individual distributions, minimum RAM, minimum disk capacity, or specific GPU drivers, so those requirements should not be guessed.

Model resource requirements vary substantially. A small quantized model may run on hardware that cannot load a larger model. Available system memory, GPU memory, storage, model format, context length, and inference backend can all affect whether a model starts successfully and how quickly it responds. Choose a model appropriate for the machine rather than assuming every model listed in the application will fit.

You will also need permission to download a model if it is not already present. Some model repositories may impose their own license acceptance or access requirements. Atomic Chat supports models from Hugging Face, but the exact availability and conditions of an individual model come from that model's publisher.

Install Atomic Chat from the Linux AppImage

The AppImage route is the most direct documented installation path for a Linux user who wants to run the released desktop application. It avoids the Node.js, Yarn, Make, and Rust toolchain required for a source build. Download the Linux package from the official Atomic Chat website or the project's official release page rather than from an unofficial mirror.

A terminal-based permission command follows this general form:

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

Launch the same file after applying the permission:

"/full/path/to/the-downloaded.AppImage"

Replace the example path with the exact downloaded filename and location. Quoting the path prevents spaces in a directory or filename from being interpreted as separate shell arguments.

This guide does not prescribe a system-wide AppImage installation directory, desktop integration utility, or package-manager conversion because the supplied project evidence does not establish one required method. Running the official AppImage directly is sufficient for the documented workflow.

Load a model and prepare the inference service

Once Atomic Chat opens, select a model that is suitable for the Linux computer and make it available in the application. The project's basic workflow is to download Atomic Chat, pick a model, and start chatting. Its local model support includes model families such as Llama, Gemma, Qwen, Mistral, and Phi, among others, but model availability may change and individual models can have different licenses or hardware needs.

Atomic Chat exposes multiple inference engines through the same API base URL. Client applications do not need to know which backend is active underneath the service. This separation is useful operationally because the model or engine can be changed in Atomic Chat without necessarily changing the client's API URL.

For this guide, leave the service on its default 127.0.0.1 binding. Changing the host to 0.0.0.0 makes it reachable through the machine's network interfaces and is intended for LAN exposure. That broader binding adds another network path and is unnecessary when Localtonet runs beside Atomic Chat on the same computer.

Verify the OpenAI-compatible API locally

Local verification is the most important diagnostic checkpoint in the workflow. If a request to 127.0.0.1:1337 fails on the Atomic Chat computer, a public tunnel will not repair the application, model, or local listener. Verify the service before installing or configuring remote access.

With Atomic Chat running and a model loaded, send the documented chat completion request. Replace the model placeholder with the identifier of the model currently loaded in Atomic Chat:

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 response should be JSON in the OpenAI-compatible chat completion format. The exact generated text and timing depend on the loaded model and hardware. The relevant verification is that the server accepts the request, recognizes the model, performs inference, and returns a structured response instead of a connection or model error.

Verify with the OpenAI Python client

Atomic Chat's documented Python example uses the OpenAI client with a changed base_url. It supplies not-needed as the API key value because the example states that a real API key is not required by the local server.

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 example assumes that Python and a compatible OpenAI Python package are already installed. Those are client-side requirements, not requirements for the AppImage itself. The curl test is usually the smallest verification path because it avoids a language package and application configuration.

Interpret common local outcomes

Connect Atomic Chat through a Localtonet HTTP tunnel

Configure remote access only after the local curl test succeeds. Install and run the Localtonet client on the same Linux computer as Atomic Chat. That placement allows our client to reach the loopback-only service without changing Atomic Chat's listener to 0.0.0.0.

An HTTP tunnel is appropriate because Atomic Chat exposes an HTTP API. The local target is 127.0.0.1 on port 1337. HTTP and File Server tunnels support Random Sub Domain, Custom Sub Domain, or Custom Domain process types, and each serves the configured content at a public HTTPS address. Availability of individual options can vary, so use only the choices currently presented for your account.

The complete public API base URL is the assigned HTTPS origin followed by /v1. If the assigned origin is represented as https://your-assigned-host.example, the conceptual client configuration is:

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

That hostname is an illustration, not an actual Localtonet endpoint. Always copy the real public URL assigned to your running tunnel. A chat completion request appends /chat/completions to the /v1 base:

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 the illustrative origin and model placeholder before running the request. Never place a private Localtonet device token in the URL, JSON body, application repository, or client configuration.

Configure an OpenAI-compatible remote client

Most compatible clients separate the API base URL from the model name. Set the base URL to the real Localtonet HTTPS origin plus /v1. Set the model field to the identifier of the model loaded in Atomic Chat. If the client requires a nonempty API-key field even though the upstream Atomic Chat service does not validate one, a placeholder may satisfy that client's local configuration requirement, but it does not create authentication.

from openai import OpenAI

client = OpenAI(
    base_url="https://your-assigned-host.example/v1",
    api_key="not-needed",
)

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

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

Secure remote access to the inference API

Local-only AI and public remote access have different trust boundaries. Atomic Chat's privacy benefits apply when inference, model data, and conversations remain on the local machine. Once a public endpoint is enabled, prompts and generated responses intentionally travel between remote clients and the local service. The deployment must therefore protect the public URL, client devices, application data, and model capacity.

A Localtonet HTTP tunnel provides a public HTTPS address and removes the need for inbound router port forwarding. It does not automatically add API-key authentication to an upstream application that does not require a key. Do not equate transport through an HTTPS endpoint with authorization to use the underlying inference service.

Recommended exposure pattern

For an individual temporary test, keep Atomic Chat and Localtonet on the same trusted Linux machine, retain the loopback binding, share the public URL only with the intended tester, monitor the test, and stop the tunnel immediately afterward. This minimizes the period in which the API is reachable.

For recurring access or multiple users, direct forwarding to the unauthenticated Atomic Chat API is not an appropriate final design. Add a local gateway that authenticates callers and enforces the controls required by your environment. The exact gateway configuration depends on the chosen software and organizational policy, so this article does not invent a universal command or claim a specific authentication mechanism is built into Atomic Chat.

Operate the service reliably

Four runtime components must remain healthy: the Atomic Chat desktop process, the loaded model and inference backend, the Localtonet client, and the HTTP tunnel. A failure in any one of these layers interrupts remote requests.

Start services in a testable order

Start Atomic Chat first, load the intended model, and repeat the local curl request. Then start the Localtonet client and tunnel. Finally, test through the public HTTPS URL. This order makes failures easier to isolate because every layer is verified before the next one is added.

Stop exposure without deleting the local setup

Stopping the Localtonet tunnel removes the public path while allowing Atomic Chat to continue serving local clients. This is useful when the local application should remain open but remote access is needed only during scheduled periods. Deleting the tunnel is appropriate when the public configuration will not be reused.

Change models carefully

A client request names a model. If the active model changes, remote clients may also need an updated model identifier. Verify the new model locally before resuming the public tunnel. Clients can continue using the same /v1 base URL while Atomic Chat changes the underlying inference engine, but the model field must still match a model recognized by the running service.

Account for inference latency

Local inference can take longer than a typical cloud API request, particularly while a model is loading or when the host is resource constrained. A client with an aggressive request timeout may fail even though Atomic Chat eventually produces a result. Adjust client-side timeout behavior based on measured local response times, but do not assign an arbitrary universal value because performance depends on the machine and model.

Preserve a local health check

Keep the local curl request available as a health check. If remote calls fail, run it directly on the Atomic Chat machine. A successful local request points toward the Localtonet client, tunnel state, public URL, or remote client configuration. A failed local request points toward Atomic Chat, the loaded model, or the local port.

Troubleshoot installation, API, and tunnel failures

Check the target from the Localtonet machine

If Localtonet and Atomic Chat run on the same Linux computer, rerun the local curl test there. Do not test 127.0.0.1:1337 from another computer and expect it to reach the Atomic Chat host. Every machine has its own loopback interface.

Check the base URL for duplicate paths

Some client settings expect an API base such as https://assigned-host/v1, while the client library automatically appends /chat/completions. If a user enters the complete chat completion path into a base URL field, the client may append another route and produce an invalid URL. Inspect the final requested path when possible.

Separate authorization errors from inference errors

If you add an authenticated gateway, test it as a distinct layer. An authorization rejection means the gateway received the request but did not accept the credentials or policy. A model error means the request progressed far enough to reach an application layer that evaluated the model field. Keeping these layers conceptually separate makes troubleshooting faster.

When to build Atomic Chat from source instead

Most readers should use the released AppImage. A source build is more appropriate for contributors, developers testing unreleased changes, or users who need to inspect and modify the desktop application. The documented source prerequisites are Node.js 20 or newer, Yarn 4.5.3 or newer, Make, and Rust. The project provides a make dev workflow.

Do not mix AppImage troubleshooting with source-build troubleshooting. The AppImage is a released application package, while the development workflow introduces JavaScript dependencies, Rust tooling, compiler requirements, repository state, and development services. Those additional layers create failure modes that do not exist in the normal AppImage setup.

The supplied evidence confirms the prerequisite versions and make dev workflow but does not provide enough verified detail here to reproduce every repository checkout, dependency installation, system package, or build artifact step safely. For that reason, this tutorial does not invent a complete source-build command sequence. The AppImage remains the documented installation path covered end to end.

Frequently asked questions