Setting up Paperclip AI to dokploy

This is not a full guide; I'm just documenting a series of issues I found while setting up Paperclip on my VPS using Dokploy/Docker. And this was the first issue.

References

• Dokploy

• Dokploy Template

• Paperclip Docs

Context

I have a VPS configured with Dokploy, and I wanted to experiment with Paperclip. I've seen many videos and discussions about the tool. I find it kind of interesting and probably will enable me to run some projects remotely and somewhat autonomously.

Hire your first agent

Basically, you might be following this guide from the official docs: Your First Agent. The main problem comes when you follow the instructions and you want to use your subscription to connect to your agent.

The catch

You might get a command that you need to run in the terminal. If you are not experienced with Docker or Dokploy, you might find this a blocker.

When you are connecting your first or any new agent, you get a command like this one to connect your subscription:

(export CODEX_HOME='/paperclip/instances/default/ai-local-logins/<uuid>' && mkdir -p "$CODEX_HOME" && codex -c 'cli_auth_credentials_store="file"' login --device-auth)

The main problem occurs when you connect to the Docker container and run the command using root or any other user different than the one that has access to the project structure; basically, it's node in this case.

What I did

Initially, I opened app.dokploy.com and established a new connection to the terminal directly from the web application. Apparently, the default connection opens a new shell or bash session using the root user.

This creates a conflict with the node user's permissions. Now, whatever runs under the hood of Paperclip is locked up.

Using your claude/codex subscription adapter

You must run the following commands

First, connect to your server

ssh ubuntu@<server-ip-or-host>

Then connect to the container

docker exec -it -u node <container> bash

Important to use -u node to avoid changing the project structure permissions, if you use the default user (root) the authentication fails.

Wrap up

And there you go! Basically, if you follow those simple steps when authorizing the subscription adapter, you won't have any permission issues.

So far, I found another issue that I'm documenting in the next part, if you need it.