Pubky Homeserver

https://github.com/pubky/pubky-homeserver
Admin
Pubky Homeserver is the core infrastructure for the Pubky protocol, providing user-owned storage,...
Tokens:279,788
Snippets:1,883
Trust Score:9.5
License:MIT
Update:1 week ago
Show doc for...
Tokens:
Raw
### Install SDK and examples

Source: https://github.com/pubky/pubky-homeserver/blob/main/examples/javascript/README.md

Build the local JS SDK package and install example dependencies. Requires Node 20+, npm, and Rust toolchain.

```bash
cd pubky-sdk/bindings/js/pkg
npm install
npm run build

cd ../../../../examples/javascript
npm install
```

--------------------------------

### Examples: GET, JSON POST, and --testnet requests with request binary

Source: https://github.com/pubky/pubky-homeserver/blob/main/examples/rust/4-request/README.md

Three sample invocations: a GET to the _pubky homeserver subdomain using the raw z-base32 key, a JSON POST with Content-Type and Accept headers, and a GET with --testnet for local testnet resolution. The --testnet example requires a running local testnet.

```bash
# HTTPS to the _pubky (homeserver) subdomain form (use the raw z-base32 key)
cargo run --bin request -- GET https://_pubky.<user_z32>/pub/my-cool-app/info.json

# JSON POST with headers
cargo run --bin request -- \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{"msg":"hello"}' \
  POST https://example.com/data.json

# Use local testnet endpoints
cargo run --bin request -- --testnet GET https://_pubky.<user_z32>/pub/my-cool-app/hello.txt

```

--------------------------------

### Development quick start commands

Source: https://github.com/pubky/pubky-homeserver/blob/main/pubky-sdk/bindings/js/README.md

Commands to install dependencies, build the wasm bundle, start a testnet, and run tests from the pkg directory.

```bash
npm install          # grab JS deps once
npm run build        # compile wasm + patch bundle
npm run testnet      # start local DHT + relay + homeserver (in another terminal)
npm run test         # run tape tests against the testnet + browser harness
```

--------------------------------

### Grant authorization flow - browser app setup (2-auth-flow)

Source: https://github.com/pubky/pubky-homeserver/blob/main/examples/javascript/README.md

Starts the browser app for the two-process grant authorization example. Requires npm install and npm run dev in the 2-auth-flow directory.

```bash
cd 2-auth-flow
npm install
npm run dev
```

--------------------------------

### Install Rust toolchain with rustup

Source: https://github.com/pubky/pubky-homeserver/blob/main/docs/INSTALL.md

Quick setup for the Rust toolchain using rustup. Source the environment after installation.

```bash
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
source ~/.cargo/env
```

--------------------------------

### Install and run the Vite browser app

Source: https://github.com/pubky/pubky-homeserver/blob/main/examples/javascript/5-browser-session-persistence/README.md

Run in a separate terminal from the example directory. Installs dependencies and starts the Vite dev server for the browser session persistence app.

```bash
cd examples/javascript/5-browser-session-persistence
npm install
npm run dev
```

--------------------------------

### Start Pubky testnet with Docker and PostgreSQL

Source: https://github.com/pubky/pubky-homeserver/blob/main/examples/rust/README.md

Start a disposable PostgreSQL container and then launch the Pubky testnet. The testnet requires PostgreSQL and these commands are run from the examples/rust directory. Wait for 'Testnet running' before running examples.

```bash
docker run --name pubky-postgres \
  -e POSTGRES_USER=postgres \
  -e POSTGRES_PASSWORD=postgres \
  -p 127.0.0.1:5432:5432 \
  -d postgres:18
```

```bash
TEST_PUBKY_CONNECTION_STRING='postgres://postgres:postgres@localhost:5432/postgres' \
  cargo run -p pubky-testnet
```

--------------------------------

### Initialize Pubky and start flows

Source: https://github.com/pubky/pubky-homeserver/blob/main/pubky-sdk/bindings/js/pkg/README.md

Shows how to create a Pubky instance for mainnet or local testnet, create a signer, start a grant auth flow, access public storage, resolve a homeserver, and get the raw HTTP client. Includes imports from @synonymdev/pubky.

```javascript
import { Pubky, Keypair, AuthFlowKind } from "@synonymdev/pubky";

// Mainnet (default relays)
const pubky = new Pubky();

// Local testnet wiring (Pkarr + HTTP mapping).
// Omit the argument for "localhost".
const pubkyLocal = Pubky.testnet("localhost");

// Signer (bind your keypair to a new Signer actor)
const signer = pubky.signer(Keypair.random());

// Grant Pubky Auth flow (with capabilities)
const authFlow = await pubky.startGrantAuthFlow(
  "/pub/my-cool-app/:rw",
  AuthFlowKind.signin(),
  { clientId: "my-cool-app.example" },
);

// Public storage (read-only)
const publicStorage = pubky.publicStorage;

// Pkdns resolver
const pkdns = pubky.getHomeserverOf(publicKey);

// Optional: raw HTTP client for advanced use
const client = pubky.client;
```

--------------------------------

### Enable and start systemd service

Source: https://github.com/pubky/pubky-homeserver/blob/main/docs/INSTALL.md

Reloads systemd, enables the service to start on boot, and starts it.

```bash
sudo systemctl daemon-reload
sudo systemctl enable pubky-homeserver
sudo systemctl start pubky-homeserver
```

--------------------------------

### Getting Started with Pubky SDK

Source: https://github.com/pubky/pubky-homeserver/blob/main/pubky-sdk/bindings/js/pkg/README.md

Complete workflow: create a Pubky facade, generate keys, sign up at a homeserver, sign in (direct or via QR auth flow), write and read public JSON. Uses default mainnet Pkarr relays; use Pubky.testnet() for localhost testnet. The signup token can be null if no invite is required.

