Configuring your server

Almost everything is configured in the Eggent interface, and a .env file is optional. Environment variables are for what must be known before start-up: the address, the port, fallback keys.

#Environment variables

The full list is in .env.example in the repository. The main ones:

After changing .env, recreate the container:

docker compose up -d --force-recreate

#Reverse proxy and HTTPS

On a VPS, keep Eggent on 127.0.0.1 and put a proxy with HTTPS in front of it. HTTPS is not only about security: without it the browser will not allow the microphone, and Telegram will not accept a webhook.

Caddy (gets the certificate by itself):

eggent.example.com {
    request_body {
        max_size 100MB
    }
    reverse_proxy 127.0.0.1:3000
}

Nginx:

server {
    server_name eggent.example.com;
    client_max_body_size 100m;

    location / {
        proxy_pass http://127.0.0.1:3000;
        proxy_http_version 1.1;
        proxy_set_header Host $host;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
        proxy_buffering off;
        proxy_read_timeout 600s;
    }
}

Once the proxy is set up, put the public address into APP_BASE_URL.

#Telegram on your own server

Connect the bot in Settings → Messengers, as described in Telegram. Modes:

• Long Polling — works without a public address. Good for a home machine. Messages are handled one after another, so something you send while the agent is busy — including /reset or "stop" — is read when that turn ends; a turn that has gone quiet is ended by the limits under EGGENT_TURN_SILENCE_* above.
• Webhook — needs a public HTTPS address (APP_BASE_URL). Faster and more reliable on a VPS.

Auto picks the webhook once a public HTTPS address is set.

#Egress proxy

If the server reaches the internet only through a proxy, set HTTPS_PROXY (and HTTP_PROXY, NO_PROXY if needed). Needs Node.js 22.23 or newer; the Docker image already has it.

#Security

• Do not expose Eggent's port to the internet without HTTPS. By default it listens only on 127.0.0.1 — keep it that way behind a proxy.
• Change the default login and password straight away.
• Treat the external API token like a password and never use it in browser code.
• Protect and back up the data/ folder: it holds chats, files, memory, settings and keys.
• The agent has a terminal inside the container. Do not mount folders into the container that the agent does not need.