Run MeetCost Locally with Docker or Python Virtualenv

This guide takes you from a fresh clone to a working local deployment with real cost figures on screen — seeded with eight fictional employees and a handful of completed meetings so the reports have something in them from the first load. There are two paths: Docker (fewest prerequisites) and plain Python with a virtual environment. Pick the one that matches your setup; both land at the same place.

The local quickstart uses MEETCOST_ENVIRONMENT=development and MEETCOST_AUTH_MODE=dev, which enables the meetcost token command and relaxes some production checks. These modes are explicitly refused when MEETCOST_ENVIRONMENT=production. See Deployment for the production setup with Postgres and OIDC.

Prerequisites

Docker
Without Docker

Docker Desktop or Docker Engine with Compose v2
Git
jq (optional, for pretty-printing the API response)

Python 3.9 or later
Git
jq (optional, for pretty-printing the API response)

Setup

With Docker
Without Docker

Clone the repository

git clone https://github.com/meetcost/meetcost.git
cd meetcost

Create your environment file

Copy the example env file. You will fill in the encryption key in the next step.

cp .env.example .env

Generate an encryption key

Pay values are stored encrypted with AES-256-GCM under a key you supply. Generate one now and paste it into .env as MEETCOST_ENCRYPTION_KEY.

docker compose run --rm meetcost meetcost genkey

Open .env in your editor and set:

MEETCOST_ENCRYPTION_KEY=<paste the output here>

Start the service

docker compose up -d

The service will be available at http://localhost:8000.

Seed demo data

The seed-demo command creates eight fictional employees with pay records, assigns roles, and injects a few completed meetings so the reports pages are not empty.

docker compose exec meetcost meetcost seed-demo

Expected output:

Seeded 8 people, pay records, and 4 completed meetings.
Admin: ada@example.com — mint a token with: meetcost token ada@example.com

Open the admin UI

Visit http://localhost:8000/admin, click Get a development token, and enter ada@example.com. Ada is the seeded admin user.

Clone the repository

git clone https://github.com/meetcost/meetcost.git
cd meetcost

Create a virtual environment and install dependencies

python3 -m venv .venv
./.venv/bin/pip install -e ".[dev]"

This installs the meetcost CLI, the FastAPI service, and the development dependencies (pytest, ruff).

Create your environment file

cp .env.example .env

Generate an encryption key

Pay values are stored encrypted with AES-256-GCM under a key you supply. Generate one now and paste it into .env as MEETCOST_ENCRYPTION_KEY.

./.venv/bin/meetcost genkey

Open .env in your editor and set:

MEETCOST_ENCRYPTION_KEY=<paste the output here>

Seed demo data

The seed-demo command creates eight fictional employees with pay records, assigns roles, and injects a few completed meetings so the reports pages are not empty on first load.

./.venv/bin/meetcost seed-demo

Expected output:

Seeded 8 people, pay records, and 4 completed meetings.
Admin: ada@example.com — mint a token with: meetcost token ada@example.com

Start the service

./.venv/bin/meetcost serve

The service will be listening at http://localhost:8000. Leave this terminal running.

Get a development token

The meetcost token command mints a short-lived JWT signed with your MEETCOST_SECRET_KEY. It works only when MEETCOST_ENVIRONMENT is not production.

With Docker
Without Docker

docker compose exec meetcost meetcost token ada@example.com

./.venv/bin/meetcost token ada@example.com

This prints the token to stdout. The curl example below captures it into a shell variable in one step.

Development tokens are signed with a local secret and are not verified against an identity provider. They are refused entirely in production. Use MEETCOST_AUTH_MODE=oidc with your own OIDC issuer for any non-local deployment.

Call the estimate endpoint

With the service running and demo data seeded, ask for the cost of a one-hour weekly sync with all eight demo employees:

With Docker
Without Docker

TOKEN=$(docker compose exec meetcost meetcost token ada@example.com)

curl -s localhost:8000/api/v1/estimate \
  -H "Authorization: Bearer $TOKEN" -H 'Content-Type: application/json' \
  -d '{"invitees":["ada@example.com","bola@example.com","chen@example.com",
                   "dia@example.com","emeka@example.com","fatima@example.com",
                   "gus@example.com","hana@example.com"],
       "duration_minutes":60,"cadence":"weekly"}' | jq