```javascript
import { Pubky, PublicKey, Keypair, AuthFlowKind } from "@synonymdev/pubky";

// Initiate a Pubky SDK facade wired for default mainnet Pkarr relays.
const pubky = new Pubky(); // or: const pubky = Pubky.testnet(); for localhost testnet.

// 1) Create random user keys and bind to a new Signer.
const keypair = Keypair.random();
const signer = pubky.signer(keypair);

// 2) Sign up at a homeserver (optionally with an invite)
const homeserver = PublicKey.from(
  "8pinxxgqs41n4aididenw5apqp1urfmzdztr8jt4abrkdn435ewo"
);
const signupToken = "<your-invite-code-or-null>";
await signer.signup(homeserver, signupToken);

// 3a) Signin with the signer directly.
let session = await signer.signin("example.com");

// 3b) Or, if you do not have the keypair available, authenticate on a 3rd-party app
// by delegating the authentication to a signer with a QR code.
const authFlow = await pubky.startGrantAuthFlow(
  "/pub/my-cool-app/:rw",
  AuthFlowKind.signin(),
  { clientId: "my-cool-app.example" },
);
renderQr(authFlow.authorizationUrl); // Show to user the signin deeplink via a QR code
session = await authFlow.awaitApproval();

// 4) Write a public JSON file
const path = "/pub/my-cool-app/hello.json";
await session.storage.putJson(path, { hello: "world" });

// 5) Read it publicly (no auth needed)
const userPk = session.info.publicKey.toString();
const addr = `${userPk}/pub/my-cool-app/hello.json`;
const json = await pubky.publicStorage.getJson(addr); // -> { hello: "world" }
```

--------------------------------

### Run an example with --testnet

Source: https://github.com/pubky/pubky-homeserver/blob/main/examples/javascript/README.md

Run the signup example against a local testnet. Requires the testnet to be running.

```bash
cd examples/javascript
node 1-signup.mjs --testnet
```

--------------------------------

### Start PostgreSQL Server with pg_ctlcluster

Source: https://github.com/pubky/pubky-homeserver/blob/main/docs/INSTALL.md

Starts the PostgreSQL server using pg_ctlcluster. Not needed on systems with systemd where PostgreSQL starts automatically.

```bash
pg_ctlcluster $(pg_lsclusters -h | awk '{print $1, $2}') start
```

--------------------------------

### Run testnet with Dockerized PostgreSQL

Source: https://github.com/pubky/pubky-homeserver/blob/main/examples/rust/8-testnet/README.md

Runs the testnet example with a Dockerized PostgreSQL instance. Docker must be running on the host for this default setup.

```bash
cargo run --bin testnet
```

--------------------------------

### signup-tokens generate examples

Source: https://github.com/pubky/pubky-homeserver/blob/main/homeservercli/README.md

Two examples: one with unlimited storage and default rates, and one with 500 MB storage and custom read/write rates.

```sh
# Unlimited storage, default rates
homeservercli signup-tokens generate --storage-quota-mb unlimited
```

```sh
# 500 MB storage, 10 MB/s read, 1 MB/s write
homeservercli signup-tokens generate \
  --storage-quota-mb 500 \
  --rate-read 10mb/s \
  --rate-write 1mb/s
```

--------------------------------

### Install and run pubky-testnet

Source: https://github.com/pubky/pubky-homeserver/blob/main/pubky-sdk/bindings/js/pkg/README.md

Install the pubky-testnet crate and run the local testnet.

```bash
cargo install pubky-testnet
pubky-testnet
```

--------------------------------

### Run signup example with --testnet

Source: https://github.com/pubky/pubky-homeserver/blob/main/examples/rust/README.md

Run the signup example against a local testnet. Execute this in another terminal after the testnet reports 'Testnet running'. The --testnet flag expects a local testnet to be available.

```bash
cd examples/rust
cargo run --bin signup -- --testnet
```

--------------------------------

### Run storage example against local testnet

Source: https://github.com/pubky/pubky-homeserver/blob/main/examples/rust/3-storage/README.md

Runs the storage example with default settings against a local testnet. Requires a running local testnet as described in the examples README.

```bash
cargo run --bin storage -- --testnet
```

--------------------------------

### Run storage example with custom path and content

Source: https://github.com/pubky/pubky-homeserver/blob/main/examples/rust/3-storage/README.md

Runs the storage example with a custom path and content. The path and content are passed as command-line arguments.

```bash
cargo run --bin storage -- --testnet /pub/my-app/data.json --content "my data"
```

--------------------------------

### Check homeserver and testnet images run without services

Source: https://github.com/pubky/pubky-homeserver/blob/main/docs/TESTING.md

Runs the homeserver and testnet images with --network none to verify the binary runs without starting services or connecting to PostgreSQL. Both images install their binary as homeserver.

```bash
docker run --rm --network none pubky-homeserver:debug homeserver --help
```

```bash
docker run --rm --network none pubky-testnet:release homeserver --help
```

--------------------------------

### Install Rust

Source: https://github.com/pubky/pubky-homeserver/blob/main/pubky-sdk/bindings/js/pkg/README.md

Install Rust via rustup, required for wasm and testnet builds.

```bash
curl https://sh.rustup.rs -sSf | sh
```

--------------------------------

### users quota-set examples

Source: https://github.com/pubky/pubky-homeserver/blob/main/homeservercli/README.md

Examples for setting storage limit, removing limit, resetting to default, setting read rate, and restricting write paths.

```sh
# Set storage limit to 1 GB
homeservercli users quota-set <PUBKY> --storage-quota-mb 1024
```

```sh
# Remove storage limit
homeservercli users quota-set <PUBKY> --storage-quota-mb unlimited
```

```sh
# Reset the storage override back to the system default
homeservercli users quota-set <PUBKY> --storage-quota-mb default
```

```sh
# Set read rate to 5 MB/s
homeservercli users quota-set <PUBKY> --rate-read 5mb/s
```

```sh
# Restrict writes to specific paths (repeatable)
homeservercli users quota-set <PUBKY> \
  --allowed-write-paths /pub/tokens/ \
  --allowed-write-paths /pub/profile.json
```

--------------------------------

### Install with cargo install

Source: https://github.com/pubky/pubky-homeserver/blob/main/homeservercli/README.md

Installs the Homeserver CLI from the current directory using Cargo.

```sh
cargo install --path .
```

--------------------------------

### Config file example (config.toml)

Source: https://github.com/pubky/pubky-homeserver/blob/main/homeservercli/README.md

Example configuration file for the CLI, compatible with the pubky-homeserver config format. The listen_socket accepts a bare socket address or a full URL.

```toml
[admin]
admin_password = "your-admin-password"
listen_socket = "127.0.0.1:6288"
```

--------------------------------

### Start the testnet

Source: https://github.com/pubky/pubky-homeserver/blob/main/examples/javascript/README.md

Run the Pubky testnet from the repository root. Wait for 'Testnet running' before proceeding.

```bash
cargo run -p pubky-testnet
```

