​
Prerequisites

Before deploying Atoma Proxy, ensure you have:
  • Docker and Docker Compose installed
  • Sui wallet configured (see Sui installation guide)
  • Hugging Face API token (for accessing gated models)

​
Clone the repository:

git clone https://github.com/atoma-network/atoma-proxy.git
cd atoma-proxy

​
Configure .env :

  1. Create a .env from the .env.example file:
cp .env.example .env
  1. Fill in the values for the environment variables. You need to at least set the following mandatory variables:
  • POSTGRES_DB
  • POSTGRES_USER
  • POSTGRES_PASSWORD
  • ATOMA_PROXY_SERVICE_PORT (default: 8081)
  • ATOMA_API_SERVICE_PORT (default: 8080)

​
Configure config.toml:

  1. Create a config.toml from the config.example.toml file:
cp config.example.toml config.toml
  1. Fill in the values for the configuration variables. You need to at least set the following mandatory variables:
  • database_url: The URL of the PostgreSQL database. Use the values from the .env file.
  • models: The list of models to be supported by the proxy.

​
Start the containers:

# Build and start all services, with local profile
docker compose --profile local up --build

# Or run in detached mode, with local profile
docker compose --profile local up -d --build
  • Check service status:
docker compose ps
  • Test the health endpoint:
curl http://localhost:8080/health
  • View available models:
curl http://localhost:8080/v1/models

​
API Documentation

See the API Reference for more details.

​
Interact with your own Atoma Proxy Instance

Once you have deployed your Atoma Proxy instance locally, you can interact with it by using the same API endpoints as the ones described in the API Reference. For example, for a chat completion request, you can use the following command (assuming that you have set the ATOMA_API_SERVICE_PORT to 8080, otherwise replace the port below accordingly): 
curl -X POST http://localhost:8080/v1/chat/completions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <YOUR_API_KEY>" \
  -d '{
    "model": <SUPPORTED_MODEL>,
    "messages": [
      {
        "role": "system",
        "content": "You are a helpful assistant."
      },
      {
        "role": "user",
        "content": "What is the capital of France?"
      }
    ],
    "temperature": 0.7
  }'
In order to generate an API key locally, you should follow a registration process, described in here.