cludseo/corkboard repository overview

⁠corkboard

A personal hosting service: upload a single HTML file or video and open it at a stable /a/{slug} URL. People upload through a web form, and agents use the same features through MCP tools.

⁠Before you start

• Platform: The image is published for linux/arm64 only.
• MongoDB: Stores artifact metadata.
• S3-compatible storage: Stores HTML and video content. The app does not create buckets, so a private bucket must already exist.

⁠Run the container

1. Create a private bucket in your S3-compatible storage. Put its name in S3_BUCKET in step 2.

2. Start the container with your environment variables. Use addresses reachable from inside the container. With a host loopback address such as 127.0.0.1, the container starts but requests fail.

   docker run -d --name corkboard -p 127.0.0.1:3000:3000 \
     -e MONGODB_URI=mongodb://mongo:27017/corkboard \
     -e S3_ENDPOINT=http://minio:9000 \
     -e S3_BUCKET=corkboard \
     -e S3_ACCESS_KEY_ID=<access-key> \
     -e S3_SECRET_ACCESS_KEY=<secret-key> \
     -e PUBLIC_BASE_URL=http://127.0.0.1:3000 \
     cludseo/corkboard:latest
   

   Copy

3. Open http://127.0.0.1:3000⁠ and check that the list page loads. If it does, the MongoDB connection works.

4. Upload a file at /new and check that its detail page renders. If it does, the storage connection works too.

To verify: the container runs as a non-root user on port 3000 and uses the list page (/) as its health check. Once docker ps shows healthy, it is ready.

⁠Environment variables

Every key has a default meant for local development. In production, change at least the public address and the storage keys.

PUBLIC_BASE_URL never falls back to the Host header. If you do not update it, the url in API and MCP responses keeps pointing at the old address.

⁠Upload artifacts

• Web: Upload HTML (.html, .htm) or video (.mp4, .webm, .ogv) at /new. The uploaded file opens at /a/{slug}.

• REST API: Send multipart data to POST /api/artifacts.

  curl -i -X POST http://127.0.0.1:3000/api/artifacts \
    -F 'title=Hello World' \
    -F 'visibility=PUBLIC' \
    -F 'file=@./hello.html;type=text/html'
  

  Copy

• MCP: /mcp provides five tools: list, get, create, update, and delete. In Claude Code, register it with claude mcp add --transport http corkboard http://127.0.0.1:3000/mcp. The app's /connect page also shows how to connect.

⁠Troubleshooting

⁠Limitations

• PRIVATE is a label for sorting, not access control. Private artifacts still appear in the list and open at the same URL.
• An upload uses about 5 times the file size in memory. At the default limit (50 MiB), one upload takes about 250 MiB, so raise container memory before raising the limit.
• Deletion cannot be undone. After a slug changes, the old URL returns 404.