Akash Chat

Akash Chat is an open source chat application built with Next.js. It talks to any OpenAI-compatible inference API, so you can point it at AkashML by setting two environment variables: API_KEY and API_ENDPOINT. This guide covers running it locally for development and deploying it on the Akash Network.

Prerequisites

An AkashML account and an API key. Create one under Settings → API Keys.
Node.js v18 or higher and pnpm (for local development).
Git.

Run locally

Step 1 — Clone the repository

git clone https://github.com/akash-network/akash-chat.git
cd akash-chat

Step 2 — Install dependencies

pnpm install

Step 3 — Configure AkashML

Create a .env.local file in the project root. At minimum, set your API key and point the endpoint at AkashML:

.env.local

API_KEY=akml-...
API_ENDPOINT=https://api.akashml.com/v1
DEFAULT_MODEL=zai-org/GLM-5.2

Replace akml-... with your real API key. Set DEFAULT_MODEL to any model ID from the AkashML catalog — Akash Chat fetches the rest of the available models from the endpoint at runtime.

Step 4 — Start the development server

pnpm dev

Open http://localhost:3000 and send a message to confirm the connection. Requests count against your AkashML credit balance and show up in the Dashboard usage chart.

Environment variables

Only API_KEY is required. The rest enable optional features such as caching, a password lock, and voice transcription.

Variable	Required	Value
`API_KEY`	yes	Your AkashML API key (`akml-...`)
`API_ENDPOINT`	no	AkashML base URL — `https://api.akashml.com/v1`
`DEFAULT_MODEL`	no	Default model ID, e.g. `zai-org/GLM-5.2`
`ACCESS_TOKEN`	no	Password that locks the instance (see below)
`WS_TRANSCRIPTION_URLS`	no	WebSocket URLs for voice transcription
`WS_TRANSCRIPTION_MODEL`	no	Model used for voice transcription

A minimal setup needs only API_KEY and API_ENDPOINT. See .env.example in the repo for the full list of optional variables.

Lock your instance with a password

Because Akash Chat sends requests with your AkashML key, you usually don't want a public instance open to anyone. Set ACCESS_TOKEN to require a password before the app can be used:

.env.local

ACCESS_TOKEN=choose-a-strong-password

When ACCESS_TOKEN is set, the app prompts every visitor for the token on first load and rejects API requests that don't include it. A hash of the token is stored in the visitor's browser so they aren't asked again. This is a single shared password for the whole instance — share it with the people who should have access.

Note: Setting ACCESS_TOKEN also disables Akash Chat's built-in per-user rate limiting, since the deployment is treated as trusted. Your AkashML API key limits (configured under Settings → API Keys) still apply.

Deploy on the Akash Network

Akash Chat ships a prebuilt container image and an Akash SDL (deploy.yml). You can deploy it on the Akash Network in a few minutes using the Akash Console or the akash CLI.

Step 1 — Prepare the SDL

Use the SDL below, replacing API_KEY with your AkashML key and ACCESS_TOKEN with a password to lock the instance (drop that line to leave it open).

deploy.yml

---
version: "2.0"
services:
  akashchat:
    image: ghcr.io/akash-network/akash-chat:latest
    expose:
      - port: 3000
        as: 80
        to:
          - global: true
    env:
      - API_KEY=akml-...
      - API_ENDPOINT=https://api.akashml.com/v1
      - DEFAULT_MODEL=zai-org/GLM-5.2
      - ACCESS_TOKEN=choose-a-strong-password
profiles:
  compute:
    akashchat:
      resources:
        cpu:
          units: 2
        memory:
          size: 4Gi
        storage:
          - size: 2Gi
  placement:
    akash:
      pricing:
        akashchat:
          denom: uact
          amount: 10000
deployment:
  akashchat:
    akash:
      profile: akashchat
      count: 1

Step 2 — Deploy

Open the Akash Console and connect a funded wallet.
Create a new deployment and paste the SDL from above (or upload your deploy.yml).
Review the bids from providers and accept one.
Once the lease is active, open the provider URI shown in the console to access your Akash Chat instance.

To deploy a custom version, build your own image from the repository's Dockerfile and replace the image field with your registry path.

Chat history and persistence

Akash Chat stores all chat history in your browser's local storage — there's no server-side database in this setup. Local storage is scoped to the site's domain, which matters on Akash: each lease is served from a provider-assigned URL, so if the deployment goes down, gets redeployed, or moves to a different provider, that URL can change. Because history is tied to the domain, visitors lose access to their existing conversations when it does.

Two ways to avoid losing context:

Export / Import — Use the Export action in the chat sidebar to download a chat-export-<date>.json file (chats, folders, and saved system prompts), then Import it on the new instance to restore everything. Encourage users to export regularly.
Custom domain — Point a stable custom domain at your deployment so the origin stays the same across redeploys. Local storage then persists and no context is lost. This is the better option for an instance you intend to keep running.