TOKEN=$(./.venv/bin/meetcost token ada@example.com)

curl -s localhost:8000/api/v1/estimate \
  -H "Authorization: Bearer $TOKEN" -H 'Content-Type: application/json' \
  -d '{"invitees":["ada@example.com","bola@example.com","chen@example.com",
                   "dia@example.com","emeka@example.com","fatima@example.com",
                   "gus@example.com","hana@example.com"],
       "duration_minutes":60,"cadence":"weekly"}' | jq

The response includes the per-occurrence cost, the annualised total for the given cadence, and any configured nudges:

{
  "cost": { "visible": true, "total": "649.38", "currency": "USD", "headcount": 8 },
  "annualised_total": "33767.76",
  "nudges": [
    { "code": "cost_above_threshold",
      "message": "This meeting costs about USD 649. Could a written update do the same job?" },
    { "code": "annualised",
      "message": "At this cadence that is about USD 33,768 a year." }
  ]
}

The annualised figure — USD 33,768 in this example — is the number the product exists to surface. It is computed from per_occurrence_cost × occurrences_per_year for the given cadence. For weekly that is 52 occurrences. For a one_off cadence, annualised_total is omitted because an annual figure would be meaningless.

Understanding the response

Field	Meaning
`cost.total`	The total cost for one occurrence of this meeting at the given duration
`cost.currency`	The currency of all pay records consulted. A mixed-currency invitee list returns an error instead
`cost.headcount`	Number of invitees included in the calculation
`annualised_total`	`cost.total × occurrences_per_year` for the given cadence
`nudges`	Zero or more advisory messages triggered by configured thresholds (cost, headcount, duration)

Cadence values

The cadence field accepts: one_off, daily, weekdaily, weekly, biweekly, monthly, quarterly.

What the demo data looks like

seed-demo creates the following people and roles:

Email	Name	Team	Annual Pay (USD)	Role
ada@example.com	Ada Okonkwo	Engineering	165,000	admin
bola@example.com	Bola Mensah	Engineering	142,000	participant
chen@example.com	Chen Wei	Engineering	128,000	participant
dia@example.com	Dia Farrell	Product	151,000	team_lead
emeka@example.com	Emeka Nwosu	Product	118,000	participant
fatima@example.com	Fatima Rahman	Finance	134,000	finance
gus@example.com	Gus Lindqvist	Sales	97,000	participant
hana@example.com	Hana Suzuki	Sales	104,000	participant

It also injects three weekly all-hands meetings (from the past three weeks) and one monthly roadmap review, so the digests and reports endpoints return real data.

Assigning roles from the CLI

You can grant roles without going through the admin UI:

./.venv/bin/meetcost grant fatima@example.com finance
./.venv/bin/meetcost grant dia@example.com team_lead --team-id product

Valid roles are participant, organiser, team_lead, finance, and admin.

Running the tests

The test suite runs with no network access and completes in a few seconds:

./.venv/bin/pytest

The most important test is server/tests/test_no_egress.py, which asserts that the service makes no outbound connections to any host that is not in the configured egress allowlist — this is the test that keeps the data-residency claim honest.

Next steps

Production Deployment

Switch to Postgres, configure OIDC against your identity provider, supply an encryption key from your secret manager, and deploy with the provided Helm chart.

Architecture

Understand the four-layer code structure, storage schema, boot sequence, and extension points.

Permissions

Full detail on the role model, salary-inference protections, and the small-meeting rounding rules.

Adapters

Connect a directory provider (Google, Microsoft), an attendance collector, or an HRIS for automated pay data sync.

Get Started

Deployment

Features

Privacy & Security

Integrations

Run MeetCost Locally with Docker or Python Virtualenv

Prerequisites

Setup

Get a development token

Call the estimate endpoint

Understanding the response

Cadence values

What the demo data looks like

Assigning roles from the CLI

Running the tests

Next steps

Production Deployment

Architecture

Permissions

Adapters

​Prerequisites

​Setup

​Get a development token

​Call the estimate endpoint

​Understanding the response

​Cadence values

​What the demo data looks like

​Assigning roles from the CLI

​Running the tests

​Next steps

Production Deployment

Architecture

Permissions

Adapters

Prerequisites

Setup

Get a development token

Call the estimate endpoint

Understanding the response

Cadence values

What the demo data looks like

Assigning roles from the CLI

Running the tests

Next steps