--------------------------------

### Start PostgreSQL with Docker

Source: https://github.com/pubky/pubky-homeserver/blob/main/docs/TESTING.md

Starts a local PostgreSQL 18 container for running homeserver and testnet tests. Uses credentials postgres/postgres and exposes port 5432 on localhost.

```bash
docker run --name pubky-postgres \
  -e POSTGRES_USER=postgres \
  -e POSTGRES_PASSWORD=postgres \
  -p 127.0.0.1:5432:5432 \
  -d postgres:18
```

--------------------------------

### Run logging example with debug level

Source: https://github.com/pubky/pubky-homeserver/blob/main/examples/rust/7-logging/README.md

Runs the logging example with verbose tracing. Requires Docker to be running on the host.

```bash
cargo run --bin logging -- --level debug
```

--------------------------------

### Run logging example with custom connection string

Source: https://github.com/pubky/pubky-homeserver/blob/main/examples/rust/7-logging/README.md

Runs the logging example with a custom PostgreSQL connection string via the TEST_PUBKY_CONNECTION_STRING environment variable.

```bash
TEST_PUBKY_CONNECTION_STRING=postgres://user:pass@localhost:5432/mydb cargo run --bin logging -- --level debug --external-postgres
```

--------------------------------

### Install PostgreSQL on Native System

Source: https://github.com/pubky/pubky-homeserver/blob/main/docs/INSTALL.md

Installs PostgreSQL using apt on Ubuntu-based systems.

```bash
sudo apt update && sudo apt install -y postgresql
```

--------------------------------

### Run testnet with custom PostgreSQL connection string

Source: https://github.com/pubky/pubky-homeserver/blob/main/examples/rust/8-testnet/README.md

Runs the testnet example with a custom PostgreSQL connection string via the TEST_PUBKY_CONNECTION_STRING environment variable. Each testnet automatically gets its own ephemeral pubky_test_{uuid} database on the configured server.

```bash
TEST_PUBKY_CONNECTION_STRING=postgres://user:pass@localhost:5432/mydb cargo run --bin testnet -- --external-postgres
```

--------------------------------

### Run homeserver natively in foreground

Source: https://github.com/pubky/pubky-homeserver/blob/main/docs/INSTALL.md

Starts the homeserver in the foreground for testing; press Ctrl+C to stop. Does not survive reboots.

```bash
pubky-homeserver
```

--------------------------------

### Run homeserver with Docker

Source: https://github.com/pubky/pubky-homeserver/blob/main/docs/INSTALL.md

Starts the homeserver in a Docker container with --network=host to reach PostgreSQL on the host, volume mount for data, and restart policy.

```bash
docker run -d --name pubky-homeserver --restart unless-stopped --network=host -v ~/.pubky:/root/.pubky pubky-homeserver homeserver
```

--------------------------------

### Run storage example with custom recovery file

Source: https://github.com/pubky/pubky-homeserver/blob/main/examples/rust/3-storage/README.md

Runs the storage example with a custom recovery file. The recovery file path is provided via the --recovery-file flag.

```bash
cargo run --bin storage -- --testnet --recovery-file </path/to/recovery file>
```

--------------------------------

### Example output

Source: https://github.com/pubky/pubky-homeserver/blob/main/examples/rust/5-events_stream/README.md

Example output showing PUT and DEL events.

```text
[PUT] pubky://o1gg96ewuojmopcjbz8895478wdtxtzzuxnfjjz8o8e77csa1ngo/pub/posts/123 (cursor: 42, hash: abc123...)
[DEL] pubky://o1gg96ewuojmopcjbz8895478wdtxtzzuxnfjjz8o8e77csa1ngo/pub/posts/456 (cursor: 43, hash: -)
```

--------------------------------

### Example: GET a user's social post from pubky homeserver

Source: https://github.com/pubky/pubky-homeserver/blob/main/examples/rust/4-request/README.md

Concrete GET command that returns the content of a user's social post from their pubky homeserver. Uses a real _pubky host key in the URL.

```bash
cargo run --bin request -- GET https://_pubky.operrr8wsbpr3ue9d4qj41ge1kcc6r7fdiy6o3ugjrrhi4y77rdo/pub/pubky.app/posts/0033X02JAN0SG

```

--------------------------------

### Install SDK dependencies (npm install)

Source: https://github.com/pubky/pubky-homeserver/blob/main/examples/javascript/README.md

Installs the local SDK package dependencies, including fetch-cookie. Run this when the module fetch-cookie cannot be found.

```bash
cd pubky-sdk/bindings/js/pkg
npm install
```

--------------------------------

### Start local testnet with npm run testnet

Source: https://github.com/pubky/pubky-homeserver/blob/main/examples/javascript/5-browser-session-persistence/README.md

Run in a terminal from pubky-sdk/bindings/js/pkg to start a local testnet before launching the browser app.

```bash
cd pubky-sdk/bindings/js/pkg
npm run testnet
```

--------------------------------

### Initialize Data Directory with pubky-homeserver init

Source: https://github.com/pubky/pubky-homeserver/blob/main/docs/INSTALL.md

Creates the default data directory, sample config.toml, and server keypair without starting the server or connecting to PostgreSQL. Available from v0.10 onwards; on v0.9 or earlier the directory is created automatically on first run.

```bash
pubky-homeserver init
```

--------------------------------

### Run logging example with external PostgreSQL

Source: https://github.com/pubky/pubky-homeserver/blob/main/examples/rust/7-logging/README.md

Runs the logging example using an external PostgreSQL instance. Uses the default connection string postgres://postgres:postgres@localhost:5432/postgres unless overridden.

```bash
# Uses postgres://postgres:postgres@localhost:5432/postgres by default
cargo run --bin logging -- --level debug --external-postgres
```

--------------------------------

### Verify release binary install

Source: https://github.com/pubky/pubky-homeserver/blob/main/docs/INSTALL.md

Checks that the installed binary runs and prints its version.

```bash
pubky-homeserver --version
```

--------------------------------

### Start PostgreSQL Container with Docker

Source: https://github.com/pubky/pubky-homeserver/blob/main/docs/INSTALL.md

Starts a PostgreSQL 18 container with the pubky_homeserver database, user postgres, and password postgres. The container restarts unless stopped and exposes port 5432 on localhost only. Requires Docker Engine.

