What You Need Before Starting
Getting Genten running on your machine is straightforward. Here's what you need.
If you don't have Docker Desktop yet, that's fine. We'll walk you through installing it in the next section.
Install Docker Desktop
Docker Desktop is a free application that lets you run containers on your computer. If you already have it installed, skip to Section 3.
docker --version
You should see something like:
Docker version 24.0.7, build afdd53b
Pull the Genten Image
Download Genten from GitHub to your computer. This takes 1-2 minutes.
docker pull ghcr.io/hekateknyc/genten:latest
When the download finishes, you'll see a message like:
Status: Downloaded newer image for ghcr.io/hekateknyc/genten:latest
Set Up Your Configuration File
Genten needs a configuration file to know where to store data and how to run. Don't worry, we'll walk through each setting.
.env inside that folder
.env file:
# =================================================================== # PRODUCTION-REQUIRED CONFIGURATION # These variables MUST be set in production environments # =================================================================== NODE_ENV=production VITE_API_URL=http://localhost:3001 DATABASE_URL=./data/agent-dashboard.sqlite AGENT_GATEWAY_URL=http://127.0.0.1:18789 DEV_MODE=false CLIENT_URL=http://localhost:5173 # =================================================================== # OPTIONAL CONFIGURATION # These variables have defaults and can be customized as needed # =================================================================== PORT=3001 LOG_LEVEL=info OPENCLAW_TOKEN= OPENCLAW_BIN_PATH= BRIEFING_HOUR=8 # =================================================================== # EMAIL CONFIGURATION (Optional) # Required only if email notifications/briefings are enabled. # Genten sends all system emails from gentendashboard@gmail.com. # Users enter their own email in the Settings page to receive briefings. # =================================================================== GMAIL_APP_PASSWORD= FEEDBACK_RELAY_URL=https://your-apps-script-relay-url-here FEEDBACK_RELAY_SECRET=
Here's what each required setting means. You don't need to change any of these unless you're doing something advanced.
NODE_ENV=production
Tells Genten to run in production mode. Leave this as-is.
VITE_API_URL=http://localhost:3001
The web address where Genten will run. Use
localhost:3001 unless you're hosting this on a
server.
DATABASE_URL=./data/agent-dashboard.sqlite
Where Genten stores all your data. This will create a folder called "data" inside your genten folder. Leave as-is.
DEV_MODE=false
Disables developer tools. Leave this as false for
normal use.
CLIENT_URL=http://localhost:5173
Internal frontend URL. Leave as-is.
GMAIL_APP_PASSWORD after your first launch. We'll cover
that in the Settings page inside Genten.
Create the docker-compose.yml File
Docker Compose tells Docker how to run Genten. This file defines the image to use, which ports to expose, and where to store data.
docker-compose.yml in the same
folder as your .env file
docker-compose.yml:
services:
genten:
image: ghcr.io/hekateknyc/genten:latest
build: .
container_name: genten
restart: unless-stopped
ports:
- "3001:3001"
volumes:
- ./data:/app/data
env_file:
- .env
image: ghcr.io/hekateknyc/genten:latest
Use the Genten image you just downloaded.
ports: "3001:3001"
Make Genten available at http://localhost:3001 in
your browser.
volumes: - ./data:/app/data
This is the most important line. It maps the "data" folder on your computer to the container's storage. This means your data persists even when you stop and restart Genten. Without this line, you'd lose everything when you restart.
restart: unless-stopped
Automatically restart Genten if it crashes or if your computer restarts.
Start Genten
You're ready to launch. This is the moment everything comes together.
cd to change directories. For example:
cd ~/Desktop/genten
docker compose up
Watch for these messages in the logs:
[db] Ran 16 migration(s) [server] Server listening on port 3001 [server] Frontend URL: http://localhost:5173
http://localhost:3001
You should see the Genten dashboard load. The first time you visit, you'll see an empty dashboard with a "Connect an Agent" button. That's normal — you haven't connected any AI agents yet.
docker compose up -d instead (the -d means
"detached" mode).
Common Problems and Fixes
Most issues have quick fixes. Here are the ones we see most often.
Error message:
Error starting userland proxy: listen tcp4 0.0.0.0:3001: bind:
address already in use
What it means: Something else on your computer is already using port 3001.
docker-compose.yml3001 in the ports line to another
number
"3002:3001" — this makes Genten
available at localhost:3002 instead
Error message:
Cannot connect to the Docker daemon. Is the docker daemon
running?
What it means: Docker Desktop isn't running.
docker compose up command again
Error message:
permission denied while trying to connect to the Docker daemon
socket
What it means: Your user account doesn't have permission to use Docker.
sudo usermod -aG docker $USER
This is normal! You haven't connected any AI agents yet. Genten is working correctly — it's just empty.
Stopping and Restarting Genten
How to stop, restart, and update Genten without losing your data.
If you started Genten with docker compose up (not
detached mode):
Ctrl+C in the terminal where Genten is running
If you started Genten in detached mode with
docker compose up -d:
docker compose down
docker compose up
When HekaTek releases a new version of Genten:
Ctrl+C or docker compose down
docker compose pull
docker compose up
Genten will automatically run any new database migrations when it starts. Your data remains intact.
Where to Get Help
We're here to help you get Genten running smoothly.