Docker Setup - Skyvern

This guide walks you through deploying Skyvern using Docker Compose. By the end, you’ll have a working Skyvern instance with the API server, browser, database, and web UI running on your machine.

Prerequisites

Docker and Docker Compose v2 installed (Get Docker). All commands use docker compose (with a space). If you have an older installation, replace with docker-compose.
4GB+ RAM available
An LLM API key (OpenAI, Anthropic, Azure, Gemini, or Bedrock)

Quick start

1. Clone the repository

git clone https://github.com/Skyvern-AI/skyvern.git
cd skyvern

2. Configure environment variables

Copy the example environment file and configure your LLM provider:

cp .env.example .env

Open .env and set your LLM provider. Here’s an example for OpenAI:

.env

ENABLE_OPENAI=true
OPENAI_API_KEY=sk-your-api-key-here
LLM_KEY=OPENAI_GPT5_5

For other providers, see LLM Configuration.

3. Configure the frontend

Copy the frontend environment file:

cp skyvern-frontend/.env.example skyvern-frontend/.env

The default values work for local development. Docker Compose mounts the generated local credentials into the UI container, so you can leave VITE_SKYVERN_API_KEY as YOUR_API_KEY for the first startup.

4. Start the services

docker compose up -d

This pulls the images and starts three services:

postgres: Database on port 5432 (internal only)
skyvern: API server on port 8000
skyvern-ui: Web interface on port 8080

First startup takes 1-2 minutes as it runs database migrations and creates your organization.

5. Get your API key

Wait for all services to be healthy before continuing:

docker compose ps

All three services should show healthy in the STATUS column. The skyvern container runs database migrations and generates credentials on first startup. This takes 1-2 minutes. Once healthy, retrieve your API key:

cat .skyvern/credentials.toml

This file is auto-generated by Skyvern on first startup. The credentials inside are standard Skyvern API keys. You’ll see output like:

[skyvern]
configs = [
    {env = "local", host = "http://skyvern:8000/api/v1", orgs = [{name="Skyvern", cred="eyJhbGciOiJIUzI1..."}]}
]

The host value uses the Docker-internal hostname skyvern. From your machine, use http://localhost:8000 instead. You only need the cred value. This is your API key.

6. Verify the installation

Open http://localhost:8080 in your browser. You should see the Skyvern dashboard. Test the API by listing workflows (should return an empty array on fresh install):

curl -s http://localhost:8000/v1/workflows \
  -H "x-api-key: YOUR_API_KEY_HERE"

The API accepts requests on both /v1/ and /api/v1/. The frontend uses /api/v1 for backward compatibility. New integrations should use /v1/.

Understanding the services

The Docker Compose file defines three services that work together:

Service	Image	Ports	Purpose
`postgres`	postgres:14-alpine	5432 (internal)	Stores tasks, workflows, credentials, and run history
`skyvern`	public.ecr.aws/skyvern/skyvern	8000, 9222	API server + embedded browser
`skyvern-ui`	public.ecr.aws/skyvern/skyvern-ui	8080, 9090	Web dashboard and artifact server

The skyvern container includes Playwright with Chromium. The browser runs inside the same container as the API server. No separate browser service is needed.

Data volumes

Docker Compose mounts several directories for persistent storage:

Local path	Container path	Contents
`./postgres-data`	`/var/lib/postgresql/data`	Database files
`./artifacts`	`/data/artifacts`	Extracted data, screenshots
`./videos`	`/data/videos`	Browser session recordings
`./har`	`/data/har`	HTTP Archive files for debugging
`./log`	`/data/log`	Application logs
`./.skyvern`	`/app/.skyvern`	Generated API credentials

Environment variables reference

The .env file controls the Skyvern server. Here are the most important variables grouped by purpose.

Environment files

docker-compose.yml uses TWO sources for service environment:

Inline environment: block — compose-network values that depend on the docker network topology. Examples: DATABASE_STRING=postgresql+psycopg://skyvern:skyvern@postgres:5432/skyvern (the postgres hostname only resolves inside the compose network), BROWSER_TYPE, BROWSER_STREAMING_MODE, ENABLE_CODE_BLOCK.
env_file: .env — user secrets (LLM API keys, etc.).

Do not move DATABASE_STRING from compose into .env. The .env.example shipped with the repo uses a localhost host that points at the backend container itself when used inside compose — moving that value into .env will break the database connection. If you have an existing .env from a pre-1.0.32 skyvern quickstart run, it may contain a leftover DATABASE_STRING=postgresql+psycopg://skyvern@localhost/skyvern line. Remove it:

sed -i.bak '/^DATABASE_STRING.*localhost/d' .env

LLM Configuration

Configure at least one LLM provider. See LLM Configuration for all providers.

# OpenAI
ENABLE_OPENAI=true
OPENAI_API_KEY=sk-...
LLM_KEY=OPENAI_GPT5_5

# Or Anthropic
ENABLE_ANTHROPIC=true
ANTHROPIC_API_KEY=sk-ant-...
LLM_KEY=ANTHROPIC_CLAUDE4.7_OPUS

Browser settings

# Browser mode: chromium-headful (visible) or chromium-headless (no display)
BROWSER_TYPE=chromium-headful