```bash
docker run --name pubky-postgres \
  --restart unless-stopped \
  -e POSTGRES_USER=postgres \
  -e POSTGRES_PASSWORD=postgres \
  -e POSTGRES_DB=pubky_homeserver \
  -p 127.0.0.1:5432:5432 \
  -v postgres-data:/var/lib/postgresql \
  -d postgres:18
```

--------------------------------

### Enable docker-postgres feature

Source: https://github.com/pubky/pubky-homeserver/blob/main/docs/TESTING.md

Adds the docker-postgres feature to pubky-testnet dev-dependencies, allowing tests to automatically start a PostgreSQL container via Docker. Useful for self-contained tests or CI.

```toml
[dev-dependencies]
pubky-testnet = { version = "<version>", features = ["docker-postgres"] }
```

--------------------------------

### Per-test Docker PostgreSQL container

Source: https://github.com/pubky/pubky-homeserver/blob/main/docs/TESTING.md

Starts a separate PostgreSQL container for each test using .with_docker_postgres(). Simple but expensive for large test suites.

```rust
use pubky_testnet::EphemeralTestnet;

#[tokio::test]
async fn my_test() {
    let testnet = EphemeralTestnet::builder()
        .with_docker_postgres()
        .build()
        .await
        .unwrap();

    let homeserver = testnet.homeserver_app();
}
```

--------------------------------

### Configure PostgreSQL database_url in config.toml

Source: https://github.com/pubky/pubky-homeserver/blob/main/docs/INSTALL.md

Uncomment and set the database_url in ~/.pubky/config.toml to connect to PostgreSQL. The example uses postgres://postgres:postgres@localhost:5432/pubky_homeserver.

```toml
[general]
database_url = "postgres://postgres:postgres@localhost:5432/pubky_homeserver"
```

--------------------------------

### Start homeserver with HomeserverApp

Source: https://github.com/pubky/pubky-homeserver/blob/main/pubky-homeserver/README.md

Starts the full server stack (client server, admin server, metrics server, DHT republishers) using HomeserverApp. Prints the HTTP and Pubky TLS URLs, and the admin server address if available. Waits for Ctrl+C to shut down.

```rust
use pubky_homeserver::HomeserverApp;
use std::path::PathBuf;

#[tokio::main]
async fn main() -> anyhow::Result<()> {
    let app = HomeserverApp::start_with_persistent_data_dir_path(
        PathBuf::from("~/.pubky")
    ).await?;

    println!("Homeserver HTTP: {}", app.icann_http_url());
    println!("Homeserver Pubky TLS: {}", app.pubky_url());

    if let Some(admin) = app.admin_server() {
        println!("Admin server: http://{}", admin.listen_socket());
    }

    tokio::signal::ctrl_c().await?;
    Ok(())
}
```

--------------------------------

### Check PostgreSQL readiness with native install

Source: https://github.com/pubky/pubky-homeserver/blob/main/docs/INSTALL.md

Use to verify PostgreSQL is running when connection is refused. Reports 'no response' if not running.

```bash
pg_isready
```

--------------------------------

### Start fresh testnet for multi-window regression

Source: https://github.com/pubky/pubky-homeserver/blob/main/pubky-sdk/bindings/js/README.md

Command to start a fresh testnet with a specific homeserver config for running the multi-window regression tests.

```bash
cargo run -p pubky-testnet -- --homeserver-config pubky-sdk/bindings/js/pkg/scripts/session-tabs.toml
```

--------------------------------

### Run tests with test connection string

Source: https://github.com/pubky/pubky-homeserver/blob/main/docs/TESTING.md

Runs pubky-homeserver tests with all features, using the TEST_PUBKY_CONNECTION_STRING environment variable to point to the local PostgreSQL instance. Each test gets its own ephemeral pubky_test_{uuid} database that is cleaned up after the test.

```bash
TEST_PUBKY_CONNECTION_STRING='postgres://postgres:postgres@localhost:5432/postgres' \
  cargo test -p pubky-homeserver --all-features
```

--------------------------------

### Error Handling Example

Source: https://github.com/pubky/pubky-homeserver/blob/main/pubky-sdk/bindings/js/pkg/README.md

Demonstrates how to catch and inspect a PubkyError, specifically checking for a RequestError with a 404 status code to handle not-found scenarios.

```APIDOC
## Error Handling Example

### Description
Demonstrates how to catch and inspect a PubkyError, specifically checking for a RequestError with a 404 status code to handle not-found scenarios.

### JavaScript Example
```js
try {
  await publicStorage.getJson(`${pk}/pub/example.com/missing.json`);
} catch (e) {
  const error = e as PubkyError;
  if (
    error.name === "RequestError" &&
    typeof error.data === "object" &&
    error.data !== null &&
    "statusCode" in error.data &&
    typeof (error.data as { statusCode?: number }).statusCode === "number" &&
    (error.data as { statusCode?: number }).statusCode === 404
  ) {
    // handle not found
  }
}
```
```

--------------------------------

### Install build dependencies

Source: https://github.com/pubky/pubky-homeserver/blob/main/docs/INSTALL.md

Installs packages required to build from source on Debian-based systems.

```bash
sudo apt update && sudo apt install -y build-essential pkg-config libssl-dev git curl
```

--------------------------------

### Start from specific cursors for multiple users

Source: https://github.com/pubky/pubky-homeserver/blob/main/examples/rust/5-events_stream/README.md

Fetches events starting from specific cursors for two users.

```bash
cargo run --bin events_stream -- \
  o1gg96ewuojmopcjbz8895478wdtxtzzuxnfjjz8o8e77csa1ngo \
  pxnu33x7jtpx9ar1ytsi4yxbp6a5o36gwhffs8zoxmbuptici1jy \
  --cursors "1234567890,9876543210" \
  --limit 50
```

--------------------------------

### Build binary with Cargo

Source: https://github.com/pubky/pubky-homeserver/blob/main/docs/INSTALL.md

Builds the pubky-homeserver binary in release mode and copies it to /usr/local/bin.

```bash
cargo build --release -p pubky-homeserver
cp ./target/release/pubky-homeserver /usr/local/bin
```

--------------------------------

### Run installed homeserver binary

Source: https://github.com/pubky/pubky-homeserver/blob/main/pubky-homeserver/README.md

Runs the installed pubky-homeserver binary with a specified data directory.

```bash
pubky-homeserver --data-dir ~/.pubky
```

--------------------------------

### Signup with testnet and sample recovery file

