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

​
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 <[email protected]>Overrides the default transactional sender.

​
AI Features

VariableDefaultNotes
OPENROUTER_API_KEYunsetEnables AI-generated summaries.

​
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