📣
skpages · v1.0.0

Give your agent a voice on the internet.

One command. One link. Your own machines.

Your agent builds a report, a dashboard or a small site, runs sk-pages publish, and hands you a link. Private pages sit behind your SSO login. Public pages get a link nobody can guess. Every page lives in your own Nextcloud.

§How it works

SK Pages is two small pieces: a CLI (bash and curl, nothing else) that uploads pages over WebDAV into a Nextcloud folder, and a read-only Caddy that serves that folder on its own origin. Anything that can run a shell command can publish: Claude Code, Codex, Hermes, Pi, OpenCode, or a cron job.

$ sk-pages publish weekly-spend.html --talk https://pages.example.org/my-agent/weekly-spend/ sk-pages: link posted in Talk room abc123, thread 4711
1 · publish

Agent runs one command

sk-pages publish FILE|DIR uploads a file or a whole directory. stdout is only the URL, so a script can capture it.

2 · store

One copy, in Nextcloud

Pages land in a Nextcloud group folder, so no single account owns them. Versioned, searchable, backed up with the rest of your files.

3 · serve

Caddy only reads

The docroot is mounted read-only and Caddy's admin API is off. The web server cannot change a page, it can only hand it out.

4 · share

A person gets a link

Behind a login for private pages, or an unguessable /p/<token>/ link for public ones. Republishing keeps the same link.

It installs as an skskills skill, so every runtime on the machine reads the same SKILL.md before it publishes and knows the rules.

§Private by default, public by link

Everything on the site needs a login, except one area. That login is Authentik (through Traefik or inside Caddy) or simply membership of your tailnet.

PathWho can open itHow
/<agent>/<page>/Private. Only people who pass the login.sk-pages publish report.html
/p/<token>/<page>/Public. Anyone who has the link.sk-pages publish report.html --public
/p/ and /p/<token>/Nobody. Always 404, so public pages cannot be listed.Built into the serving rules

Tokens are 144 random bits. A public link is a secret in the plain sense: whoever holds it can open the page, so never put secrets in a page, public or private.

§Feedback in Talk

Add --talk (or --talk-room, --thread) and the CLI posts the link into a Nextcloud Talk thread titled Page: NAME. The person gets a notification, replies in that thread, and the agent reads the replies and republishes to the same link. If Talk rejects an old thread, the CLI starts a new one. A Talk failure never fails a publish: the page is already up.

agent ──publish──▶ Nextcloud (WebDAV) ──read-only──▶ Caddy ──▶ person ▲ │ │ └──── republish ◀── Talk thread "Page: report" ◀──── reply ────┘

§Pages cannot phone home

Pages are written by agents, and an agent can be wrong or prompt-injected. So SK Pages treats every page as untrusted HTML and sends a strict Content-Security-Policy with it. A page can run its own scripts and load common CDNs (cdnjs, jsDelivr, unpkg, Google Fonts), which is what charts and dashboards need. What it cannot do:

The honest limit: images may load from any HTTPS host, so a hostile page could still leak a little through an image URL. The CSP stops the easy, high-bandwidth ways out. It is not a sandbox for a page written by an attacker. The full threat model, with the test that backs each control, is in SECURITY.md.

§Three ways to run it

The server side is always the same read-only Caddy on :8080, bound to an overlay network or 127.0.0.1 and never a public port. What changes is what sits in front for TLS and the login.

SKStacks

Docker Swarm with Traefik and Authentik. The skstacks role optional/skpages serves pages.<cluster>.<domain>, puts authentik@file on the private router and a higher-priority public router on /p/.

Standalone Docker

docker compose up -d in deploy/standalone with the docroot path set. Bring your own TLS front, or set SKPAGES_AUTH=authentik and Caddy checks the login itself.

Tailscale

HTTPS on https://<machine>.<tailnet>.ts.net with no DNS, router or certificate work. Three setups, below.

TailscalePick a setup

A. Tailnet only. Being in the tailnet is the login. Simplest, and /p/ links also stay inside the tailnet.

tailscale serve --bg --https=443 http://127.0.0.1:8080

B. Tailnet for private pages, Funnel for public links. Funnel opens a whole port to the internet, so the two live on different ports: tailnet-only on 443, Funnel on 8443 with only /p/ mapped. On 8443 everything except /p/<token>/... is 404.

tailscale serve --bg --https=443 http://127.0.0.1:8080 tailscale funnel --bg --https=8443 --set-path=/p/ http://127.0.0.1:8080/p/ # ~/.config/sk-pages/config SKPAGES_PUBLIC_BASE_URL=https://<machine>.<tailnet>.ts.net:8443

C. Funnel plus SKSSO. Funnel the whole site and let Caddy check every private request against Authentik's forward-auth (SKPAGES_AUTH=authentik). Authentik must be reachable from the browser and from Caddy.

tailscale funnel --bg --https=443 http://127.0.0.1:8080

Never Funnel the port that serves private pages with SKPAGES_AUTH=none. Full steps, including the Authentik provider, are in SOP.md section 5.3.

§Quickstart

On the machine where your agent runs. You need a Nextcloud account for the agent with an app password, and the server side from one of the setups above.

git clone https://github.com/smilinTux/skpages && cd skpages ./install.sh # CLI on PATH (+ skill, if skskills is installed) mkdir -p ~/.config/sk-pages cat > ~/.config/sk-pages/config <<'EOF' SKPAGES_BASE_URL=https://pages.example.org EOF cat > ~/.config/sk-pages/env <<'EOF' NC_URL=https://cloud.example.org NC_USER=my-agent NC_APP_PASSWORD=xxxxx-xxxxx-xxxxx-xxxxx-xxxxx EOF chmod 600 ~/.config/sk-pages/env sk-pages init # creates skpages/ and skpages/p/ sk-pages publish report.html # prints the link

Then sk-pages list, sk-pages rm AGENT/NAME (Nextcloud keeps it in trash), and sk-pages config, which shows the settings in effect and never prints a secret. The app password reaches curl on a file descriptor, never on the command line.

§Why not a Nextcloud app?

It was the first idea. The pages are already in Nextcloud, so why not serve them from there? Because a page written by an agent is untrusted HTML, and serving untrusted HTML on the same origin as your Nextcloud session is stored XSS waiting to happen: any script on the page could act as the logged-in viewer.

Nextcloud agrees. It forces .html files to download instead of rendering them for exactly this reason, and its Notes app was fixed for this class of bug in CVE-2023-39955. So SK Pages keeps Nextcloud for what it is good at (storage, versions, sharing, WebDAV, Talk) and serves pages from a separate origin with a server that can only read.

It also means Nextcloud is not welded in for the people reading pages. They only ever talk to Caddy.

§Architecture, explorable

The same shape as above (agent and CLI, the Nextcloud group folder and Talk, the read-only Caddy, the TLS front and the Authentik login) as a standalone, self-contained page with a dark and light toggle. It opens in a new tab.

Its JSON source is diagrams/skpages.architecture.json in this repository, derived from, and never contradicting, the architecture in SOP.md section 2.