Source: https://github.com/pubky/pubky-homeserver/blob/main/examples/rust/1-signup/README.md

Runs the signup binary against a local testnet homeserver using the default sample recovery file. Requires a running local testnet.

```bash
# use the local testnet homeserver and sample recovery file
cargo run --bin signup -- --testnet
```

--------------------------------

### Run the JavaScript grant auth flow

Source: https://github.com/pubky/pubky-homeserver/blob/main/examples/javascript/2-auth-flow/README.md

Start a local testnet in one terminal, then start the browser app in another, and finally approve the generated auth URL in a third terminal using the authenticator CLI.

```bash
cd pubky-sdk/bindings/js/pkg
npm run testnet
```

```bash
cd examples/javascript/2-auth-flow
npm install
npm run dev
```

```bash
cd examples/javascript
node 2-authenticator.mjs "<AUTH_URL>" --testnet
```

--------------------------------

### Run auth_client for sign-up and sign-in

Source: https://github.com/pubky/pubky-homeserver/blob/main/examples/rust/2-auth_flow/README.md

Starts the auth_client CLI with the --signup flag to sign up and sign in in one flow. The first command uses the local testnet; the second targets a non-testnet homeserver, requiring its public key and an optional signup code. The signup URL uses the signup_grant intent.

```bash
cargo run --bin auth_client -- --testnet --signup
```

```bash
cargo run --bin auth_client -- --signup \
  --homeserver <HOMESERVER_PUBLIC_KEY> \
  --signup-code <SIGNUP_CODE>
```

--------------------------------

### Copy binary to PATH

Source: https://github.com/pubky/pubky-homeserver/blob/main/docs/INSTALL.md

Places the extracted binary into /usr/local/bin so it can be run from anywhere.

```bash
cp pubky-homeserver-v${PUBKY_VERSION}-${PUBKY_PLATFORM}/pubky-homeserver /usr/local/bin
```

--------------------------------

### Signup with custom recovery file and signup code

Source: https://github.com/pubky/pubky-homeserver/blob/main/examples/rust/1-signup/README.md

Runs the signup binary against a mainnet homeserver with a custom recovery file and a signup code.

```bash
# With a custom recovery file and signup code
cargo run --bin signup <homeserver pubky> --recovery-file </path/to/recovery file> --signup-code <code>
```

--------------------------------

### Verify Docker image

Source: https://github.com/pubky/pubky-homeserver/blob/main/docs/INSTALL.md

Runs the image to check the homeserver version.

```bash
docker run --rm pubky-homeserver homeserver --version
```

--------------------------------

### keypair.publicKey

Source: https://github.com/pubky/pubky-homeserver/blob/main/pubky-sdk/bindings/js/pkg/README.md

Gets the public key of the keypair.

```APIDOC
## keypair.publicKey

### Description
Gets the public key of the keypair.

### Method
Property

### Endpoint
`keypair.publicKey`

### Parameters
None

### Request Example
```js
const pubkey = keypair.publicKey;
```

### Response
Returns a PublicKey instance.
```

--------------------------------

### Run logging example with debug level

Source: https://github.com/pubky/pubky-homeserver/blob/main/examples/javascript/README.md

Uses setLogLevel() to surface the SDK's internal tracing while performing a quick storage roundtrip. Override --homeserver for mainnet infrastructure or change --level to reduce noise.

```bash
node 7-logging.mjs --testnet --level debug
```

--------------------------------

### Install cloudflared as a systemd service

Source: https://github.com/pubky/pubky-homeserver/blob/main/docs/deploy/cloudflare-tunnel.md

Installs cloudflared as a systemd service so it starts on boot. The config path is passed explicitly because sudo changes the home directory to /root.

```bash
sudo cloudflared --config ~/.cloudflared/config.yml service install
sudo systemctl enable cloudflared
sudo systemctl start cloudflared
```

--------------------------------

### Signup to mainnet homeserver

Source: https://github.com/pubky/pubky-homeserver/blob/main/examples/rust/1-signup/README.md

Runs the signup binary against a mainnet homeserver by providing the homeserver pubky as an argument.

```bash
# Signup to a mainnet homeserver
cargo run --bin signup <homeserver pubky>
```

--------------------------------

### Install Pubky SDK via npm

Source: https://github.com/pubky/pubky-homeserver/blob/main/pubky-sdk/bindings/js/pkg/README.md

Install the @synonymdev/pubky package. Requires Node v20+ (undici fetch, WebCrypto). Supports ESM and CommonJS with TypeScript typings.

```bash
npm install @synonymdev/pubky
```

--------------------------------

### start_grant_auth_flow (Rust)

Source: https://github.com/pubky/pubky-homeserver/blob/main/docs/v0.10-migration/grant-auth.md

Starts a grant authentication flow in Rust, returning a flow with an authorization URL and an await_approval method.

```APIDOC
## start_grant_auth_flow

### Description
Starts a grant authentication flow in Rust, returning a flow with an authorization URL and an await_approval method.

### Method
start_grant_auth_flow

### Parameters
- **caps** (string) - Required - Capability string, e.g., "/pub/my-app/:rw"
- **auth_flow_kind** (AuthFlowKind) - Required - The authentication flow kind, e.g., AuthFlowKind::signin()
- **client_id** (ClientId) - Required - The client ID, e.g., ClientId::new("my-app.example")?

### Request Example
```rust
let client_id = ClientId::new("my-app.example")?;
let flow = pubky.start_grant_auth_flow(
    &caps,
    AuthFlowKind::signin(),
    client_id,
)?;
```

### Response
Returns a flow object with:
- **authorization_url()** (String) - The URL to display for scanning
- **await_approval()** (Future) - Resolves to a session after user approval
```

--------------------------------

### Signup with recovery file (1-signup.mjs)

Source: https://github.com/pubky/pubky-homeserver/blob/main/examples/javascript/README.md

Runs the signup script with optional homeserver, recovery file, signup code, and testnet flag. Defaults to ../sample_recovery.key with empty passphrase; prompts for passphrase if encrypted.

```bash
node 1-signup.mjs [homeserver_pubky] [--recovery-file <path>] [--signup-code <code>] [--testnet]

# use the local testnet homeserver and sample recovery file
node 1-signup.mjs --testnet

# with a custom recovery file and signup code
node 1-signup.mjs <homeserver_pubky> --recovery-file ./alice.recovery --signup-code INVITE-123
```

