Start Using Quilltap

Get set up in minutes and start interacting with AI.

Running with Docker

Quilltap runs as a single Docker container with no external database. Just Docker and one secret value you'll generate yourself.

What You'll Need

Docker Desktop (Windows, macOS, or Linux). That's it.

Your platform:

Setup (5 minutes)

1

Create a Data Folder

Quilltap stores everything — your database, uploaded files, the pictures you'll generate, and logs — in a single folder on your machine.

PowerShell
mkdir "$env:USERPROFILE\.quilltap"
Terminal
mkdir -p ~/Library/Application\ Support/Quilltap
Terminal
mkdir -p ~/.quilltap
2

Generate Your Encryption Key

Quilltap encrypts your AI provider API keys at rest using a master key called ENCRYPTION_MASTER_PEPPER. You generate this once and keep it safe — if you lose it, any API keys you've saved become unrecoverable.

PowerShell
-join ((1..43) | ForEach-Object { [char](Get-Random -Minimum 33 -Maximum 126) })
Terminal
openssl rand -base64 32
Terminal
openssl rand -base64 32

Copy the output — you'll need it in the next step.

3

Save Your Key

Create a file called .env in your data folder with one line: 

ENCRYPTION_MASTER_PEPPER=paste-your-generated-key-here

Replace paste-your-generated-key-here with the value from Step 2. This is the file:

  • Windows: %USERPROFILE%\.quilltap\.env
  • macOS: ~/Library/Application Support/Quilltap/.env
  • Linux: ~/.quilltap/.env

Back this file up. The encryption pepper is the one value you can't regenerate. Treat it like a password.

4

Start Quilltap

PowerShell
docker run -d `
  --name quilltap `
  -p 3000:3000 `
  --env-file "$env:USERPROFILE\.quilltap\.env" `
  -v "$env:USERPROFILE\.quilltap:/app/quilltap" `
  csebold/quilltap:latest
Terminal
docker run -d \
  --name quilltap \
  -p 3000:3000 \
  --env-file ~/Library/Application\ Support/Quilltap/.env \
  -v ~/Library/Application\ Support/Quilltap:/app/quilltap \
  csebold/quilltap:latest
Terminal
docker run -d \
  --name quilltap \
  -p 3000:3000 \
  --env-file ~/.quilltap/.env \
  -v ~/.quilltap:/app/quilltap \
  csebold/quilltap:latest
5

Open Quilltap

Go to http://localhost:3000. You're in.

What's in Your Data Folder

Everything Quilltap needs lives in that one directory you created:

Path Contents
data/quilltap.db Your SQLite database (characters, chats, settings)
files/ Uploaded images and attachments
logs/ Application logs
plugins/ Installed plugins

Your data stays on your machine. Quilltap never phones home.

Updating

docker stop quilltap
docker rm quilltap
docker pull csebold/quilltap:latest

Then re-run the same docker run command from Step 4. Your data folder is untouched — nothing is lost.

Quick Reference

Task Command
Stop Quilltap docker stop quilltap
Start it again docker start quilltap
View logs docker logs quilltap
Follow logs live docker logs -f quilltap

Next Steps

Once Quilltap is running:

  1. 1.

    Add an AI provider — Go to Settings and create a connection profile for your preferred provider (OpenAI, Anthropic, Google Gemini, Ollama, OpenRouter, and more). You'll need an API key from that provider.

  2. 2.

    Create or import a character — Build one from scratch or import a SillyTavern-compatible JSON file.

  3. 3.

    Start chatting — Pick a character, choose your AI provider, and go.

Troubleshooting

"Port 3000 is already in use"

Change the host port: replace -p 3000:3000 with -p 8080:3000, then open http://localhost:8080.

Container exits immediately

Check the logs with docker logs quilltap. The most common cause is a missing ENCRYPTION_MASTER_PEPPER.

Permission errors on the data folder (Linux)

On Docker Desktop (Windows/macOS), permissions are handled automatically. On native Linux, the container runs as a non-root user that may not match your host UID. If you see permission errors, make the data folder writable before the first run: 

chmod -R 777 ~/.quilltap

Or, if you prefer tighter permissions, match the container's user to your own: 

docker run ... --user "$(id -u):$(id -g)" csebold/quilltap:latest