Latest release v2026.1106.0 is live (November 6, 2026).

Integrations · Docker

Run Paperclip in Docker

Q: Is there an official Paperclip Docker image?

Yes. It is ghcr.io/paperclipai/paperclip, with the tags latest, beta, nightly and canary, for amd64 and arm64.

Q: Do I need my own PostgreSQL database?

No. The container uses an embedded database that it stores on the data volume. The repository also has a Compose file with a separate PostgreSQL service if you want one.

Q: How do I create the first admin account?

In the browser. Open the instance, create an account and choose Claim this instance. No terminal command is needed.

Q: Does my data survive a restart or an upgrade?

Yes, if you keep the data folder and the secrets file. In our test, a new container with the same folder kept the account and the organization.

Q: Can I use Docker Compose?

Yes. A Compose file that uses the same image, port, volume and secrets works. The repository also ships a Compose quickstart that builds from source.

Paperclip publishes a Docker image with the server, the web UI and the main agent CLIs. One command starts it, and your data stays in one folder.

Install Paperclip Read the docs

docker pull ghcr.io/paperclipai/paperclip:latest

terminal

$ node --version

v24.11.0

$ npx paperclipai onboard --yes

✓ Paperclip running at http://localhost:3100

→ Hire your first agent to get started

1 secretis required to start the container

Port 3100serves the web UI and the API

amd64 + arm64images are published for both

Setup

How do I run Paperclip in Docker?

Pull the image ghcr.io/paperclipai/paperclip, create one secret and start the container with a data folder mounted at /paperclip. Then open http://localhost:3100 and claim the instance in the browser. You don’t need to clone the repository.

The image includes the server, the web UI and an embedded database
The Claude Code, Codex, OpenCode and Gemini CLIs are already installed
Everything that must persist lives in one mounted folder

Docker deployment reference→

terminal

$ node --version

v24.11.0

$ npx paperclipai onboard --yes

✓ Paperclip running at http://localhost:3100

→ Hire your first agent to get started

Guide

Start Paperclip from the published image

You need Docker and about 10 GB of free disk space. We ran these steps on November 11, 2026.

Create the secrets file
Create the file once and keep it. Use the same file on every restart. BETTER_AUTH_SECRET is required, and the container exits without it.
Terminal
```
cat > paperclip.env <<EOF
BETTER_AUTH_SECRET=$(openssl rand -hex 32)
PAPERCLIP_TOOL_ACTION_SIGNING_SECRET=$(openssl rand -hex 32)
EOF
```

Start the container

The data folder paperclip-data is created next to the secrets file. The first start took about 10 seconds in our test.

Terminal

docker run -d --name paperclip \
  -p 3100:3100 \
  --env-file paperclip.env \
  -e PAPERCLIP_PUBLIC_URL=http://localhost:3100 \
  -v "$PWD/paperclip-data:/paperclip" \
  ghcr.io/paperclipai/paperclip:latest

Claim the instance
Open http://localhost:3100. Choose Sign in / Create account, then Create one, then Claim this instance. The first person to claim the instance becomes its admin, so do this before you share the address.
Connect an agent
Onboarding asks for an organization name, a first agent and a model connection. You can sign in to a Claude or ChatGPT subscription in the browser, or set an API key.
Upgrade later
Pull the new image, remove the container and run the same start command again. Your data stays in paperclip-data.
Terminal
```
docker pull ghcr.io/paperclipai/paperclip:latest
docker rm -f paperclip
```

Agents

Do agents run inside the container?

Yes, by default. Paperclip starts each agent’s CLI inside the same container, and the agent works in folders on the data volume. For stronger isolation, the experimental Environments feature runs agents in separate sandboxes.

Claude Code, Codex, OpenCode and Gemini CLI run in the container with no extra install
Hermes and OpenClaw are not in the image. They connect from where they already run
Sandbox providers include Daytona, E2B, Modal and Kubernetes. The docs mark Environments experimental

Environments in the docs→

Sandbox — network policy

Deny by defaultrun PAP-1042 · isolated workspace

egressapi.github.com · source + PRsallow

egressapi.anthropic.com · model providerallow

egressregistry.npmjs.org · package installallow

egress* everything else · no egressdeny

Reference

What do I need to set?

Settings for the Paperclip Docker container
Setting	Value	Notes
Image	`ghcr.io/paperclipai/paperclip:latest`	Other tags: `beta`, `nightly`, `canary`
Port	`3100`	Change the left side of `-p` to use another host port
Data volume	`/paperclip`	Database, uploads, the secrets key and agent workspaces
`BETTER_AUTH_SECRET`	Required	A random value. Keep it the same across restarts
`PAPERCLIP_PUBLIC_URL`	Recommended	The address people use to open Paperclip

Image

Value: ghcr.io/paperclipai/paperclip:latest
Notes: Other tags: beta, nightly, canary

Port

Value: 3100
Notes: Change the left side of -p to use another host port

Data volume

Value: /paperclip
Notes: Database, uploads, the secrets key and agent workspaces

`BETTER_AUTH_SECRET`

Value: Required
Notes: A random value. Keep it the same across restarts

`PAPERCLIP_PUBLIC_URL`

Value: Recommended
Notes: The address people use to open Paperclip

The image already sets the host, the home folder and authenticated mode. You don’t need to pass them.

Limits

What should I know before I start?

The image is large, because it carries the agent CLIs. The compressed download is about 3 GB on arm64 and about 5 GB on amd64. If you delete the data folder, the instance starts fresh.

A service on the host is at host.docker.internal from inside the container, not 127.0.0.1
For a team, put the container behind HTTPS or a private network and set the public URL to match
The -cloud image tags are not for self-hosting. Use the plain tags
Paperclip Cloud, the hosted version, is in an invitation-only beta

Open source and self-hosting→

Secret references

ANTHROPIC_API_KEY●●●●resolved at runtimeagent

GITHUB_TOKEN●●●●resolved at runtimeproject

DEPLOY_KEY●●●●resolved at runtimeuser · private

FAQ

Questions about Paperclip and Docker

Is there an official Paperclip Docker image?

Yes. It is ghcr.io/paperclipai/paperclip, with the tags latest, beta, nightly and canary, for amd64 and arm64.

Do I need my own PostgreSQL database?

No. The container uses an embedded database that it stores on the data volume. The repository also has a Compose file with a separate PostgreSQL service if you want one.

How do I create the first admin account?

In the browser. Open the instance, create an account and choose Claim this instance. No terminal command is needed.

Does my data survive a restart or an upgrade?

Yes, if you keep the data folder and the secrets file. In our test, a new container with the same folder kept the account and the organization.

Can I use Docker Compose?

Yes. A Compose file that uses the same image, port, volume and secrets works. The repository also ships a Compose quickstart that builds from source.

“One container holds the server, the database and the agents. One folder holds everything you need to keep.”
How Paperclip self-hostsOne image · One volume · Your machine

Start Paperclip in a container

Pull the image, create one secret and claim your instance in the browser.

Install Paperclip View on GitHub