--------------------------------

### Install Pubky SDK with Cargo.toml

Source: https://github.com/pubky/pubky-homeserver/blob/main/pubky-sdk/README.md

Add the pubky crate as a dependency in your Cargo.toml. Optional helpers like pubky-testnet are commented out for use in examples.

```toml
# Cargo.toml
[dependencies]
pubky = "0.x"            # this crate
# Optional helpers used in examples:
# pubky-testnet = "0.x"
```

--------------------------------

### pubky.startGrantAuthFlow(path, kind, options)

Source: https://github.com/pubky/pubky-homeserver/blob/main/pubky-sdk/bindings/js/pkg/README.md

Starts a Pubky Auth flow with capabilities. Returns an AuthFlow object for completing the authentication.

```APIDOC
## pubky.startGrantAuthFlow(path, kind, options)

### Description
Starts a Pubky Auth flow with capabilities. Returns an AuthFlow object for completing the authentication.

### Method
Method

### Endpoint
`pubky.startGrantAuthFlow(path, kind, options)`

### Parameters
- **path** (string) - Required - The path pattern for the capabilities (e.g., `/pub/my-cool-app/:rw`).
- **kind** (AuthFlowKind) - Required - The kind of auth flow (e.g., `AuthFlowKind.signin()`).
- **options** (object) - Required - Additional options, e.g., `{ clientId: "my-cool-app.example" }`.

### Request Example
```js
const authFlow = await pubky.startGrantAuthFlow(
  "/pub/my-cool-app/:rw",
  AuthFlowKind.signin(),
  { clientId: "my-cool-app.example" },
);
```

### Response
Returns an AuthFlow object.
```

--------------------------------

### Start grant auth flow and save session

Source: https://github.com/pubky/pubky-homeserver/blob/main/pubky-sdk/bindings/js/pkg/README.md

Starts a delegated browser PoP key auth flow, falling back to local PoP keys when unsupported. Delegated sessions keep PoP keys non-extractable; local sessions store bearer-equivalent secrets in IndexedDB.

```JavaScript
const flow = await pubky.startGrantAuthFlow(
  "/pub/example.com/:rw",
  AuthFlowKind.signin(),
  { clientId: "example.com" },
);
const session = await flow.awaitApproval();
await pubky.browserSessionStore.save(session);
```

--------------------------------

### Homeserver configuration in config.toml

Source: https://github.com/pubky/pubky-homeserver/blob/main/docs/deploy/domain.md

Edit ~/.pubky/config.toml to set drive and pkdns settings. Replace YOUR_IP with the public IP (find via curl -4 ifconfig.me) and YOUR_DOMAIN with your domain. Do not apply 0.0.0.0 to icann_listen_socket, admin.listen_socket, or metrics.listen_socket; keep them on 127.0.0.1. Ensure a static public IP to avoid PKARR, Caddy, and DNS pointing to a dead address.

```toml
[drive]
# Listen on all interfaces so Pubky TLS is reachable from the internet
pubky_listen_socket = "0.0.0.0:6287"

# icann_listen_socket defaults to 127.0.0.1:6286 — no change needed.

# Accept client addresses from the local Caddy proxy.
icann_client_identity = { mode = "proxy_protocol", trusted_proxies = ["127.0.0.1/32"] }

[pkdns]
# The public-facing IP of this machine. Published to the DHT so that
# Pubky TLS clients can connect directly to the homeserver.
public_ip = "YOUR_IP"

# Your domain name for HTTPS browser access.
icann_domain = "YOUR_DOMAIN"

```

--------------------------------

### systemd service unit for pubky-homeserver

Source: https://github.com/pubky/pubky-homeserver/blob/main/docs/INSTALL.md

Systemd unit file to run the homeserver in the background, start on boot, and restart on failure. Replace YOUR_USER with your Linux username.

```ini
[Unit]
Description=Pubky Homeserver
# Use postgresql.service if you installed Postgres natively,
# or docker.service if you run Postgres in Docker.
After=network-online.target postgresql.service
Wants=network-online.target

[Service]
# Path to the pubky-homeserver binary. The --data-dir flag tells it where
# to find config.toml and the keypair (defaults to ~/.pubky).
ExecStart=/usr/local/bin/pubky-homeserver --data-dir /home/YOUR_USER/.pubky
# The OS user that the homeserver process runs as
User=YOUR_USER
# The homeserver listens for SIGINT (Ctrl+C), not SIGTERM.
KillSignal=SIGINT
Restart=on-failure
RestartSec=5

[Install]
WantedBy=multi-user.target
```

--------------------------------

### Download and extract release archive

Source: https://github.com/pubky/pubky-homeserver/blob/main/docs/INSTALL.md

Downloads the release tarball and extracts it. Requires curl.

```bash
curl -LO https://github.com/pubky/pubky-homeserver/releases/download/v${PUBKY_VERSION}/pubky-homeserver-v${PUBKY_VERSION}-${PUBKY_PLATFORM}.tar.gz
tar -xf pubky-homeserver-v${PUBKY_VERSION}-${PUBKY_PLATFORM}.tar.gz
```

--------------------------------

### Run auth_client for sign-in

Source: https://github.com/pubky/pubky-homeserver/blob/main/examples/rust/2-auth_flow/README.md

Starts the auth_client CLI against a local testnet to begin a sign-in grant flow. The optional flags customize the client ID and requested capabilities. Requires a running local testnet.

```bash
cargo run --bin auth_client -- --testnet

# with a custom client ID or capabilities
cargo run --bin auth_client -- --testnet \
  --client-id my-app.example \
  --capabilities /pub/my-app/:rw
```

--------------------------------

### Signup with testnet and custom recovery file

Source: https://github.com/pubky/pubky-homeserver/blob/main/examples/rust/1-signup/README.md

Runs the signup binary against a local testnet homeserver with a custom recovery file specified via --recovery-file.

```bash
# with a custom recovery file
cargo run --bin signup -- --testnet --recovery-file </path/to/recovery file>
```

--------------------------------

### PublicStorage read-only operations

Source: https://github.com/pubky/pubky-homeserver/blob/main/pubky-sdk/bindings/js/pkg/README.md

Access the read-only public storage via `pubky.publicStorage`. Supports reads (`get`, `getJson`, `getText`, `getBytes`), metadata (`exists`, `stats`), and directory listing with `list`. The addressed path must include a trailing `/` for directory listing. `get()` returns a raw `Response` for streaming or custom parsing.