# Browser livestreaming mode: cdp (default local screencast) or vnc
BROWSER_STREAMING_MODE=cdp

# Timeout for individual browser actions (milliseconds)
BROWSER_ACTION_TIMEOUT_MS=5000

# Where to save recordings
VIDEO_PATH=./videos

Task execution

# Maximum steps before a task times out
MAX_STEPS_PER_RUN=10

# Server port
PORT=8000

# Log verbosity: DEBUG, INFO, WARNING, ERROR
LOG_LEVEL=INFO

Database

The database connection is set in docker-compose.yml, not .env:

environment:
  - DATABASE_STRING=postgresql+psycopg://skyvern:skyvern@postgres:5432/skyvern

To use an external database, update this connection string and remove the postgres service.

Common operations

View logs

# All services
docker compose logs -f

# Specific service
docker compose logs -f skyvern

Restart after configuration changes

docker compose restart skyvern

Stop all services

docker compose down

Update to latest version

docker compose pull
docker compose up -d

Reset everything (including database)

This deletes all data including task history, credentials, and recordings.

docker compose down -v
rm -rf postgres-data artifacts videos har log .skyvern
docker compose up -d

Exposing to the network

By default, Skyvern only accepts connections from localhost. To expose it on your network:

Option 1: Bind to all interfaces

Edit docker-compose.yml to change the port bindings:

services:
  skyvern:
    ports:
      - "0.0.0.0:8000:8000"  # Accept connections from any IP

Option 2: Use a reverse proxy

For production deployments, put Skyvern behind nginx or Traefik:

your-domain.com → nginx → localhost:8080 (UI)
api.your-domain.com → nginx → localhost:8000 (API)

Update the frontend environment to use your domain:

skyvern-frontend/.env

VITE_API_BASE_URL=https://api.your-domain.com/api/v1
VITE_WSS_BASE_URL=wss://api.your-domain.com/api/v1
VITE_ARTIFACT_API_BASE_URL=https://artifacts.your-domain.com

If exposing Skyvern to the internet, add authentication at the reverse proxy layer or use a VPN.

Troubleshooting

Container exits immediately

Check the logs for the failing service:

docker compose logs skyvern

Common causes:

Missing or invalid LLM API key: look for LLM-related errors in logs
Database connection failed: check if postgres service is healthy with docker compose ps

API returns "Invalid credentials" (403)

The API key is missing, malformed, or doesn’t match the organization. Verify:

The x-api-key header is included in your request
The key matches exactly what’s in .skyvern/credentials.toml
No extra whitespace or newlines in the key

# Correct format
curl -H "x-api-key: eyJhbGciOiJIUzI1..." http://localhost:8000/v1/workflows

API returns "Could not validate credentials" (403)

The API key format is invalid (JWT decode failed). This usually means:

The key was truncated or corrupted during copy-paste
You’re using an API key from a different Skyvern installation

Regenerate credentials by resetting the installation:

rm -rf .skyvern
docker compose restart skyvern
cat .skyvern/credentials.toml  # Get new key

UI shows blank page or connection errors

Check that skyvern-frontend/.env has the correct values:

VITE_API_BASE_URL=http://localhost:8000/api/v1
VITE_WSS_BASE_URL=ws://localhost:8000/api/v1
VITE_SKYVERN_API_KEY=<your-key-from-credentials.toml>

After updating, restart the UI:

docker compose restart skyvern-ui

Task fails with "Unknown browser type"

The BROWSER_TYPE environment variable has an invalid value. Valid options:

chromium-headful: Browser with visible window (default)
chromium-headless: No visible window
cdp-connect: Connect to external Chrome

Task fails with "Context window exceeded"

The page content is too large for the LLM. Try:

Simplifying your prompt
Starting from a more specific URL
Using a model with a larger context window

Next steps

LLM Configuration

Configure OpenAI, Anthropic, Azure, Ollama, and other providers

Browser Configuration

Customize browser settings, locales, and connect to external Chrome

Storage Configuration

Store artifacts in S3 or Azure Blob instead of local disk

Proxy Setup

Configure proxies to avoid bot detection

​Prerequisites

​Quick start

​1. Clone the repository

​2. Configure environment variables

​3. Configure the frontend

​4. Start the services

​5. Get your API key

​6. Verify the installation

​Understanding the services

​Data volumes

​Environment variables reference

​Environment files

​LLM Configuration

​Browser settings

​Task execution

​Database

​Common operations

​View logs

​Restart after configuration changes

​Stop all services

​Update to latest version

​Reset everything (including database)

​Exposing to the network

​Option 1: Bind to all interfaces

​Option 2: Use a reverse proxy

​Troubleshooting

​Next steps

LLM Configuration

Browser Configuration

Storage Configuration

Proxy Setup

Prerequisites

Quick start

1. Clone the repository

2. Configure environment variables

3. Configure the frontend

4. Start the services

5. Get your API key

6. Verify the installation

Understanding the services

Data volumes

Environment variables reference

Environment files

LLM Configuration

Browser settings

Task execution

Database

Common operations

View logs

Restart after configuration changes

Stop all services

Update to latest version

Reset everything (including database)

Exposing to the network

Option 1: Bind to all interfaces

Option 2: Use a reverse proxy

Troubleshooting

Next steps