Skip to main content

Quickstart

At the end of this quickstart, you have a local Priompt server and you've seen how an agent fetches a prompt and hears about changes. In this quickstart, you start the server, fetch a demo prompt from Python or Node, and publish two changes while a subscriber watches. It takes about ten minutes.

The video shows a similar tour of the priompt CLI in a terminal.

Prerequisites​

Before you begin, make sure you have:

  • Docker, or Go 1.25 or later: to run the server. Get them from Docker or go.dev/dl.
  • Python 3.9 or later, or Node 20 or later: to run the client.
  • bash or zsh: the shell commands use it. On Windows, use Git Bash or WSL.

1. Start the server​

On its first start, the server stores a demo prompt at the address priompt://acme/onboarding/welcome, so there's something to fetch right away.

To start the server in Docker:

  1. Run the published image:

    docker run -d --name priompt -p 8443:8443 -v priompt-data:/data ghcr.io/priompt/priompt

    The server listens on port 8443 and keeps its database in the priompt-data volume. The Production checklist covers what to change for a real server.

  2. Check the log:

    docker logs priompt
    Output
    2026/10/18 18:24:45 seeded demo prompt priompt://acme/onboarding/welcome
    2026/10/18 18:24:45 priompt v0.7.4 (b9072abfc4b0fb10f8e42ac1316fd4ea12462797) serving on :8443 (tls=false mtls=false auth=0-token cache=mem embed=lexical(offline) nats=127.0.0.1:4222 metrics=:2112 ratelimit=0/s)
    2026/10/18 18:24:45 metrics on :2112/metrics

2. Fetch a prompt​

An agent fetches a prompt by its address and fills in its slots, the named placeholders such as {name} that your app supplies. See Prompts and addresses for the address format.

To fetch the demo prompt from Python:

  1. Install the SDK:

    pip install priompt-sdk

  2. Save this script as quickstart.py:

    quickstart.py
    from priompt_sdk import PromptClient

    client = PromptClient(host="localhost:8443")
    prompt = client.get("priompt://acme/onboarding/welcome")
    print(prompt.template.format(name="Ada", org="Acme"))
    print(prompt.version_hash[:12])

  3. Run it:

    python quickstart.py
    Output
    Hi Ada, welcome to Acme!

    22e5cc10ac0f

The blank line comes from the template, which ends with a newline. The version hash identifies this exact content. It changes with every publish that changes the content.

3. Publish a change and watch it arrive​

Agents learn about a change by subscribing to the prompt. Each change event carries the new version hash and a semantic verdict, a label for how far the edit changes the prompt's meaning. See Semantic diff for how Priompt computes it. In this step, priompt watch plays the subscribing agent.

To publish two changes and watch them arrive:

  1. In a new terminal, subscribe to the prompt:

    docker exec priompt priompt watch -uri priompt://acme/onboarding/welcome
    Output
    2026/10/18 00:42:22 watching priompt://acme/onboarding/welcome on nats://127.0.0.1:4222

    Leave it running.

  2. In another terminal, publish a rewrite of the prompt:

    echo 'You are the onboarding guide for {org}. Greet {name}, then list three first steps.' |
      docker exec -i priompt priompt publish -uri priompt://acme/onboarding/welcome -file - -slot name -slot org
    Output
    published priompt://acme/onboarding/welcome (ff8d89cbc0e6) — subscribers notified

    -file - reads the template from standard input, and each -slot declares a slot the template uses. The watch terminal prints the change with the verdict structural:

    Output
    2026/10/18 00:42:41 priompt://acme/onboarding/welcome updated -> ff8d89cbc0e627cc748eb9b901a2852585cabbca87d29922bf178911a7e58b6f [structural]

  3. Publish a one-word tweak of the new text:

    echo 'You are the onboarding guide for {org}. Greet {name} warmly, then list three first steps.' |
      docker exec -i priompt priompt publish -uri priompt://acme/onboarding/welcome -file - -slot name -slot org
    Output
    published priompt://acme/onboarding/welcome (9025ffc1be53) — subscribers notified

    The watch terminal prints the verdict minor edit:

    Output
    2026/10/18 00:42:42 priompt://acme/onboarding/welcome updated -> 9025ffc1be53511a820a65ef3aaef9d3c6970444787353febfdab05d183a5d4b [minor edit]

An agent can reload a minor edit on its own and hold a structural change for a person to review.

4. Try to publish a broken prompt​

Priompt validates every prompt before it stores it. A template may use only the slots it declares, and every declared slot must appear in the template.

To see validation reject a prompt:

  1. Publish a template that uses {org} without declaring it:

    echo 'Hi {name}, welcome to {org}!' |
      docker exec -i priompt priompt publish -uri priompt://acme/onboarding/welcome -file - -slot name
    Output
    2026/10/18 00:42:44 rpc error: code = InvalidArgument desc = invalid prompt: template uses undeclared slots: org

    The command exits with status 1, and the server stores nothing.

  2. List the served prompts:

    docker exec priompt priompt list
    Output
    priompt://acme/onboarding/welcome	9025ffc1be53

    The served version is still the one from your last successful publish.

warning

This server accepts requests from anyone who can reach it, because no tokens are configured. Keep it on your own machine. Before you expose a server, follow the Production checklist.

Clean up​

To remove the server and its data:

  1. Stop the watch with Ctrl+C.

  2. Delete the container and its volume:

    docker rm -f priompt
    docker volume rm priompt-data
    Output
    priompt
    priompt-data

Next steps​