```javascript
const pub = pubky.publicStorage;

// Reads
const response = await pub.get(
  `${userPk}/pub/example.com/data.json`
); // -> Response (stream it)
await pub.getJson(`${userPk}/pub/example.com/data.json`);
await pub.getText(`${userPk}/pub/example.com/readme.txt`);
await pub.getBytes(`${userPk}/pub/example.com/icon.png`); // Uint8Array

// Metadata
await pub.exists(`${userPk}/pub/example.com/foo`); // boolean
await pub.stats(`${userPk}/pub/example.com/foo`); // { content_length, content_type, etag, last_modified } | null

// List directory (addressed path "<pubky>/pub/.../") must include trailing `/`.
// list(addr, cursor=null|suffix|fullUrl, reverse=false, limit?, shallow=false)
await pub.list(
  `${userPk}/pub/example.com/`,
  null,
  false,
  100,
  false
);
```

--------------------------------

### Start Grant Auth Flow with Pubky

Source: https://github.com/pubky/pubky-homeserver/blob/main/pubky-sdk/bindings/js/pkg/README.md

Initializes a Pubky instance and starts a grant auth flow for third-party app authentication via QR or deeplink. Requires a capabilities string and optional relay URL; defaults to Synonym-hosted relay if omitted. The flow returns an authorization URL to display and awaits user approval to obtain a session.

```javascript
import { Pubky, AuthFlowKind } from "@synonymdev/pubky";
const pubky = new Pubky();

// Comma-separated capabilities string
const caps = "/pub/my-cool-app/:rw,/pub/another-app/folder/:w";

// Optional relay; defaults to Synonym-hosted relay if omitted
const relay = "https://httprelay.pubky.app/inbox/"; // optional (defaults to this)

// Start grant auth polling
const flow = await pubky.startGrantAuthFlow(
  caps,
  AuthFlowKind.signin(),
  {
    clientId: "my-cool-app.example",
    relay,
    xCallback: {
      xSource: "My Cool App",
      xSuccess: "my-cool-app://auth/success?nonce=unique",
      xError: "my-cool-app://auth/error?nonce=unique",
      xCancel: "my-cool-app://auth/cancel?nonce=unique",
    },
  },
);

renderQr(flow.authorizationUrl); // show to user

// Blocks until the signer approves; returns a ready Session
const session = await flow.awaitApproval();
```

--------------------------------

### Usage syntax

Source: https://github.com/pubky/pubky-homeserver/blob/main/homeservercli/README.md

Shows the general usage syntax for the CLI.

```text
homeservercli [OPTIONS] <SUBCOMMAND>
```

--------------------------------

### setLogLevel

Source: https://github.com/pubky/pubky-homeserver/blob/main/pubky-sdk/bindings/js/pkg/README.md

Sets the verbosity level for the WASM logger that bridges Rust log output into the browser or Node console. Must be called once at application start, before constructing Pubky or other SDK actors.

```APIDOC
## setLogLevel

### Description
Sets the verbosity level for the WASM logger that bridges Rust log output into the browser or Node console. Must be called once at application start, before constructing Pubky or other SDK actors.

### Method
Function call

### Endpoint
`setLogLevel(level)`

### Parameters
- **level** (string) - Required - The log level: `"error"`, `"warn"`, `"info"`, `"debug"`, or `"trace"`.

### Request Example
```js
import { setLogLevel } from "@synonymdev/pubky";
setLogLevel("debug");
```

### Response
No return value. Throws an error if the logger is already initialized.
```

--------------------------------

### pubky.startGrantAuthFlow(caps, kind, options)

Source: https://github.com/pubky/pubky-homeserver/blob/main/pubky-sdk/bindings/js/pkg/README.md

Starts a grant authentication flow. Chooses delegated browser PoP keys when the runtime supports them, otherwise falls back to local PoP keys.

```APIDOC
## pubky.startGrantAuthFlow(caps, kind, options)

### Description
Starts a grant authentication flow. Chooses delegated browser PoP keys when the runtime supports them, otherwise falls back to local PoP keys.

### Method
Async

### Parameters
- **caps** (string) - Required - Capabilities string.
- **kind** (AuthFlowKind) - Required - The auth flow kind (e.g., signin).
- **options** (object) - Optional - Additional options, e.g., clientId.

### Returns
- **flow** (AuthFlow) - The auth flow object.

### Example
```js
const flow = await pubky.startGrantAuthFlow(
  "/pub/example.com/:rw",
  AuthFlowKind.signin(),
  { clientId: "example.com" },
);
```
```

--------------------------------

### Initialize Data Directory with Docker

Source: https://github.com/pubky/pubky-homeserver/blob/main/docs/INSTALL.md

Runs the init command inside a Docker container, mounting the host's ~/.pubky directory to /root/.pubky. Requires the pubky-homeserver image.

```bash
docker run -it -v ~/.pubky:/root/.pubky pubky-homeserver homeserver init
```

--------------------------------

### Handle 404 RequestError in try-catch

Source: https://github.com/pubky/pubky-homeserver/blob/main/pubky-sdk/bindings/js/pkg/README.md

Example of catching a PubkyError from a publicStorage.getJson call and checking for a RequestError with a 404 statusCode. The code verifies the error data is an object with a numeric statusCode property before handling the not-found case.

```JavaScript
try {
  await publicStorage.getJson(`${pk}/pub/example.com/missing.json`);
} catch (e) {
  const error = e as PubkyError;
  if (
    error.name === "RequestError" &&
    typeof error.data === "object" &&
    error.data !== null &&
    "statusCode" in error.data &&
    typeof (error.data as { statusCode?: number }).statusCode === "number" &&
    (error.data as { statusCode?: number }).statusCode === 404
  ) {
    // handle not found
  }
}
```

--------------------------------

### Run browser session persistence example

Source: https://github.com/pubky/pubky-homeserver/blob/main/examples/javascript/README.md

Run the Vite app that creates disposable testnet accounts and demonstrates saving, listing, restoring, and forgetting multiple browser-backed Pubky sessions with browserSessionStore. Requires Node.js and npm.

```bash
cd 5-browser-session-persistence
npm install
npm run dev
```

--------------------------------

### Set log level with setLogLevel

Source: https://github.com/pubky/pubky-homeserver/blob/main/pubky-sdk/bindings/js/pkg/README.md

