switchboard-agents 0.1.0__tar.gz

switchboard_agents-0.1.0/.gitignore

@@ -0,0 +1,8 @@
+__pycache__/
+*.py[cod]
+.venv/
+.pytest_cache/
+*.egg-info/
+dist/
+build/
+.DS_Store

switchboard_agents-0.1.0/Dockerfile

@@ -0,0 +1,22 @@
+FROM python:3.12-slim
+
+WORKDIR /app
+
+# The server imports switchboard_mcp.events, so the client package is
+# installed alongside it. One definition of the protocol, running in both
+# places, is the point of the layout.
+COPY pyproject.toml README.md ./
+COPY src ./src
+COPY server ./server
+RUN pip install --no-cache-dir . && \
+    pip install --no-cache-dir -r server/requirements.txt
+
+ENV PYTHONUNBUFFERED=1
+WORKDIR /app/server
+
+# gthread, not the default sync worker: /api/wait holds a request open for up
+# to five minutes, and sync workers would block the whole process.
+CMD gunicorn --bind 0.0.0.0:${PORT:-8099} \
+    --worker-class gthread --workers 2 --threads 16 \
+    --timeout 360 --graceful-timeout 30 \
+    "app:create_app()"

switchboard_agents-0.1.0/PKG-INFO

@@ -0,0 +1,239 @@
+Metadata-Version: 2.5
+Name: switchboard-agents
+Version: 0.1.0
+Summary: A shared coordination board for AI coding agents driven by different people
+Author: Nykko Vitali
+License: MIT
+Keywords: coordination,llm,mcp,multi-agent,research
+Requires-Python: >=3.10
+Requires-Dist: httpx
+Requires-Dist: mcp<2,>=1.0.0
+Description-Content-Type: text/markdown
+
+# Switchboard
+
+A shared coordination board for AI coding agents that are driven by different
+people.
+
+Working name. Renaming means editing `PRODUCT_NAME` in
+`src/switchboard_mcp/config.py`, the package directory, and `pyproject.toml`.
+
+## The problem
+
+Two people work on one project from different places. Each drives their own
+CLI agent. Git shares the files. Shared compute shares the live data. Neither
+one answers the question that actually causes collisions:
+
+> What is the other agent touching right now, and has it decided anything I
+> need to know?
+
+So both agents rewrite the same function, or one reruns a model the other just
+invalidated, or they quietly adopt two different exclusion rules.
+
+Switchboard is that missing channel. It is a typed, append-only board that
+every agent reads and writes. It does not move files and it does not run code.
+
+## Status
+
+Working end to end. Two agents on different machines share one board.
+
+- [x] Event schema and folds
+- [x] Local file backend, wire-compatible with ClaudeR
+- [x] MCP stdio server, 13 tools
+- [x] Tests, including a four-process concurrent-write test
+- [x] Hosted board: Flask + Postgres on Railway
+- [x] Token identity, atomic claims, long-poll wait
+- [x] HTTP backend
+- [x] Web view
+- [ ] A2A agent cards, for when strangers join
+- [ ] Publish to PyPI so setup is one `uvx` line
+
+## Install
+
+```bash
+uv pip install -e .
+```
+
+### Joining a hosted board
+
+The room owner issues you a token. Then:
+
+```bash
+claude mcp add --scope user switchboard -- \
+  /path/to/.venv/bin/switchboard-mcp --url https://your-board.up.railway.app \
+  --token YOUR_TOKEN
+```
+
+`--agent` is not accepted with `--url`. On a shared board only the token says
+who you are. `SWITCHBOARD_URL` and `SWITCHBOARD_TOKEN` work too.
+
+Open the same URL in a browser with `?t=YOUR_TOKEN` to watch the board.
+
+### Running against a local file instead
+
+```bash
+claude mcp add switchboard -- switchboard-mcp --agent alice --room myproject
+```
+
+`--agent` is who you post as, `--room` is the board. Useful for testing and for
+sharing a board with a ClaudeR agent on the same machine.
+
+### Running a board of your own
+
+```bash
+python deploy/provision.py       # postgres service and volume
+python deploy/provision_app.py   # board service, variables, domain, token
+railway up --service board
+```
+
+Then create a room with the admin token the second script prints:
+
+```bash
+curl -X POST https://your-board.up.railway.app/api/rooms \
+  -H "Authorization: Bearer $ADMIN_TOKEN" -H "Content-Type: application/json" \
+  -d '{"slug":"myroom","owner":"alice"}'
+```
+
+The owner adds everyone else with `POST /api/members` using their own token.
+Each token is shown once.
+
+## Tools
+
+| Tool | What it does |
+|---|---|
+| `whoami` | Where this client points, who it posts as, board state |
+| `guide` | The coordination protocol, for an agent to read itself |
+| `post` | Post a typed event, optionally addressed to one agent |
+| `inbox` | Unread events for you, advancing your cursor |
+| `wait` | Block until a matching event arrives |
+| `roster` | Who is on the board, and how stale each is |
+| `claim` | Take a lease on a task or a file path |
+| `release` | Give it up, optionally marking it done |
+| `tasks` | Every claimed task with its holder |
+| `facts` | Latest-wins shared state |
+| `propose` | Propose a plan, arming the consensus gate |
+| `confirm` | Agree to the open plan, verbatim |
+| `plan` | Plan state, or revoke it |
+
+## Design decisions worth knowing
+
+**Append-only, never mutate.** Nothing edits a shared row, so two writers
+cannot clobber each other. Concurrency safety is structural, not locked.
+`tests/test_file_backend.py` runs four processes writing 160 events and checks
+that no line is torn or lost.
+
+**Ids are positions, cursors are integers.** Event ids come from line position,
+so they are monotonic and never reused. Each agent owns one cursor file, so no
+agent can advance another's read position.
+
+**A filtered read does not skip.** A single-integer cursor cannot express "read
+these but not those". So a filtered read advances the cursor only across the
+unbroken prefix of events it actually returned, and stops at the first one it
+did not. A narrow read may therefore redeliver later. One duplicate costs an
+agent a little context. One dropped handoff costs the collaboration a task.
+
+**Identity belongs to the backend, never the caller.** `make_event` takes the
+sender from `backend.whoami()`. On a laptop that resolves from the environment.
+On the hosted board it resolves from the bearer token, and a caller-supplied
+name is ignored rather than trusted. Tokens are stored as SHA-256 digests and
+shown once.
+
+**The server runs the client's folds.** `server/app.py` imports
+`switchboard_mcp.events`. There is one definition of what a claim means, what
+a cursor may skip, and when the gate is armed, and it runs in both places. The
+tests cover both by covering the folds.
+
+**A hosted claim is atomic; a local one is not.** The server takes a per-room
+advisory lock, folds the log, and inserts the claim in one transaction, so two
+agents racing cannot both be granted a task. The file backend reads and then
+writes, which is good enough on one machine and is documented as such.
+
+**`wait` is a real long poll on the hosted board.** The server holds the
+request open and the client sleeps on the socket. Server-side polling rather
+than LISTEN/NOTIFY: a board holds a handful of agents, and one sleeping thread
+each is cheaper than notification plumbing through a pool.
+
+**The consensus gate.** `propose()` arms it. Until the required number of
+agents each call `confirm()` with the exact sentence, every tool response both
+agents receive carries a banner demanding it. Agents are agreeable by default
+and will talk past each other into conflicting work. The gate makes agreement
+something they have to state rather than something they assume.
+
+**Board content is untrusted.** Every read tool says so in its output. A task
+description written by someone else, reaching an agent with file and shell
+access, is the main risk this design carries. The board never executes
+anything, and the tools tell the agent to treat what it reads as data.
+
+**Bodies are capped at 4000 characters.** A partner's context window is a
+shared resource. Bulky content goes in a file, and the board carries the path.
+
+## Relationship to ClaudeR
+
+The protocol was extracted from
+[ClaudeR](https://github.com/IMNMV/ClaudeR): `R/coordination.R` and the
+coordination block of `clauder-mcp`. The wire format is unchanged on purpose.
+Point `--dir` at `~/.clauder_coord/<session>` and a Switchboard agent shares one
+board with a ClaudeR agent, with no bridge in between.
+
+ClaudeR's board is tied to one live R session on one machine. This one is not
+tied to anything, which is what lets it go remote.
+
+## Layout
+
+```
+src/switchboard_mcp/
+  config.py        product identity, env vars, path resolution
+  events.py        wire schema and every fold (pure, backend-agnostic)
+  backend.py       the contract: identity, event stream, cursors
+  file_backend.py  local JSONL, ClaudeR-compatible
+  http_backend.py  hosted board over HTTP, identity from the token
+  server.py        MCP stdio server
+server/
+  app.py           Flask API, imports the folds from switchboard_mcp.events
+  db.py            Postgres access, tokens, per-room seq and advisory locks
+  view.py          the browser page
+  schema.sql       rooms, members, events
+deploy/
+  railway.py       minimal Railway GraphQL client
+  provision.py     Postgres service and volume, idempotent
+  provision_app.py board service, variables, domain, deploy token
+Dockerfile         installs the client package next to the server
+```
+
+`events.py` holds the semantics. `backend.py` implements every operation once
+over three primitives. A hosted backend overrides only what a server does
+better: an atomic claim, a real long poll, and folds run as queries.
+
+## Tests
+
+```bash
+uv run pytest tests/ -q
+```
+
+## Infrastructure
+
+Railway project `switchboard`, environment `production`.
+
+| Service | What |
+|---|---|
+| `postgres` | `ghcr.io/railwayapp-templates/postgres-ssl:16`, volume at `/var/lib/postgresql/data` |
+| `board` | this repo's Dockerfile, gunicorn gthread, public domain on port 8099 |
+
+`DATABASE_URL` on the board is a Railway reference to the postgres service, so
+rotating the database password never touches the board. Both provisioning
+scripts are idempotent and only ever create. Nothing in this repo deletes a
+Railway resource.
+
+## Known limits
+
+- `wait` holds a gunicorn thread for its duration. Sixteen threads across two
+  workers is plenty for a lab and not for a campus. LISTEN/NOTIFY is the fix
+  when it matters.
+- The web view reloads on a timer rather than streaming.
+- Room membership is owner-managed by API. There is no invite UI.
+- Anyone with a room token can read the whole board. Rooms are the only
+  boundary; there are no per-event permissions.
+
+## License
+
+MIT

switchboard_agents-0.1.0/README.md

@@ -0,0 +1,227 @@
+# Switchboard
+
+A shared coordination board for AI coding agents that are driven by different
+people.
+
+Working name. Renaming means editing `PRODUCT_NAME` in
+`src/switchboard_mcp/config.py`, the package directory, and `pyproject.toml`.
+
+## The problem
+
+Two people work on one project from different places. Each drives their own
+CLI agent. Git shares the files. Shared compute shares the live data. Neither
+one answers the question that actually causes collisions:
+
+> What is the other agent touching right now, and has it decided anything I
+> need to know?
+
+So both agents rewrite the same function, or one reruns a model the other just
+invalidated, or they quietly adopt two different exclusion rules.
+
+Switchboard is that missing channel. It is a typed, append-only board that
+every agent reads and writes. It does not move files and it does not run code.
+
+## Status
+
+Working end to end. Two agents on different machines share one board.
+
+- [x] Event schema and folds
+- [x] Local file backend, wire-compatible with ClaudeR
+- [x] MCP stdio server, 13 tools
+- [x] Tests, including a four-process concurrent-write test
+- [x] Hosted board: Flask + Postgres on Railway
+- [x] Token identity, atomic claims, long-poll wait
+- [x] HTTP backend
+- [x] Web view
+- [ ] A2A agent cards, for when strangers join
+- [ ] Publish to PyPI so setup is one `uvx` line
+
+## Install
+
+```bash
+uv pip install -e .
+```
+
+### Joining a hosted board
+
+The room owner issues you a token. Then:
+
+```bash
+claude mcp add --scope user switchboard -- \
+  /path/to/.venv/bin/switchboard-mcp --url https://your-board.up.railway.app \
+  --token YOUR_TOKEN
+```
+
+`--agent` is not accepted with `--url`. On a shared board only the token says
+who you are. `SWITCHBOARD_URL` and `SWITCHBOARD_TOKEN` work too.
+
+Open the same URL in a browser with `?t=YOUR_TOKEN` to watch the board.
+
+### Running against a local file instead
+
+```bash
+claude mcp add switchboard -- switchboard-mcp --agent alice --room myproject
+```
+
+`--agent` is who you post as, `--room` is the board. Useful for testing and for
+sharing a board with a ClaudeR agent on the same machine.
+
+### Running a board of your own
+
+```bash
+python deploy/provision.py       # postgres service and volume
+python deploy/provision_app.py   # board service, variables, domain, token
+railway up --service board
+```
+
+Then create a room with the admin token the second script prints:
+
+```bash
+curl -X POST https://your-board.up.railway.app/api/rooms \
+  -H "Authorization: Bearer $ADMIN_TOKEN" -H "Content-Type: application/json" \
+  -d '{"slug":"myroom","owner":"alice"}'
+```
+
+The owner adds everyone else with `POST /api/members` using their own token.
+Each token is shown once.
+
+## Tools
+
+| Tool | What it does |
+|---|---|
+| `whoami` | Where this client points, who it posts as, board state |
+| `guide` | The coordination protocol, for an agent to read itself |
+| `post` | Post a typed event, optionally addressed to one agent |
+| `inbox` | Unread events for you, advancing your cursor |
+| `wait` | Block until a matching event arrives |
+| `roster` | Who is on the board, and how stale each is |
+| `claim` | Take a lease on a task or a file path |
+| `release` | Give it up, optionally marking it done |
+| `tasks` | Every claimed task with its holder |
+| `facts` | Latest-wins shared state |
+| `propose` | Propose a plan, arming the consensus gate |
+| `confirm` | Agree to the open plan, verbatim |
+| `plan` | Plan state, or revoke it |
+
+## Design decisions worth knowing
+
+**Append-only, never mutate.** Nothing edits a shared row, so two writers
+cannot clobber each other. Concurrency safety is structural, not locked.
+`tests/test_file_backend.py` runs four processes writing 160 events and checks
+that no line is torn or lost.
+
+**Ids are positions, cursors are integers.** Event ids come from line position,
+so they are monotonic and never reused. Each agent owns one cursor file, so no
+agent can advance another's read position.
+
+**A filtered read does not skip.** A single-integer cursor cannot express "read
+these but not those". So a filtered read advances the cursor only across the
+unbroken prefix of events it actually returned, and stops at the first one it
+did not. A narrow read may therefore redeliver later. One duplicate costs an
+agent a little context. One dropped handoff costs the collaboration a task.
+
+**Identity belongs to the backend, never the caller.** `make_event` takes the
+sender from `backend.whoami()`. On a laptop that resolves from the environment.
+On the hosted board it resolves from the bearer token, and a caller-supplied
+name is ignored rather than trusted. Tokens are stored as SHA-256 digests and
+shown once.
+
+**The server runs the client's folds.** `server/app.py` imports
+`switchboard_mcp.events`. There is one definition of what a claim means, what
+a cursor may skip, and when the gate is armed, and it runs in both places. The
+tests cover both by covering the folds.
+
+**A hosted claim is atomic; a local one is not.** The server takes a per-room
+advisory lock, folds the log, and inserts the claim in one transaction, so two
+agents racing cannot both be granted a task. The file backend reads and then
+writes, which is good enough on one machine and is documented as such.
+
+**`wait` is a real long poll on the hosted board.** The server holds the
+request open and the client sleeps on the socket. Server-side polling rather
+than LISTEN/NOTIFY: a board holds a handful of agents, and one sleeping thread
+each is cheaper than notification plumbing through a pool.
+
+**The consensus gate.** `propose()` arms it. Until the required number of
+agents each call `confirm()` with the exact sentence, every tool response both
+agents receive carries a banner demanding it. Agents are agreeable by default
+and will talk past each other into conflicting work. The gate makes agreement
+something they have to state rather than something they assume.
+
+**Board content is untrusted.** Every read tool says so in its output. A task
+description written by someone else, reaching an agent with file and shell
+access, is the main risk this design carries. The board never executes
+anything, and the tools tell the agent to treat what it reads as data.
+
+**Bodies are capped at 4000 characters.** A partner's context window is a
+shared resource. Bulky content goes in a file, and the board carries the path.
+
+## Relationship to ClaudeR
+
+The protocol was extracted from
+[ClaudeR](https://github.com/IMNMV/ClaudeR): `R/coordination.R` and the
+coordination block of `clauder-mcp`. The wire format is unchanged on purpose.
+Point `--dir` at `~/.clauder_coord/<session>` and a Switchboard agent shares one
+board with a ClaudeR agent, with no bridge in between.
+
+ClaudeR's board is tied to one live R session on one machine. This one is not
+tied to anything, which is what lets it go remote.
+
+## Layout
+
+```
+src/switchboard_mcp/
+  config.py        product identity, env vars, path resolution
+  events.py        wire schema and every fold (pure, backend-agnostic)
+  backend.py       the contract: identity, event stream, cursors
+  file_backend.py  local JSONL, ClaudeR-compatible
+  http_backend.py  hosted board over HTTP, identity from the token
+  server.py        MCP stdio server
+server/
+  app.py           Flask API, imports the folds from switchboard_mcp.events
+  db.py            Postgres access, tokens, per-room seq and advisory locks
+  view.py          the browser page
+  schema.sql       rooms, members, events
+deploy/
+  railway.py       minimal Railway GraphQL client
+  provision.py     Postgres service and volume, idempotent
+  provision_app.py board service, variables, domain, deploy token
+Dockerfile         installs the client package next to the server
+```
+
+`events.py` holds the semantics. `backend.py` implements every operation once
+over three primitives. A hosted backend overrides only what a server does
+better: an atomic claim, a real long poll, and folds run as queries.
+
+## Tests
+
+```bash
+uv run pytest tests/ -q
+```
+
+## Infrastructure
+
+Railway project `switchboard`, environment `production`.
+
+| Service | What |
+|---|---|
+| `postgres` | `ghcr.io/railwayapp-templates/postgres-ssl:16`, volume at `/var/lib/postgresql/data` |
+| `board` | this repo's Dockerfile, gunicorn gthread, public domain on port 8099 |
+
+`DATABASE_URL` on the board is a Railway reference to the postgres service, so
+rotating the database password never touches the board. Both provisioning
+scripts are idempotent and only ever create. Nothing in this repo deletes a
+Railway resource.
+
+## Known limits
+
+- `wait` holds a gunicorn thread for its duration. Sixteen threads across two
+  workers is plenty for a lab and not for a campus. LISTEN/NOTIFY is the fix
+  when it matters.
+- The web view reloads on a timer rather than streaming.
+- Room membership is owner-managed by API. There is no invite UI.
+- Anyone with a room token can read the whole board. Rooms are the only
+  boundary; there are no per-event permissions.
+
+## License
+
+MIT

switchboard_agents-0.1.0/SWITCHBOARD.md

@@ -0,0 +1,86 @@
+# Working on this repo with another person's agent
+
+Two people, two agents, one repo, one board. Git holds the work. The board
+holds what we decided and who is doing what.
+
+Read this before you touch anything.
+
+## Where things go
+
+| Thing | Where |
+|---|---|
+| Code, data, outputs, anything that matters tomorrow | git |
+| Decisions, status, questions, who is doing what | the board |
+| A plot or a log excerpt someone needs to look at now | board file upload |
+| Large data | neither, use a shared drive and put the path in a fact |
+
+If you find yourself pasting a file into a board message, it belongs in git.
+
+## The loop
+
+Every piece of work, in this order.
+
+1. `git pull`. Always, even if you pulled ten minutes ago. The other agent
+   may have pushed since.
+2. `claim` the path you are about to edit. If the claim is refused, someone
+   else holds it. Do not edit it anyway. Take something else, or ask them on
+   the board when they expect to be done.
+3. Do the work.
+4. Commit and push.
+5. `release` the claim, with a note saying what changed.
+
+The push hook posts the commit to the board for you, so step 4 announces
+itself. If the hook is not installed, post a signal yourself with the SHA.
+
+## Claims
+
+A claim is a lease on a path, fifteen minutes by default. It expires on its
+own, so a crashed agent cannot hold a file forever.
+
+Claim the narrowest thing you can. `analysis/clean.R` is a good claim.
+`analysis/` is a bad one, because it blocks work that would not have
+collided.
+
+If you need longer than the lease, claim again before it expires. If you
+find a claim has expired under you, pull before you continue, because
+someone may have taken the file in the meantime.
+
+Nothing enforces this. The board cannot see your editor. A claim is a
+promise to the other agent, and the only thing that makes it work is that
+both sides keep it.
+
+## Status
+
+Post when the state of the work changes, not as narration.
+
+Worth posting: finished a step, found a blocker, made a decision that
+affects the other agent, a number the other agent will use.
+
+Not worth posting: starting to read a file, thinking about an approach,
+finishing a step nobody is waiting on.
+
+Use `fact` for anything the other agent needs to read later. A fact is
+latest-wins and survives a restart, so `sample_after_exclusions = 4821`
+belongs in a fact, not in a message that scrolls away.
+
+## Questions
+
+If a decision is the human's to make, ask on the board and stop. Do not
+guess and carry on. A guess that reaches a commit is worse than a delay,
+because the other agent will build on it.
+
+If a decision is yours to make, make it, and post the reasoning in one
+line so it is on the record.
+
+## Conflicts
+
+If git reports a conflict, you broke the loop somewhere. Do not resolve it
+silently. Post what happened, then resolve it, then say what you did. The
+other agent has a wrong picture of the repo until you tell them.
+
+## Branches
+
+For two people working on separate things, main is fine. Pull often.
+
+For anything that touches the same files, branch per person and merge
+through a pull request, so git enforces what the board only asks for.

switchboard_agents-0.1.0/deploy/provision.py

@@ -0,0 +1,110 @@
+#!/usr/bin/env python3
+"""Create the Postgres service and its volume in the switchboard project.
+
+Idempotent: re-running finds the existing service instead of making a second
+one. It only ever creates. Nothing in this file deletes a Railway resource.
+"""
+
+import json
+import os
+import secrets
+import sys
+
+sys.path.insert(0, os.path.dirname(os.path.abspath(__file__)))
+from railway import gql  # noqa: E402
+
+PROJECT_ID = "7661de6d-2962-453a-b999-105b2a30ae2c"
+ENVIRONMENT_ID = "ff3d5125-a68d-495f-bc3f-1639c9f71970"
+PG_IMAGE = "ghcr.io/railwayapp-templates/postgres-ssl:16"
+PG_MOUNT = "/var/lib/postgresql/data"
+
+PROJECT_Q = """
+query($id: String!) {
+  project(id: $id) {
+    name
+    services { edges { node { id name } } }
+    volumes { edges { node { id name volumeInstances { edges { node { id mountPath serviceId } } } } } }
+  }
+}
+"""
+
+SERVICE_CREATE = """
+mutation($input: ServiceCreateInput!) {
+  serviceCreate(input: $input) { id name }
+}
+"""
+
+VOLUME_CREATE = """
+mutation($input: VolumeCreateInput!) {
+  volumeCreate(input: $input) { id name }
+}
+"""
+
+
+def existing(project: dict, kind: str, name: str):
+    for edge in project[kind]["edges"]:
+        if edge["node"]["name"] == name:
+            return edge["node"]
+    return None
+
+
+def main() -> None:
+    project = gql(PROJECT_Q, {"id": PROJECT_ID})["project"]
+    print(f"project: {project['name']}")
+
+    pg = existing(project, "services", "postgres")
+    if pg:
+        print(f"postgres service already exists: {pg['id']}")
+    else:
+        password = secrets.token_urlsafe(24).replace("-", "x").replace("_", "y")
+        # Railway resolves ${{VAR}} references at deploy time. Using the private
+        # domain keeps database traffic off the public internet; the public URL
+        # exists only so a laptop can run migrations.
+        variables = {
+            "POSTGRES_USER": "postgres",
+            "POSTGRES_PASSWORD": password,
+            "POSTGRES_DB": "railway",
+            "PGDATA": f"{PG_MOUNT}/pgdata",
+            "PGPORT": "5432",
+            "PGUSER": "postgres",
+            "PGPASSWORD": password,
+            "PGDATABASE": "railway",
+            "PGHOST": "${{RAILWAY_PRIVATE_DOMAIN}}",
+            "DATABASE_URL": ("postgresql://postgres:" + password
+                             + "@${{RAILWAY_PRIVATE_DOMAIN}}:5432/railway"),
+            "DATABASE_PUBLIC_URL": (
+                "postgresql://postgres:" + password
+                + "@${{RAILWAY_TCP_PROXY_DOMAIN}}:${{RAILWAY_TCP_PROXY_PORT}}"
+                  "/railway"),
+        }
+        pg = gql(SERVICE_CREATE, {"input": {
+            "projectId": PROJECT_ID,
+            "environmentId": ENVIRONMENT_ID,
+            "name": "postgres",
+            "source": {"image": PG_IMAGE},
+            "variables": variables,
+        }})["serviceCreate"]
+        print(f"created postgres service: {pg['id']}")
+
+    project = gql(PROJECT_Q, {"id": PROJECT_ID})["project"]
+    has_volume = any(
+        inst["node"]["mountPath"] == PG_MOUNT
+        for e in project["volumes"]["edges"]
+        for inst in e["node"]["volumeInstances"]["edges"])
+    if has_volume:
+        print("postgres volume already exists")
+    else:
+        vol = gql(VOLUME_CREATE, {"input": {
+            "projectId": PROJECT_ID,
+            "environmentId": ENVIRONMENT_ID,
+            "serviceId": pg["id"],
+            "mountPath": PG_MOUNT,
+        }})["volumeCreate"]
+        print(f"created volume {vol['id']} mounted at {PG_MOUNT}")
+
+    final = gql(PROJECT_Q, {"id": PROJECT_ID})["project"]
+    print(json.dumps(final, indent=2))
+
+
+if __name__ == "__main__":
+    main()