Skip to main content

​
Hosting AgentLogs

AgentLogs server is available in two production-ready formats:
  • Official Docker image: ghcr.io/agentlogs/agentlogs
  • Official standalone binary: agentlogs-server for Linux, macOS, and Windows
Both run the same server runtime and support embedded migrations.
You must configure at least one OAuth provider. AgentLogs currently supports GitHub and GitLab login.

​
Deploy

​
Docker

Pull and run the official image: 
docker run -d \
  --name agentlogs \
  -p 3000:3000 \
  -v agentlogs-data:/app/.data \
  -e BETTER_AUTH_SECRET=... \
  -e WEB_URL=https://logs.example.com \
  -e GITHUB_CLIENT_ID=... \
  -e GITHUB_CLIENT_SECRET=... \
  ghcr.io/agentlogs/agentlogs:latest
Replace the GitHub variables with GitLab variables if you want GitLab-only login, or provide both sets if you want both providers enabled.
Mount /app/.data to persist both SQLite data and uploaded transcript blobs.

​
Standalone Binary

Download a matching binary from the GitHub Releases page (server-vX.Y.Z tags), then run: 
chmod +x ./agentlogs-server
./agentlogs-server
  • By default, the binary runs embedded migrations, then starts the server
  • --no-migrations skips startup migrations
  • --only-migrations runs migrations and exits

​
Environment Variables

Before you deploy, make sure you have:
  • BETTER_AUTH_SECRET
  • WEB_URL set to your public hostname in production
  • GitHub login: GITHUB_CLIENT_ID and GITHUB_CLIENT_SECRET, or GitLab login: GITLAB_CLIENT_ID and GITLAB_CLIENT_SECRET
  • GITLAB_ISSUER if you use self-managed GitLab
  • An AI summary backend if you want transcript titles generated automatically

​
Authentication

VariableDefaultNotes
BETTER_AUTH_SECRETunsetRequired. Generate with openssl rand -base64 32. Used to sign auth state and sessions.
WEB_URLhttp://localhost:3000Public base URL of your app. Used for OAuth callbacks, auth origins, and browser redirects. Set this to your real public hostname in production.
WAITLIST_ENABLEDtrueWhen enabled, new users default to the waitlist role. Set it to false to make new users regular users immediately.

​
OAuth Providers

At least one provider must be configured. If both GitHub and GitLab are configured, AgentLogs currently prefers GitHub for provider-agnostic login redirects such as browser login and device authorization.

​
GitHub

VariableDefaultNotes
GITHUB_CLIENT_IDunsetRequired if GitHub login is enabled. GitHub OAuth app client ID.
GITHUB_CLIENT_SECRETunsetRequired if GitHub login is enabled. GitHub OAuth app client secret.

​
GitLab

VariableDefaultNotes
GITLAB_CLIENT_IDunsetRequired if GitLab login is enabled. GitLab OAuth/OIDC app client ID.
GITLAB_CLIENT_SECRETunsetRequired if GitLab login is enabled. GitLab OAuth/OIDC app client secret.
GITLAB_ISSUERhttps://gitlab.comSet this to your self-managed GitLab instance URL when not using gitlab.com.

​
Storage

VariableDefaultNotes
DB_LOCAL_PATH.data/db.sqliteSQLite database path.
STORAGE_DIR.data/storageLocal blob storage directory for uploaded transcript assets.

​
Email

VariableDefaultNotes
RESEND_API_KEYunsetEnables transactional email delivery.
EMAIL_SENDERPhilipp from AgentLogs <philipp@agentlogs.ai>Overrides the default transactional sender.

​
AI Features

AgentLogs can generate short transcript titles during ingest. You can configure one of two backends:
  • AI_BASE_URL and AI_MODEL for any OpenAI-compatible endpoint such as Ollama, vLLM, or LiteLLM
  • OPENROUTER_API_KEY for the default hosted path through OpenRouter
If both AI_BASE_URL and AI_MODEL are set, AgentLogs prefers the OpenAI-compatible endpoint. If no AI backend is configured, summary generation falls back to a generic placeholder title.
VariableDefaultNotes
OPENROUTER_API_KEYunsetEnables AI-generated summaries through OpenRouter when no custom AI endpoint is configured.
AI_BASE_URLunsetBase URL for an OpenAI-compatible API. Typical values end in /v1.
AI_MODELunsetRequired with AI_BASE_URL. Model identifier sent to the compatible endpoint.
AI_API_KEYunsetOptional API key for the compatible endpoint. Leave blank for local providers that do not require auth.

​
OpenAI-compatible endpoints

Use these variables when you want AgentLogs to keep summary generation inside your own infrastructure: 
AI_BASE_URL=http://localhost:11434/v1
AI_MODEL=llama3.2
AI_API_KEY=
  • For Docker deployments that call an Ollama server running on the host, use http://host.docker.internal:11434/v1
  • For gateways like LiteLLM or vLLM, set AI_MODEL to the model name that gateway exposes

​
OpenRouter

Use OpenRouter when you want a hosted default without running your own model server: 
OPENROUTER_API_KEY=...

​
Runtime

VariableDefaultNotes
HOST0.0.0.0HTTP bind host for the standalone server runtime.
PORT3000HTTP port for the standalone server runtime.

​
Configure Authentication Providers

​
GitHub OAuth App

Create an OAuth app at github.com/settings/developers:
  • Homepage URL: ${WEB_URL}
  • Authorization callback URL: ${WEB_URL}/api/auth/callback/github
Example for production:
  • Homepage: https://logs.example.com
  • Callback: https://logs.example.com/api/auth/callback/github

​
GitLab OAuth / OIDC App

Create an OAuth application in your GitLab instance:
  • Redirect URI: ${WEB_URL}/api/auth/oauth2/callback/gitlab
  • Scopes: openid, profile, email
Example for production:
  • Issuer: https://gitlab.com
  • Redirect URI: https://logs.example.com/api/auth/oauth2/callback/gitlab
For self-managed GitLab, set GITLAB_ISSUER to your instance base URL, for example https://gitlab.company.internal.

​
Connect Your CLI And Plugins

Authenticate your CLI against your host: 
npx agentlogs login logs.example.com
Use your public hostname without https:// so your local CLI and plugins upload to your own instance.

​
Upgrade

When upgrading, deploy a newer image or binary and start it again:
  • Docker: restart the container with the new tag; embedded migrations run on startup by default
  • Binary: replace the binary and run ./agentlogs-server