Call once at application start before constructing Pubky or other SDK actors. Throws if called again after the logger is initialized. Use 'debug' or 'trace' during development to see pkarr resolution, network requests, and storage operations.

```javascript
import { setLogLevel } from "@synonymdev/pubky";

setLogLevel("debug"); // "error" | "warn" | "info" | "debug" | "trace"
```

--------------------------------

### Set version and platform variables

Source: https://github.com/pubky/pubky-homeserver/blob/main/docs/INSTALL.md

Define the release version and platform before downloading. Adjust the platform for your OS and architecture.

```bash
PUBKY_VERSION=0.17.0
PUBKY_PLATFORM=linux-amd64  # or linux-arm64. Alternatively: osx-arm64, osx-amd64, windows-amd64
```

--------------------------------

### Import and use PubkyError and RequestErrorData

Source: https://github.com/pubky/pubky-homeserver/blob/main/pubky-sdk/bindings/js/pkg/README.md

Shows how to import the PubkyError and RequestErrorData types from the package. The example accesses 'reason' and 'statusCode' from the error's data when the error name is 'RequestError'. Note that Browser Fetch may only report 'Other' as the reason.

```TypeScript
import type { PubkyError, RequestErrorData } from "@synonymdev/pubky";

if (error.name === "RequestError") {
  const { reason, statusCode } = error.data as RequestErrorData;
}
```

--------------------------------

### Share Docker Postgres across tests with DockerPostgres::shared

Source: https://github.com/pubky/pubky-homeserver/blob/main/pubky-testnet/README.md

Share a single Docker Postgres container across multiple tests using DockerPostgres::shared(). Each testnet still gets its own ephemeral database, so tests remain isolated. This avoids the overhead of starting a separate container per test with .with_docker_postgres().

```rust
# #[cfg(feature = "docker-postgres")]
# mod docker_postgres_example {
use pubky_testnet::EphemeralTestnet;
use pubky_testnet::docker_postgres::DockerPostgres;

#[tokio::test]
async fn test_one() {
    let pg = DockerPostgres::shared().await;
    let testnet = EphemeralTestnet::builder()
        .postgres(pg.connection_string().unwrap())
        .build()
        .await
        .unwrap();
    // ... test code
}

#[tokio::test]
async fn test_two() {
    let pg = DockerPostgres::shared().await;
    let testnet = EphemeralTestnet::builder()
        .postgres(pg.connection_string().unwrap())
        .build()
        .await
        .unwrap();
    // ... test code
}
# }
```

--------------------------------

### signup-tokens generate syntax

Source: https://github.com/pubky/pubky-homeserver/blob/main/homeservercli/README.md

Shows the syntax for generating a signup invite token with optional quota overrides. Omitted flags fall back to system defaults.

```sh
homeservercli signup-tokens generate \
  [--storage-quota-mb <MB|unlimited>] \
  [--rate-read <rate>] \
  [--rate-write <rate>] \
  [--rate-read-burst <N>] \
  [--rate-write-burst <N>] \
  [--allowed-write-paths <PATH>]...
```

--------------------------------

### SessionStorage read/write operations

Source: https://github.com/pubky/pubky-homeserver/blob/main/pubky-sdk/bindings/js/pkg/README.md

Access the read/write session storage via `session.storage`. Supports writes (`putJson`, `putText`, `putBytes`, `putBlob`), reads, metadata, listing, and delete. `putBlob()` accepts a `Blob` or `File` without copying contents into WASM memory. `get()` exposes the underlying `Response` for streaming or header inspection.

```javascript
const s = session.storage;

// Writes
await s.putJson("/pub/example.com/data.json", { ok: true });
await s.putText("/pub/example.com/note.txt", "hello");
await s.putBytes("/pub/example.com/img.bin", new Uint8Array([1, 2, 3]));
await s.putBlob("/pub/example.com/file.bin", new Blob(["file contents"]));

// Reads
const response = await s.get("/pub/example.com/data.json"); // -> Response (stream it)
await s.getJson("/pub/example.com/data.json");
await s.getText("/pub/example.com/note.txt");
await s.getBytes("/pub/example.com/img.bin");

// Metadata
await s.exists("/pub/example.com/data.json");
await s.stats("/pub/example.com/data.json");

// Listing (session-scoped absolute dir)
await s.list("/pub/example.com/", null, false, 100, false);

// Delete
await s.delete("/pub/example.com/data.json");
```

--------------------------------

### Manage sessions with 8-session-management.mjs

Source: https://github.com/pubky/pubky-homeserver/blob/main/examples/javascript/README.md

Create, list, and delete grant-backed sessions from the command line. Defaults to ../sample_recovery.key with an empty passphrase. Listing and deleting sessions creates a temporary root-capability management session, then signs it out.

```bash
node 8-session-management.mjs --testnet list
node 8-session-management.mjs --testnet create
node 8-session-management.mjs --testnet create --client-id my-app.example
node 8-session-management.mjs --testnet delete <grant-id>
```

--------------------------------

### Direct sign-up with optional token: signupCookie(homeserver, null)

Source: https://github.com/pubky/pubky-homeserver/blob/main/docs/v0.10-migration/cookie-auth.md

If the signup token is optional, keep passing null or undefined as before.

```js
const session = await signer.signupCookie(homeserver, null);
```

--------------------------------

### Build local SDK package (npm run build)

Source: https://github.com/pubky/pubky-homeserver/blob/main/examples/javascript/README.md

Builds the local SDK package so that index.cjs and pubky_bg.wasm are available. Run this when the SDK package is missing or out of date.

```bash
cd pubky-sdk/bindings/js/pkg
npm run build
```

--------------------------------

### Create systemd service file

Source: https://github.com/pubky/pubky-homeserver/blob/main/docs/INSTALL.md

Opens a new systemd service file for editing with nano.

```bash
sudo nano /etc/systemd/system/pubky-homeserver.service
```

--------------------------------

### Pubky Auth URL example

Source: https://github.com/pubky/pubky-homeserver/blob/main/docs/AUTH.md

Example of a Pubky Auth URL with a specific relay, capabilities, and secret.

```text
pubkyauth:///
  ?relay=https://httprelay.pubky.app/inbox
  &caps=/pub/pubky.app/:rw,/pub/example.com/nested:rw
  &secret=mAa8kGmlrynGzQLteDVW6-WeUGnfvHTpEmbNerbWfPI

```
Tokens:
Raw