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

Variable	Default	Notes
`BETTER_AUTH_SECRET`	unset	Required. Generate with `openssl rand -base64 32`. Used to sign auth state and sessions.
`WEB_URL`	`http://localhost:3000`	Public base URL of your app. Used for OAuth callbacks, auth origins, and browser redirects. Set this to your real public hostname in production.
`WAITLIST_ENABLED`	`true`	When 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

Variable	Default	Notes
`GITHUB_CLIENT_ID`	unset	Required if GitHub login is enabled. GitHub OAuth app client ID.
`GITHUB_CLIENT_SECRET`	unset	Required if GitHub login is enabled. GitHub OAuth app client secret.

GitLab

Variable	Default	Notes
`GITLAB_CLIENT_ID`	unset	Required if GitLab login is enabled. GitLab OAuth/OIDC app client ID.
`GITLAB_CLIENT_SECRET`	unset	Required if GitLab login is enabled. GitLab OAuth/OIDC app client secret.
`GITLAB_ISSUER`	`https://gitlab.com`	Set this to your self-managed GitLab instance URL when not using gitlab.com.

Storage

Variable	Default	Notes
`DB_LOCAL_PATH`	`.data/db.sqlite`	SQLite database path.
`STORAGE_DIR`	`.data/storage`	Local blob storage directory for uploaded transcript assets.

Email

Variable	Default	Notes
`RESEND_API_KEY`	unset	Enables transactional email delivery.
`EMAIL_SENDER`	`Philipp 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.

Variable	Default	Notes
`OPENROUTER_API_KEY`	unset	Enables AI-generated summaries through OpenRouter when no custom AI endpoint is configured.
`AI_BASE_URL`	unset	Base URL for an OpenAI-compatible API. Typical values end in `/v1`.
`AI_MODEL`	unset	Required with `AI_BASE_URL`. Model identifier sent to the compatible endpoint.
`AI_API_KEY`	unset	Optional 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

Variable	Default	Notes
`HOST`	`0.0.0.0`	HTTP bind host for the standalone server runtime.
`PORT`	`3000`	HTTP 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

Introduction

Agents

CLI

Server

Hosting

Hosting AgentLogs

Deploy

Docker

Standalone Binary

Environment Variables

Authentication

OAuth Providers

GitHub

GitLab

Storage

Email

AI Features

OpenAI-compatible endpoints

OpenRouter

Runtime

Configure Authentication Providers

GitHub OAuth App

GitLab OAuth / OIDC App

Connect Your CLI And Plugins

Upgrade

​Hosting AgentLogs

​Deploy

​Docker

​Standalone Binary

​Environment Variables

​Authentication

​OAuth Providers

​GitHub

​GitLab

​Storage

​Email

​AI Features

​OpenAI-compatible endpoints

​OpenRouter

​Runtime

​Configure Authentication Providers

​GitHub OAuth App

​GitLab OAuth / OIDC App

​Connect Your CLI And Plugins

​Upgrade

Hosting AgentLogs

Deploy

Docker

Standalone Binary

Environment Variables

Authentication

OAuth Providers

GitHub

GitLab

Storage

Email

AI Features

OpenAI-compatible endpoints

OpenRouter

Runtime

Configure Authentication Providers

GitHub OAuth App

GitLab OAuth / OIDC App

Connect Your CLI And Plugins

Upgrade